ブラウザ（OpenClaw 管理）

OpenClaw は、エージェントが制御する専用の Chrome/Brave/Edge/Chromium プロファイルを実行できます。個人のブラウザとは分離されており、Gateway 内の小さなローカルコントロールサービス（ループバック専用）で管理されます。

初心者向けの概要:

  • 別のエージェント専用ブラウザと考えてください。
  • openclaw プロファイルは個人のブラウザプロファイルに影響しません。
  • エージェントは安全なレーンでタブを開いたり、ページを読んだり、クリックしたり、入力したりできます。
  • デフォルトの chrome プロファイルはエクステンションリレー経由でシステムのデフォルト Chromium ブラウザを使用します。分離された管理ブラウザには openclaw プロファイルに切り替えてください。

提供される機能

  • openclaw という名前の別のブラウザプロファイル（デフォルトでオレンジ色のアクセント）。
  • 決定論的なタブ制御（一覧/開く/フォーカス/閉じる）。
  • エージェントアクション（クリック/入力/ドラッグ/選択）、スナップショット、スクリーンショット、PDF。
  • 複数プロファイルのサポート（openclaw、work、remote など）。

このブラウザは日常使いのブラウザではありません。エージェント自動化と検証のための安全で分離されたサーフェスです。

クイックスタート

openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

「Browser disabled」と表示される場合は、設定で有効化して（以下参照）Gateway を再起動してください。

プロファイル: openclaw vs chrome

  • openclaw: 管理された分離ブラウザ（エクステンション不要）。
  • chrome: システムブラウザへのエクステンションリレー（OpenClaw エクステンションをタブにアタッチする必要あり）。
  • existing-session: 実行中の Chrome プロファイルへの公式 Chrome MCP アタッチフロー。

管理モードをデフォルトにしたい場合は browser.defaultProfile: "openclaw" を設定。

設定

ブラウザ設定は ~/.openclaw/openclaw.json に記述します。

