OpenClawヘッドレスブラウザ統合ガイド

はじめに

AIエージェントはしばしばWebページとのインタラクションが必要になります——ページ内容の取得、フォームの入力、スクリーンショットの撮影、さらには複雑なブラウザ自動化タスクの実行など。OpenClaw にはヘッドレスブラウザ（Headless Browser）統合機能が内蔵されており、Chromiumカーネルをベースに、Pi Agent SDKのbrowserツールを通じて完全なWebページ操作機能を提供します。

本記事では、OpenClaw のヘッドレスブラウザ機能の設定と使用方法、およびBridge URLの仕組みについて解説します。

Browserツールの有効化

基本設定

{
  agents: {
    "my-agent": {
      tools: {
        browser: {
          enabled: true,
          // ブラウザエンジン
          engine: "chromium",
          // ヘッドレスモード
          headless: true,
          // ブラウザ起動引数
          launchArgs: [
            "--no-sandbox",
            "--disable-gpu",
            "--disable-dev-shm-usage"
          ],
          // デフォルトビューポートサイズ
          viewport: {
            width: 1280,
            height: 720
          },
          // ページ読み込みタイムアウト（ミリ秒）
          timeout: 30000
        }
      }
    }
  }
}

Docker環境の特別設定

Docker内で実行する場合、Chromiumの依存関係がインストールされていることを確認する必要があります。

FROM openclaw/gateway:latest

# Chromium依存関係のインストール
RUN apt-get update && apt-get install -y \
    chromium \
    fonts-noto-cjk \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

または、ブラウザサポート付きのプリビルドイメージを使用できます。

services:
  openclaw:
    image: openclaw/gateway:latest-browser
    environment:
      - OPENCLAW_BROWSER_ENABLED=true

Browserツールの機能

AIエージェントはbrowserツールを通じて以下の操作を実行できます。

1. ページナビゲーションとコンテンツ抽出

ユーザー：Hacker Newsの今日の人気記事を確認して

AI内部実行：
→ browser.navigate("https://news.ycombinator.com")
→ browser.extract({ selector: ".titleline > a", fields: ["text", "href"] })
→ 抽出結果をユーザーに返す

2. ページスクリーンショット

ユーザー：GitHub trendingページのスクリーンショットを撮って

AI内部実行：
→ browser.navigate("https://github.com/trending")
→ browser.screenshot({ fullPage: false })
→ 画像としてユーザーに送信

3. フォーム操作

ユーザー：そのサイトで "OpenClaw" を検索して

AI内部実行：
→ browser.navigate("https://example.com")
→ browser.fill({ selector: "#search-input", value: "OpenClaw" })
→ browser.click({ selector: "#search-button" })
→ browser.waitForNavigation()
→ browser.extract({ selector: ".results" })

4. JavaScript実行

AI内部実行：
→ browser.evaluate("document.title")
→ browser.evaluate("document.querySelectorAll('a').length")

Bridge URLメカニズム

Bridge URLはOpenClawの独自機能で、AIエージェントのブラウザセッションをユーザーに「ブリッジ」し、ユーザーがブラウザで直接Webページを操作できるようにします。

仕組み

1. AIエージェントがヘッドレスブラウザでページを開く
2. OpenClawがBridge URLを生成する
3. ユーザーがBridge URLをクリックして自分のブラウザで開く
4. ユーザーにはエージェントのブラウザセッションのリアルタイムミラーが表示される
5. ユーザーの操作はエージェントのブラウザに同期される

Bridge URLの設定

{
  agents: {
    "my-agent": {
      tools: {
        browser: {
          bridge: {
            enabled: true,
            // Bridgeセッションのベース URL
            baseUrl: "https://openclaw.example.com/bridge",
            // セッション有効期限（秒）
            sessionTTL: 600,  // 10分
            // アクセス認証
            auth: {
              required: true,
              // ワンタイムToken認証
              method: "token"
            }
          }
        }
      }
    }
  }
}

使用シーン

シーン1：ユーザーログインが必要なWebサイト

ユーザー：銀行口座の残高を確認して

AI：銀行のサイトにログインする必要があります。ログインページを開きましたので、
    以下のリンクからログインを完了してください。
    🔗 https://openclaw.example.com/bridge/abc123

    ログイン後にお知らせください。続けて操作します。

ユーザー：[リンクをクリックしてログイン完了] できました

AI：[ログイン成功を検出]
→ browser.extract({ selector: ".balance" })
→ お客様の口座残高は ¥12,345.67 です

シーン2：CAPTCHA処理