{
  browser: {
    enabled: true, // デフォルト: true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // デフォルトの信頼ネットワークモード
      // allowPrivateNetwork: true, // レガシーエイリアス
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // レガシーの単一プロファイルオーバーライド
    remoteCdpTimeoutMs: 1500, // リモート CDP HTTP タイムアウト（ms）
    remoteCdpHandshakeTimeoutMs: 3000, // リモート CDP WebSocket ハンドシェイクタイムアウト（ms）
    defaultProfile: "chrome",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      chromeLive: {
        cdpPort: 18802,
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

補足:

  • ブラウザコントロールサービスは gateway.port から導出されたポートでループバックにバインドします（デフォルト: 18791、Gateway + 2）。リレーは次のポート（18792）を使用。
  • Gateway ポートをオーバーライドした場合（gateway.port または OPENCLAW_GATEWAY_PORT）、導出されるブラウザポートも同じ「ファミリー」内でシフト。
  • 未設定時、cdpUrl はリレーポートがデフォルト。
  • remoteCdpTimeoutMs はリモート（非ループバック）CDP 到達性チェックに適用。
  • remoteCdpHandshakeTimeoutMs はリモート CDP WebSocket 到達性チェックに適用。
  • ブラウザナビゲーション/タブオープンはナビゲーション前に SSRF ガードされ、ナビゲーション後の最終 http(s) URL でもベストエフォートで再チェック。
  • browser.ssrfPolicy.dangerouslyAllowPrivateNetwork はデフォルトで true（信頼ネットワークモデル）。厳密なパブリック専用ブラウジングには false に設定。
  • browser.ssrfPolicy.allowPrivateNetwork は互換性のためレガシーエイリアスとして引き続きサポート。
  • attachOnly: true は「ローカルブラウザを起動せず、既に実行中の場合のみアタッチ」の意味。
  • color とプロファイルごとの color でブラウザ UI に色をつけ、どのプロファイルがアクティブか確認可能。
  • デフォルトプロファイルは openclaw（OpenClaw 管理スタンドアロンブラウザ）。Chrome エクステンションリレーを使う場合は defaultProfile: "chrome" を設定。
  • 自動検出順序: Chromium ベースのシステムデフォルトブラウザを優先。それ以外の場合は Chrome → Brave → Edge → Chromium → Chrome Canary。
  • ローカル openclaw プロファイルは cdpPort/cdpUrl を自動割り当て。リモート CDP の場合のみ設定。
  • driver: "existing-session" は生の CDP ではなく Chrome DevTools MCP を使用。このドライバーでは cdpUrl を設定しない。

Brave（または他の Chromium ベースブラウザ）の使用

システムのデフォルトブラウザが Chromium ベース（Chrome/Brave/Edge など）の場合、OpenClaw は自動的にそれを使用します。自動検出をオーバーライドするには browser.executablePath を設定:

CLI 例:

openclaw config set browser.executablePath "/usr/bin/google-chrome"
// macOS
{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
  }
}

// Windows
{
  browser: {
    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
  }
}

// Linux
{
  browser: {
    executablePath: "/usr/bin/brave-browser"
  }
}

ローカル制御 vs リモート制御

  • ローカル制御（デフォルト）: Gateway がループバックコントロールサービスを起動し、ローカルブラウザを起動可能。
  • リモート制御（ノードホスト）: ブラウザのあるマシンでノードホストを実行し、Gateway がブラウザアクションをプロキシ。
  • リモート CDP: browser.profiles.<name>.cdpUrl（または browser.cdpUrl）をリモートの Chromium ベースブラウザに設定。この場合、OpenClaw はローカルブラウザを起動しない。

リモート CDP URL には認証を含められます:

  • クエリトークン（例: https://provider.example?token=<token>）
  • HTTP Basic 認証（例: https://user:[email protected]）

OpenClaw は /json/* エンドポイントの呼び出し時および CDP WebSocket への接続時に認証を保持します。設定ファイルにトークンをコミットする代わりに、環境変数やシークレットマネージャーの使用を推奨します。

ノードブラウザプロキシ（ゼロ設定デフォルト）

ブラウザのあるマシンでノードホストを実行すると、OpenClaw は追加のブラウザ設定なしでそのノードにブラウザツール呼び出しを自動ルーティングできます。リモート Gateway のデフォルトパスです。

補足:

  • ノードホストはプロキシコマンド経由でローカルブラウザコントロールサーバーを公開。
  • プロファイルはノード自身の browser.profiles 設定から取得（ローカルと同じ）。
  • 不要な場合は無効化:
    • ノード側: nodeHost.browserProxy.enabled=false
    • Gateway 側: gateway.nodes.browser.mode="off"

Browserless（ホスト型リモート CDP）

Browserless は、HTTPS 経由で CDP エンドポイントを公開するホスト型 Chromium サービスです。OpenClaw のブラウザプロファイルを Browserless のリージョンエンドポイントに向けて、API キーで認証できます。

例:

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "https://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

補足:

  • <BROWSERLESS_API_KEY> を実際の Browserless トークンに置き換え。
  • Browserless アカウントに合ったリージョンエンドポイントを選択（詳細はドキュメントを参照）。

ダイレクト WebSocket CDP プロバイダー

一部のホスト型ブラウザサービスは、標準の HTTP ベース CDP ディスカバリー（/json/version）ではなくダイレクト WebSocket エンドポイントを公開します。OpenClaw は両方をサポート:

  • HTTP(S) エンドポイント（例: Browserless）— OpenClaw が /json/version を呼び出して WebSocket デバッガー URL を検出し、接続。
  • WebSocket エンドポイント（ws:// / wss://）— /json/version をスキップして直接接続。Browserbase など、WebSocket URL を直接提供するサービス向け。

Browserbase

Browserbase は、組み込みの CAPTCHA 解決、ステルスモード、住宅用プロキシを備えたヘッドレスブラウザ実行用のクラウドプラットフォームです。

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

補足:

  • サインアップし、Overview ダッシュボードから API Key をコピー。
  • <BROWSERBASE_API_KEY> を実際の Browserbase API キーに置き換え。
  • Browserbase は WebSocket 接続時にブラウザセッションを自動作成するため、手動でのセッション作成は不要。
  • 無料プランでは同時 1 セッション、月 1 ブラウザ時間が利用可能。有料プランの制限は料金ページを参照。
  • 完全な API リファレンス、SDK ガイド、統合例は Browserbase ドキュメントを参照。

セキュリティ

主なポイント:

  • ブラウザコントロールはループバック専用。アクセスは Gateway の認証またはノードペアリング経由。
  • ブラウザコントロールが有効で認証が設定されていない場合、OpenClaw は起動時に gateway.auth.token を自動生成し、設定に保持。
  • Gateway とノードホストはプライベートネットワーク（Tailscale）に配置し、パブリック公開を避ける。
  • リモート CDP URL/トークンはシークレットとして扱い、環境変数やシークレットマネージャーを推奨。

リモート CDP のヒント:

  • 可能な限り暗号化エンドポイント（HTTPS または WSS）と短命トークンを推奨。
  • 設定ファイルに長期トークンを直接埋め込むのは避ける。

プロファイル（マルチブラウザ）

OpenClaw は複数の名前付きプロファイル（ルーティング設定）をサポートします。プロファイルの種類:

  • openclaw 管理: 独自のユーザーデータディレクトリ + CDP ポートを持つ専用 Chromium ベースブラウザインスタンス
  • リモート: 明示的な CDP URL（別の場所で実行中の Chromium ベースブラウザ）
  • エクステンションリレー: ローカルリレー + Chrome エクステンション経由の既存 Chrome タブ
  • 既存セッション: Chrome DevTools MCP 自動接続による既存の Chrome プロファイル

デフォルト:

  • openclaw プロファイルは欠落時に自動作成。
  • chrome プロファイルは Chrome エクステンションリレー用の組み込み（デフォルトで http://127.0.0.1:18792 を指す）。
  • 既存セッションプロファイルはオプトイン。--driver existing-session で作成。
  • ローカル CDP ポートはデフォルトで 18800〜18899 から割り当て。
  • プロファイルを削除するとローカルデータディレクトリがゴミ箱に移動。

すべてのコントロールエンドポイントは ?profile=<name> を受け付け、CLI では --browser-profile を使用。

Chrome エクステンションリレー（既存の Chrome を使用）

OpenClaw は、ローカル CDP リレー + Chrome エクステンション経由で（別の「openclaw」Chrome インスタンスではなく）既存の Chrome タブを操作することもできます。

詳細ガイド: Chrome エクステンション

フロー:

  • Gateway がローカル（同一マシン）で動作するか、ブラウザマシンでノードホストが動作。
  • ローカルリレーサーバーがループバック cdpUrl（デフォルト: http://127.0.0.1:18792）でリッスン。
  • OpenClaw Browser Relay エクステンションアイコンをタブでクリックしてアタッチ（自動アタッチはなし）。
  • エージェントは適切なプロファイルを選択して通常の browser ツール経由でそのタブを制御。

Gateway が別の場所で動作している場合、ブラウザマシンでノードホストを実行して Gateway がブラウザアクションをプロキシできるようにしてください。

サンドボックス化されたセッション

エージェントセッションがサンドボックス化されている場合、browser ツールはデフォルトで target="sandbox"（サンドボックスブラウザ）になる場合があります。Chrome エクステンションリレーの制御にはホストブラウザコントロールが必要なため、以下のいずれかが必要:

  • 非サンドボックスセッションで実行、または
  • agents.defaults.sandbox.browser.allowHostControl: true を設定し、ツール呼び出し時に target="host" を使用。

セットアップ

  1. エクステンションの読み込み（dev/未パッケージ化）:
openclaw browser extension install
  • Chrome → chrome://extensions → 「デベロッパーモード」有効化
  • 「パッケージ化されていない拡張機能を読み込む」→ openclaw browser extension path で表示されたディレクトリを選択
  • エクステンションをピン留めし、制御したいタブでエクステンションアイコンをクリック（バッジが ON を表示）。
  1. 使用方法:
  • CLI: openclaw browser --browser-profile chrome tabs
  • エージェントツール: browser で profile="chrome" を指定

別の名前やリレーポートを使いたい場合は独自のプロファイルを作成:

openclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

補足:

  • このモードはほとんどの操作で Playwright-on-CDP を使用（スクリーンショット/スナップショット/アクション）。
  • エクステンションアイコンを再度クリックするとデタッチ。

Chrome 既存セッション（MCP 経由）

OpenClaw は公式 Chrome DevTools MCP サーバーを通じて実行中の Chrome プロファイルにアタッチすることもできます。その Chrome プロファイルで既に開いているタブとログイン状態を再利用します。

公式の背景とセットアップ参照:

プロファイルの作成:

openclaw browser create-profile \
  --name chrome-live \
  --driver existing-session \
  --color "#00AA00"

Chrome 側の手順:

  1. chrome://inspect/#remote-debugging を開く
  2. リモートデバッグを有効化
  3. Chrome を起動したままにし、OpenClaw がアタッチする際の接続プロンプトを承認

ライブアタッチの動作確認:

openclaw browser --browser-profile chrome-live start
openclaw browser --browser-profile chrome-live status
openclaw browser --browser-profile chrome-live tabs
openclaw browser --browser-profile chrome-live snapshot --format ai

成功時の状態:

  • status が driver: existing-session を表示
  • status が running: true を表示
  • tabs が既に開いている Chrome タブを一覧表示
  • snapshot が選択されたライブタブから ref を返す

アタッチできない場合の確認事項:

  • Chrome がバージョン 144+
  • chrome://inspect/#remote-debugging でリモートデバッグが有効
  • Chrome が表示したアタッチ同意プロンプトを承認済み
  • Gateway またはノードホストが npx chrome-devtools-mcp@latest --autoConnect を生成可能

補足:

  • このパスはサインインしたブラウザセッション内で操作できるため、分離された openclaw プロファイルよりリスクが高い。
  • OpenClaw はこのドライバーでは Chrome を起動しない。既存セッションへのアタッチのみ。
  • OpenClaw はレガシーのデフォルトプロファイルリモートデバッグポートワークフローではなく、公式 Chrome DevTools MCP --autoConnect フローを使用。
  • 既存セッションのスクリーンショットはページキャプチャとスナップショットからの --ref 要素キャプチャをサポートするが、CSS --element セレクターは非対応。
  • 既存セッションの wait --url は他のブラウザドライバーと同様に完全一致、部分一致、glob パターンをサポート。wait --load networkidle はまだ未サポート。
  • PDF エクスポートやダウンロードインターセプションなど、一部の機能はエクステンションリレーまたは管理ブラウザパスが必要。
  • リレーはデフォルトでループバック専用。異なるネットワークネームスペースからリレーが到達可能である必要がある場合（例: WSL2 で Gateway、Windows で Chrome）、browser.relayBindHost を 0.0.0.0 などの明示的なバインドアドレスに設定し、周辺ネットワークをプライベートかつ認証済みに保つ。

WSL2 / クロスネームスペースの例:

{
  browser: {
    enabled: true,
    relayBindHost: "0.0.0.0",
    defaultProfile: "chrome",
  },
}

分離保証

  • 専用ユーザーデータディレクトリ: 個人のブラウザプロファイルに接触しない。
  • 専用ポート: 開発ワークフローとの衝突を避けるため 9222 を回避。
  • 決定論的タブ制御: 「最後のタブ」ではなく targetId でタブを指定。

ブラウザの選択

ローカルで起動時、OpenClaw は最初に利用可能なものを選択:

  1. Chrome
  2. Brave
  3. Edge
  4. Chromium
  5. Chrome Canary

browser.executablePath でオーバーライド可能。

プラットフォーム:

  • macOS: /Applications と ~/Applications をチェック。
  • Linux: google-chrome、brave、microsoft-edge、chromium などを検索。
  • Windows: 一般的なインストール場所をチェック。

コントロール API（任意）

ローカル統合専用。Gateway はループバック HTTP API を提供:

  • ステータス/開始/停止: GET /、POST /start、POST /stop
  • タブ: GET /tabs、POST /tabs/open、POST /tabs/focus、DELETE /tabs/:targetId
  • スナップショット/スクリーンショット: GET /snapshot、POST /screenshot
  • アクション: POST /navigate、POST /act
  • フック: POST /hooks/file-chooser、POST /hooks/dialog
  • ダウンロード: POST /download、POST /wait/download
  • デバッグ: GET /console、POST /pdf
  • デバッグ: GET /errors、GET /requests、POST /trace/start、POST /trace/stop、POST /highlight
  • ネットワーク: POST /response/body
  • 状態: GET /cookies、POST /cookies/set、POST /cookies/clear
  • 状態: GET /storage/:kind、POST /storage/:kind/set、POST /storage/:kind/clear
  • 設定: POST /set/offline、POST /set/headers、POST /set/credentials、POST /set/geolocation、POST /set/media、POST /set/timezone、POST /set/locale、POST /set/device

すべてのエンドポイントは ?profile=<name> を受け付けます。

Gateway 認証が設定されている場合、ブラウザ HTTP ルートにも認証が必要:

  • Authorization: Bearer <gateway token>
  • x-openclaw-password: <gateway password> または HTTP Basic 認証

Playwright の要件

一部の機能（navigate/act/AI スナップショット/ロールスナップショット、要素スクリーンショット、PDF）は Playwright が必要です。Playwright がインストールされていない場合、それらのエンドポイントは明確な 501 エラーを返します。openclaw 管理の Chrome では ARIA スナップショットと基本的なスクリーンショットは引き続き動作します。Chrome エクステンションリレードライバーでは ARIA スナップショットとスクリーンショットに Playwright が必要です。

Playwright is not available in this gateway build と表示される場合は、完全な Playwright パッケージ（playwright-core ではなく）をインストールして Gateway を再起動するか、ブラウザサポート付きで OpenClaw を再インストールしてください。

Docker での Playwright インストール

Gateway が Docker で動作している場合、npx playwright は避けてください（npm オーバーライドの競合）。バンドル済み CLI を使用:

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

ブラウザダウンロードを永続化するには、PLAYWRIGHT_BROWSERS_PATH（例: /home/node/.cache/ms-playwright）を設定し、/home/node が OPENCLAW_HOME_VOLUME またはバインドマウント経由で永続化されていることを確認してください。Docker を参照。

仕組み（内部）

概要:

  • 小さなコントロールサーバーが HTTP リクエストを受け付ける。
  • CDP 経由で Chromium ベースブラウザ（Chrome/Brave/Edge/Chromium）に接続。
  • 高度なアクション（クリック/入力/スナップショット/PDF）では CDP 上の Playwright を使用。
  • Playwright がない場合、非 Playwright 操作のみ利用可能。

この設計により、エージェントは安定した決定論的なインターフェースを維持しつつ、ローカル/リモートブラウザやプロファイルを切り替えられます。

CLI クイックリファレンス

すべてのコマンドは --browser-profile <name> で特定のプロファイルを指定可能。 すべてのコマンドは --json で機械可読出力に対応（安定ペイロード）。

基本操作:

  • openclaw browser status
  • openclaw browser start
  • openclaw browser stop
  • openclaw browser tabs
  • openclaw browser tab
  • openclaw browser tab new
  • openclaw browser tab select 2
  • openclaw browser tab close 2
  • openclaw browser open https://example.com
  • openclaw browser focus abcd1234
  • openclaw browser close abcd1234

検査:

  • openclaw browser screenshot
  • openclaw browser screenshot --full-page
  • openclaw browser screenshot --ref 12
  • openclaw browser screenshot --ref e12
  • openclaw browser snapshot
  • openclaw browser snapshot --format aria --limit 200
  • openclaw browser snapshot --interactive --compact --depth 6
  • openclaw browser snapshot --efficient
  • openclaw browser snapshot --labels
  • openclaw browser snapshot --selector "#main" --interactive
  • openclaw browser snapshot --frame "iframe#main" --interactive
  • openclaw browser console --level error
  • openclaw browser errors --clear
  • openclaw browser requests --filter api --clear
  • openclaw browser pdf
  • openclaw browser responsebody "**/api" --max-chars 5000

アクション:

  • openclaw browser navigate https://example.com
  • openclaw browser resize 1280 720
  • openclaw browser click 12 --double
  • openclaw browser click e12 --double
  • openclaw browser type 23 "hello" --submit
  • openclaw browser press Enter
  • openclaw browser hover 44
  • openclaw browser scrollintoview e12
  • openclaw browser drag 10 11
  • openclaw browser select 9 OptionA OptionB
  • openclaw browser download e12 report.pdf
  • openclaw browser waitfordownload report.pdf
  • openclaw browser upload /tmp/openclaw/uploads/file.pdf
  • openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
  • openclaw browser dialog --accept
  • openclaw browser wait --text "Done"
  • openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
  • openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
  • openclaw browser highlight e12
  • openclaw browser trace start
  • openclaw browser trace stop

状態:

  • openclaw browser cookies
  • openclaw browser cookies set session abc123 --url "https://example.com"
  • openclaw browser cookies clear
  • openclaw browser storage local get
  • openclaw browser storage local set theme dark
  • openclaw browser storage session clear
  • openclaw browser set offline on
  • openclaw browser set headers --headers-json '{"X-Debug":"1"}'
  • openclaw browser set credentials user pass
  • openclaw browser set credentials --clear
  • openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
  • openclaw browser set geo --clear
  • openclaw browser set media dark
  • openclaw browser set timezone America/New_York
  • openclaw browser set locale en-US
  • openclaw browser set device "iPhone 14"

補足:

  • upload と dialog はアーミング呼び出しです。ファイルチューザー/ダイアログをトリガーするクリック/キー押下の前に実行してください。
  • ダウンロードとトレースの出力パスは OpenClaw 一時ルートに制限:
    • トレース: /tmp/openclaw（フォールバック: ${os.tmpdir()}/openclaw）
    • ダウンロード: /tmp/openclaw/downloads（フォールバック: ${os.tmpdir()}/openclaw/downloads）
  • アップロードパスは OpenClaw 一時アップロードルートに制限:
    • アップロード: /tmp/openclaw/uploads（フォールバック: ${os.tmpdir()}/openclaw/uploads）
  • upload は --input-ref または --element 経由でファイル入力を直接設定することも可能。
  • snapshot:
    • --format ai（Playwright インストール時のデフォルト）: 数値 ref 付き AI スナップショットを返す（aria-ref="<n>"）。
    • --format aria: アクセシビリティツリーを返す（ref なし、検査専用）。
    • --efficient（または --mode efficient）: コンパクトロールスナップショットプリセット（interactive + compact + depth + 低 maxChars）。
    • 設定デフォルト（ツール/CLI のみ）: browser.snapshotDefaults.mode: "efficient" を設定すると、呼び出し元がモードを渡さない場合に効率的スナップショットを使用（Gateway 設定 を参照）。
    • ロールスナップショットオプション（--interactive、--compact、--depth、--selector）は ref=e12 のような ref 付きロールベーススナップショットを強制。
    • --frame "<iframe selector>" はロールスナップショットを iframe にスコープ（e12 のようなロール ref と組み合わせ）。
    • --interactive はインタラクティブ要素のフラットで選びやすいリストを出力（アクション実行に最適）。
    • --labels はオーバーレイ ref ラベル付きのビューポートスクリーンショットを追加（MEDIA:<path> を出力）。
  • click/type などは snapshot からの ref が必要（数値 12 またはロール ref e12）。アクションに CSS セレクターは意図的にサポートしていません。

スナップショットと ref

OpenClaw は 2 つの「スナップショット」スタイルをサポート:

  • AI スナップショット（数値 ref）: openclaw browser snapshot（デフォルト、--format ai）

    • 出力: 数値 ref を含むテキストスナップショット。
    • アクション: openclaw browser click 12、openclaw browser type 23 "hello"。
    • 内部では Playwright の aria-ref 経由で ref を解決。

  • ロールスナップショット（e12 のようなロール ref）: openclaw browser snapshot --interactive（または --compact、--depth、--selector、--frame）

    • 出力: [ref=e12]（任意で [nth=1]）付きのロールベースリスト/ツリー。
    • アクション: openclaw browser click e12、openclaw browser highlight e12。
    • 内部では getByRole(...)（重複時は nth()）経由で ref を解決。
    • --labels を追加するとオーバーレイ e12 ラベル付きビューポートスクリーンショットを含む。

ref の動作:

  • ref はナビゲーション間で安定しません。失敗した場合は snapshot を再実行して新しい ref を使用。
  • ロールスナップショットが --frame 付きで取得された場合、ロール ref は次のロールスナップショットまでその iframe にスコープされる。

Wait の拡張機能

時間/テキスト以外にも待機可能:

  • URL での待機（Playwright がサポートする glob）:
    • openclaw browser wait --url "**/dash"
  • ロード状態での待機:
    • openclaw browser wait --load networkidle
  • JS 述語での待機:
    • openclaw browser wait --fn "window.ready===true"
  • セレクターの可視化待機:
    • openclaw browser wait "#main"

これらは組み合わせ可能:

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

デバッグワークフロー

アクションが失敗した場合（例: “not visible”、“strict mode violation”、“covered”）:

  1. openclaw browser snapshot --interactive
  2. click <ref> / type <ref> を使用（インタラクティブモードではロール ref を推奨）
  3. それでも失敗する場合: openclaw browser highlight <ref> で Playwright のターゲットを確認
  4. ページの動作がおかしい場合:
    • openclaw browser errors --clear
    • openclaw browser requests --filter api --clear
  5. 詳細デバッグ: トレースを記録:
    • openclaw browser trace start
    • 問題を再現
    • openclaw browser trace stop（TRACE:<path> を出力）

JSON 出力

--json はスクリプティングと構造化ツール向けです。

例:

openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json

ロールスナップショットの JSON 出力には、ツールがペイロードのサイズと密度を推論できるよう、refs と小さな stats ブロック（lines/chars/refs/interactive）が含まれます。

状態と環境設定

「サイトを X のように動作させる」ワークフローに便利:

  • Cookie: cookies、cookies set、cookies clear
  • ストレージ: storage local|session get|set|clear
  • オフライン: set offline on|off
  • ヘッダー: set headers --headers-json '{"X-Debug":"1"}'（レガシー set headers --json '{"X-Debug":"1"}' も引き続きサポート）
  • HTTP Basic 認証: set credentials user pass（または --clear）
  • ジオロケーション: set geo <lat> <lon> --origin "https://example.com"（または --clear）
  • メディア: set media dark|light|no-preference|none
  • タイムゾーン / ロケール: set timezone ...、set locale ...
  • デバイス / ビューポート:
    • set device "iPhone 14"（Playwright デバイスプリセット）
    • set viewport 1280 720

セキュリティとプライバシー

  • openclaw ブラウザプロファイルにはログイン済みセッションが含まれる場合があるため、機密として扱うこと。
  • browser act kind=evaluate / openclaw browser evaluate と wait --fn はページコンテキストで任意の JavaScript を実行する。プロンプトインジェクションでこれを操作される可能性あり。不要な場合は browser.evaluateEnabled=false で無効化。
  • ログインとボット対策（X/Twitter など）については、ブラウザログイン + X/Twitter 投稿 を参照。
  • Gateway/ノードホストはプライベートに保つ（ループバックまたはテイルネット専用）。
  • リモート CDP エンドポイントは強力。トンネル化して保護すること。

厳格モードの例（プライベート/内部宛先をデフォルトでブロック）:

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // 任意の完全一致許可
    },
  },
}

トラブルシューティング

Linux 固有の問題（特に snap Chromium）については、ブラウザのトラブルシューティング を参照。

WSL2 Gateway + Windows Chrome の分割ホスト構成については、WSL2 + Windows + リモート Chrome CDP トラブルシューティング を参照。

エージェントツールと制御の仕組み

エージェントにはブラウザ自動化用のツールが 1 つあります:

  • browser — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

マッピング:

  • browser snapshot は安定した UI ツリー（AI または ARIA）を返す。
  • browser act はスナップショットの ref ID を使ってクリック/入力/ドラッグ/選択。
  • browser screenshot はピクセルをキャプチャ（フルページまたは要素）。
  • browser は以下を受け付ける:
    • profile: 名前付きブラウザプロファイルを選択（openclaw、chrome、またはリモート CDP）。
    • target（sandbox | host | node）: ブラウザの場所を選択。
    • サンドボックス化されたセッションでは、target: "host" に agents.defaults.sandbox.browser.allowHostControl=true が必要。
    • target を省略した場合: サンドボックス化されたセッションはデフォルトで sandbox、非サンドボックスセッションはデフォルトで host。
    • ブラウザ対応ノードが接続されている場合、target="host" や target="node" を固定しない限り自動ルーティングされる場合あり。

これによりエージェントは決定論的に動作し、脆弱なセレクターを回避します。

arrow_back
前へ
Web
次へ
Browser Login
arrow_forward