CAPTCHAに遭遇した場合、AIは自力で処理できないため、Bridge URLでユーザーに手動で完了してもらいます。

AI：ページにCAPTCHAが表示されました。以下のリンクから認証を完了してください。
    🔗 https://openclaw.example.com/bridge/def456
    完了後、操作を続行します。

シーン3：複雑な操作の確認

機密性の高い操作を実行する前に、Bridge URLでユーザーに確認してもらいます。

AI：フォームの入力が完了しました。以下のリンクから内容を確認して送信してください。
    🔗 https://openclaw.example.com/bridge/ghi789

高度な設定

プロキシ設定

プロキシ経由でWebサイトにアクセスする必要がある場合：

{
  tools: {
    browser: {
      proxy: {
        server: "http://proxy.example.com:8080",
        username: "user",
        password: "pass",
        // プロキシを経由しないドメイン
        bypass: ["localhost", "*.internal.com"]
      }
    }
  }
}

Cookieとセッション管理

{
  tools: {
    browser: {
      // Cookie永続化ストレージ
      persistCookies: true,
      cookieDir: "./data/browser-cookies",
      // デフォルトCookie
      defaultCookies: [
        {
          name: "lang",
          value: "zh-CN",
          domain: ".example.com"
        }
      ]
    }
  }
}

User-Agentとリクエストヘッダー

{
  tools: {
    browser: {
      userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      extraHeaders: {
        "Accept-Language": "zh-CN,zh;q=0.9"
      }
    }
  }
}

リソースインターセプト

パフォーマンスを向上させ帯域幅を削減するために、不要なリソースをインターセプトできます。

{
  tools: {
    browser: {
      resourceBlocking: {
        // 画像をブロック（コンテンツ抽出のみの場合）
        blockImages: false,
        // フォントをブロック
        blockFonts: true,
        // 広告とトラッキングスクリプトをブロック
        blockPatterns: [
          "*google-analytics*",
          "*doubleclick*",
          "*facebook.com/tr*"
        ]
      }
    }
  }
}

セキュリティに関する考慮事項

サンドボックス分離

OpenClawのブラウザツールはサンドボックス環境で実行されます。

{
  tools: {
    browser: {
      sandbox: {
        // ネットワークアクセスホワイトリスト
        allowedDomains: [
          "*.github.com",
          "*.stackoverflow.com",
          "news.ycombinator.com"
        ],
        // ファイルダウンロードを禁止
        blockDownloads: true,
        // ローカルファイルへのアクセスを禁止
        blockFileUrls: true,
        // 同時に開けるページの最大数
        maxPages: 5,
        // 1ページあたりの最大実行時間
        maxPageTime: 60000
      }
    }
  }
}

コンテンツフィルタリング

{
  tools: {
    browser: {
      contentFilter: {
        // 機密情報のフィルタリング（抽出ページにパスワードフィールドが含まれる場合など）
        redactPatterns: [
          "password",
          "credit.?card",
          "ssn"
        ],
        // 抽出コンテンツの最大長
        maxExtractLength: 10000
      }
    }
  }
}

パフォーマンス最適化

ブラウザプール

高並列シーンでは、OpenClawはブラウザインスタンスプールをサポートしています。

{
  tools: {
    browser: {
      pool: {
        // 最小ブラウザインスタンス数
        min: 2,
        // 最大ブラウザインスタンス数
        max: 10,
        // アイドルインスタンスの最大生存時間
        idleTimeout: 300000
      }
    }
  }
}

ページキャッシュ

{
  tools: {
    browser: {
      pageCache: {
        enabled: true,
        // キャッシュ有効期限
        ttl: 300,  // 5分
        // 最大キャッシュページ数
        maxPages: 50
      }
    }
  }
}

デバッグ

# 非ヘッドレスモードで起動（ローカルデバッグ用）
OPENCLAW_BROWSER_HEADLESS=false openclaw start

# ブラウザツール呼び出しログを確認
openclaw logs --filter "browser"

# スクリーンショットをローカルに保存
openclaw browser screenshot https://example.com --output ./screenshot.png

まとめ

OpenClawのヘッドレスブラウザ統合により、AIエージェントは「Webページを見て操作する」能力を獲得しました。browserツールを通じて、エージェントはWebページのナビゲーション、コンテンツ抽出、フォーム入力、スクリーンショット撮影が可能です。Bridge URLメカニズムにより、ユーザーの参加が必要な操作（ログイン、CAPTCHAなど）もシームレスに対応できます。サンドボックス分離、リソースインターセプト、ブラウザプールなどの高度な設定と組み合わせることで、このソリューションは本番環境で安全かつ効率的に運用できます。