​

ブラウザ（openclaw 管理）

• これはエージェント専用の別ブラウザだと考えてください。
• openclaw プロファイルは、あなたの個人用ブラウザプロファイルに触れません。
• エージェントは安全なレーン内でタブを開き、ページを読み取り、クリックし、入力できます。
• 組み込みの user プロファイルは、Chrome MCP を通じてあなたの実際のサインイン済み Chrome セッションに接続します。

​

利用できる機能

• 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

​

プラグイン制御

{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}

• plugins.entries.browser.enabled が無効化されていないこと
• browser.enabled=true

​

ブラウザコマンドまたはツールが見つからない

{
  plugins: {
    allow: ["telegram"],
  },
}

{
  plugins: {
    allow: ["telegram", "browser"],
  },
}

• plugins.allow が設定されている場合、browser.enabled=true だけでは不十分です。
• plugins.allow が設定されている場合、plugins.entries.browser.enabled=true だけでも不十分です。
• tools.alsoAllow: ["browser"] は、バンドル済みブラウザプラグインを読み込みません。これは、プラグインがすでに読み込まれた後にツールポリシーを調整するだけです。
• 制限的なプラグイン許可リストが不要な場合、plugins.allow を削除してもデフォルトのバンドル済みブラウザ動作が復元されます。

• openclaw browser が未知のコマンドになる。
• browser.request がない。
• エージェントがブラウザツールを利用不可または欠落と報告する。

​

プロファイル: openclaw と user

• openclaw: 管理された分離ブラウザ（拡張機能不要）。
• user: あなたの実際のサインイン済み Chrome セッション用の組み込み Chrome MCP 接続プロファイル。

• デフォルト: 分離された openclaw ブラウザを使用します。
• 既存のログイン済みセッションが重要で、ユーザーがコンピューターの前にいて接続プロンプトのクリック/承認ができる場合は、profile="user" を優先します。
• profile は、特定のブラウザモードを使いたいときの明示的な上書きです。

​

設定

{
  browser: {
    enabled: true, // デフォルト: true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // デフォルトは trusted-network モード
      // 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: "openclaw",
    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" },
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

• ブラウザ制御サービスは、gateway.port から導出されたポートの loopback にバインドされます （デフォルト: 18791、つまり gateway + 2）。
• Gateway ポート（gateway.port または OPENCLAW_GATEWAY_PORT）を上書きすると、 導出されるブラウザポートも同じ「ファミリー」に収まるようにずれます。
• cdpUrl は、未設定時には管理対象のローカル CDP ポートがデフォルトになります。
• remoteCdpTimeoutMs は、リモート（非 loopback）CDP 到達性チェックに適用されます。
• remoteCdpHandshakeTimeoutMs は、リモート CDP WebSocket 到達性チェックに適用されます。
• ブラウザのナビゲーション/タブを開く操作には、ナビゲーション前に SSRF ガードが適用され、ナビゲーション後の最終 http(s) URL に対してベストエフォートで再チェックされます。
• strict SSRF モードでは、リモート CDP エンドポイントの検出/プローブ（cdpUrl。/json/version 参照を含む）もチェックされます。
• browser.ssrfPolicy.dangerouslyAllowPrivateNetwork のデフォルトは true です（trusted-network モデル）。strict な public-only ブラウジングにするには false に設定してください。
• browser.ssrfPolicy.allowPrivateNetwork は、互換性のため従来のエイリアスとして引き続きサポートされています。
• attachOnly: true は、「ローカルブラウザを絶対に起動せず、すでに実行中の場合のみ接続する」ことを意味します。
• color とプロファイルごとの color はブラウザ UI に色味を付け、どのプロファイルがアクティブかを視覚的に確認できるようにします。
• デフォルトプロファイルは openclaw です（OpenClaw 管理のスタンドアロンブラウザ）。サインイン済みのユーザーブラウザを使うには defaultProfile: "user" を使用してください。
• 自動検出順序: Chromium ベースであればシステムのデフォルトブラウザ、それ以外の場合は Chrome → Brave → Edge → Chromium → Chrome Canary。
• ローカルの openclaw プロファイルには cdpPort/cdpUrl が自動割り当てされます。これらを設定するのはリモート CDP の場合だけにしてください。
• driver: "existing-session" は、生の CDP の代わりに Chrome DevTools MCP を使用します。 この driver では cdpUrl を設定しないでください。
• 既存セッションプロファイルを Brave や Edge などのデフォルト以外の Chromium ユーザープロファイルに接続する場合は、 browser.profiles.<name>.userDataDir を設定してください。

​

Brave（または別の Chromium ベースブラウザ）を使う

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"
  }
}

​

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

• ローカル制御（デフォルト）: Gateway が loopback 制御サービスを起動し、ローカルブラウザを起動できます。
• リモート制御（ノードホスト）: ブラウザがあるマシン上でノードホストを実行すると、Gateway はブラウザアクションをそこにプロキシできます。
• リモート CDP: browser.profiles.<name>.cdpUrl（または browser.cdpUrl）を設定して、 リモートの Chromium ベースブラウザに接続します。この場合、OpenClaw はローカルブラウザを起動しません。

• ローカル管理プロファイル: openclaw browser stop は OpenClaw が起動したブラウザプロセスを停止します
• attach-only および remote CDP プロファイル: openclaw browser stop はアクティブな 制御セッションを閉じ、Playwright/CDP のエミュレーション上書き（ビューポート、 カラースキーム、ロケール、タイムゾーン、オフラインモード、および類似の状態）を解放します。 この場合でも、OpenClaw が起動したブラウザプロセスは存在しません

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

​

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

• ノードホストは、ローカルのブラウザ制御サーバーをプロキシコマンド経由で公開します。
• プロファイルはノード自身の browser.profiles 設定から取得されます（ローカルと同じ）。
• nodeHost.browserProxy.allowProfiles はオプションです。従来/デフォルトの動作にするには空のままにしてください。設定済みのすべてのプロファイルが、プロファイル作成/削除ルートを含めて、プロキシ経由で引き続き到達可能です。
• nodeHost.browserProxy.allowProfiles を設定すると、OpenClaw はそれを最小権限の境界として扱います。許可リストにあるプロファイルのみを対象にでき、永続プロファイルの作成/削除ルートはプロキシ面でブロックされます。
• 不要であれば無効化できます:
  • ノード側: nodeHost.browserProxy.enabled=false
  • Gateway 側: gateway.nodes.browser.mode="off"

​

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

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

• <BROWSERLESS_API_KEY> を実際の Browserless トークンに置き換えてください。
• Browserless アカウントに対応するリージョンエンドポイントを選択してください（詳細はそのドキュメントを参照）。
• Browserless から HTTPS ベース URL が提供される場合は、それを 直接 CDP 接続用の wss:// に変換するか、HTTPS URL のままにして OpenClaw に /json/version を検出させることができます。

​

直接 WebSocket CDP プロバイダー

• HTTP(S) エンドポイント — OpenClaw は /json/version を呼び出して WebSocket デバッガー URL を検出し、その後接続します。
• WebSocket エンドポイント（ws:// / wss://）— OpenClaw は /json/version をスキップして 直接接続します。これは、 Browserless、 Browserbase、または WebSocket URL を提供する任意のプロバイダーのようなサービスで使用してください。

​

Browserbase

{
  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 ブラウザ時間が利用できます。 有料プランの上限については pricing を参照してください。
• 完全な API リファレンス、SDK ガイド、統合例については Browserbase docs を参照してください。

​

セキュリティ

• ブラウザ制御は loopback のみです。アクセスは Gateway の認証またはノードペアリングを経由します。
• スタンドアロンの loopback ブラウザ HTTP API は、shared-secret 認証のみを使用します: Gateway トークンの Bearer 認証、x-openclaw-password、または 設定された Gateway パスワードを使う HTTP Basic 認証です。
• Tailscale Serve の identity ヘッダーと gateway.auth.mode: "trusted-proxy" は、 このスタンドアロン loopback ブラウザ API を認証しません。
• ブラウザ制御が有効で、shared-secret 認証が設定されていない場合、OpenClaw は 起動時に gateway.auth.token を自動生成し、それを設定に永続化します。
• gateway.auth.mode がすでに password、none、または trusted-proxy の場合、OpenClaw はそのトークンを自動生成しません。
• Gateway とすべてのノードホストはプライベートネットワーク（Tailscale）上に置いてください。公開露出は避けてください。
• リモート CDP URL/トークンはシークレットとして扱ってください。環境変数またはシークレットマネージャーの使用を推奨します。

• 可能な場合は、暗号化されたエンドポイント（HTTPS または WSS）と短命トークンを優先してください。
• 長寿命トークンを設定ファイルに直接埋め込むのは避けてください。

​

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

• openclaw 管理: 専用の Chromium ベースブラウザインスタンス。独自のユーザーデータディレクトリ + CDP ポートを持ちます
• リモート: 明示的な CDP URL（別の場所で動作している Chromium ベースブラウザ）
• 既存セッション: Chrome DevTools MCP 自動接続経由の既存 Chrome プロファイル

• openclaw プロファイルは、存在しない場合に自動作成されます。
• user プロファイルは、Chrome MCP の既存セッション接続用に組み込まれています。
• user 以外の既存セッションプロファイルはオプトインです。--driver existing-session で作成してください。
• ローカル CDP ポートは、デフォルトで 18800–18899 から割り当てられます。
• プロファイルを削除すると、そのローカルデータディレクトリはゴミ箱に移動されます。

​

Chrome DevTools MCP 経由の既存セッション

• Chrome for Developers: ブラウザセッションで Chrome DevTools MCP を使う
• Chrome DevTools MCP README

• user

• 組み込みの user プロファイルは Chrome MCP 自動接続を使用し、 デフォルトのローカル Google Chrome プロファイルを対象にします。

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}

1. そのブラウザのリモートデバッグ用 inspect ページを開きます。
2. リモートデバッグを有効にします。
3. ブラウザを起動したままにし、OpenClaw が接続するときに接続プロンプトを承認します。

• Chrome: chrome://inspect/#remote-debugging
• Brave: brave://inspect/#remote-debugging
• Edge: edge://inspect/#remote-debugging

openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai

• status に driver: existing-session と表示される
• status に transport: chrome-mcp と表示される
• status に running: true と表示される
• tabs に、すでに開いているブラウザタブが一覧表示される
• snapshot が、選択されたライブタブから refs を返す

• 対象の Chromium ベースブラウザがバージョン 144+ であること
• そのブラウザの inspect ページでリモートデバッグが有効になっていること
• ブラウザが接続同意プロンプトを表示し、あなたがそれを承認したこと
• openclaw doctor は古い拡張機能ベースのブラウザ設定を移行し、 デフォルトの自動接続プロファイル用に Chrome がローカルにインストールされていることを確認しますが、 ブラウザ側のリモートデバッグをあなたの代わりに有効化することはできません

• ユーザーのログイン済みブラウザ状態が必要な場合は profile="user" を使ってください。
• カスタム既存セッションプロファイルを使う場合は、その明示的なプロファイル名を渡してください。
• このモードを選ぶのは、ユーザーが接続プロンプトを承認できるようコンピューターの前にいる場合だけにしてください。
• Gateway またはノードホストは npx chrome-devtools-mcp@latest --autoConnect を起動できます

• この経路は、サインイン済みブラウザセッション内で操作できるため、分離された openclaw プロファイルより高リスクです。
• OpenClaw はこの driver でブラウザを起動しません。既存セッションにのみ接続します。
• OpenClaw はここで公式の Chrome DevTools MCP --autoConnect フローを使用します。 userDataDir が設定されている場合、OpenClaw はそれを渡して、その明示的な Chromium ユーザーデータディレクトリを対象にします。
• 既存セッションのスクリーンショットは、ページキャプチャとスナップショットからの --ref 要素キャプチャをサポートしますが、 CSS --element セレクターはサポートしません。
• 既存セッションのページスクリーンショットは、Playwright なしで Chrome MCP を通じて動作します。 ref ベースの要素スクリーンショット（--ref）もそこで動作しますが、--full-page は --ref や --element と組み合わせられません。
• 既存セッションのアクションは、管理ブラウザ経路より依然として制限があります:
  • click、type、hover、scrollIntoView、drag、select では、 CSS セレクターではなくスナップショット refs が必要です
  • click は左ボタンのみです（ボタン上書きや修飾キーは不可）
  • type は slowly=true をサポートしません。fill または press を使ってください
  • press は delayMs をサポートしません
  • hover、scrollIntoView、drag、select、fill、evaluate は 呼び出しごとのタイムアウト上書きをサポートしません
  • select は現在単一値のみサポートします
• 既存セッションの wait --url は、他のブラウザ driver と同様に完全一致、部分一致、glob パターンをサポートします。 wait --load networkidle はまだサポートされていません。
• 既存セッションのアップロードフックは ref または inputRef を必要とし、一度に 1 ファイルのみをサポートし、 CSS element ターゲティングはサポートしません。
• 既存セッションのダイアログフックはタイムアウト上書きをサポートしません。
• 一部の機能は引き続き管理ブラウザ経路が必要で、バッチアクション、PDF エクスポート、ダウンロードのインターセプト、responsebody などが該当します。
• 既存セッションはホストローカルです。Chrome が別のマシンまたは別のネットワーク名前空間にある場合は、 代わりにリモート CDP またはノードホストを使用してください。

​

分離の保証

• 専用のユーザーデータディレクトリ: あなたの個人用ブラウザプロファイルには決して触れません。
• 専用ポート: 開発ワークフローとの衝突を防ぐため 9222 を避けます。
• 決定論的なタブ制御: 「最後のタブ」ではなく targetId でタブを対象にします。

​

ブラウザの選択

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

• macOS: /Applications と ~/Applications を確認します。
• Linux: google-chrome、brave、microsoft-edge、chromium などを探します。
• Windows: 一般的なインストール場所を確認します。

​

制御 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

• Authorization: Bearer <gateway token>
• x-openclaw-password: <gateway password> またはそのパスワードを使う HTTP Basic 認証

• このスタンドアロン loopback ブラウザ API は trusted-proxy や Tailscale Serve の identity ヘッダーを利用しません。
• gateway.auth.mode が none または trusted-proxy の場合、これらの loopback ブラウザ ルートはそうした identity 付きモードを継承しません。loopback のみに保ってください。

​

/act エラー契約

{ "error": "<message>", "code": "ACT_*" }

• ACT_KIND_REQUIRED (HTTP 400): kind が欠落しているか、認識されません。
• ACT_INVALID_REQUEST (HTTP 400): アクションペイロードの正規化またはバリデーションに失敗しました。
• ACT_SELECTOR_UNSUPPORTED (HTTP 400): サポートされていないアクション種別で selector が使用されました。
• ACT_EVALUATE_DISABLED (HTTP 403): evaluate（または wait --fn）が設定で無効になっています。
• ACT_TARGET_ID_MISMATCH (HTTP 403): トップレベルまたはバッチ化された targetId がリクエスト対象と競合しています。
• ACT_EXISTING_SESSION_UNSUPPORTED (HTTP 501): このアクションは既存セッションプロファイルではサポートされていません。

​

Playwright 要件

• ARIA スナップショット
• タブごとの CDP WebSocket が利用可能な場合の、管理 openclaw ブラウザのページスクリーンショット
• existing-session / Chrome MCP プロファイルのページスクリーンショット
• スナップショット出力からの existing-session の ref ベーススクリーンショット（--ref）

• navigate
• act
• AI スナップショット / role スナップショット
• CSS セレクター要素スクリーンショット（--element）
• ブラウザ全体の PDF エクスポート

​

Docker での Playwright インストール

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

​

仕組み（内部）

• 小さな制御サーバーが HTTP リクエストを受け付けます。
• CDP を介して Chromium ベースのブラウザ（Chrome/Brave/Edge/Chromium）に接続します。
• 高度な操作（クリック/入力/スナップショット/PDF）には、CDP の上で Playwright を使用します。
• Playwright がない場合は、Playwright 非依存の操作のみ利用できます。

​

CLI クイックリファレンス

• 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

• attach-only および remote CDP プロファイルでは、テスト後の適切なクリーンアップコマンドは 依然として openclaw browser stop です。これは、基盤となるブラウザを終了する代わりに、 アクティブな制御セッションを閉じ、一時的なエミュレーション上書きを解除します。
• 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 は事前待機呼び出しです。ファイル選択ダイアログやダイアログを 発生させる click/press の前に実行してください。
• ダウンロードとトレースの出力パスは OpenClaw の一時ルートに制限されます:
  • traces: /tmp/openclaw（フォールバック: ${os.tmpdir()}/openclaw）
  • downloads: /tmp/openclaw/downloads（フォールバック: ${os.tmpdir()}/openclaw/downloads）
• アップロードパスは OpenClaw の一時アップロードルートに制限されます:
  • uploads: /tmp/openclaw/uploads（フォールバック: ${os.tmpdir()}/openclaw/uploads）
• upload は、--input-ref または --element によってファイル input を直接設定することもできます。
• snapshot:
  • --format ai（Playwright がインストールされている場合のデフォルト）: 数値 refs を含む AI スナップショットを返します（aria-ref="<n>"）。
  • --format aria: アクセシビリティツリーを返します（refs なし。調査専用）。
  • --efficient（または --mode efficient）: コンパクトな role スナップショットのプリセットです（interactive + compact + depth + lower maxChars）。
  • 設定のデフォルト（ツール/CLI のみ）: 呼び出し側が mode を渡さないときに efficient スナップショットを使うには、browser.snapshotDefaults.mode: "efficient" を設定してください（Gateway configuration を参照）。
  • role スナップショットオプション（--interactive、--compact、--depth、--selector）は、ref=e12 のような refs を持つ role ベーススナップショットを強制します。
  • --frame "<iframe selector>" は role スナップショットを iframe に限定します（e12 のような role refs と組み合わせます）。
  • --interactive は、対話可能要素のフラットで選びやすい一覧を出力します（アクション操作に最適）。
  • --labels は、ref ラベルが重ねられたビューポート限定のスクリーンショットを追加します（MEDIA:<path> を出力します）。
• click/type/その他は、snapshot からの ref（数値の 12 または role ref の e12）を必要とします。 アクションで CSS セレクターは意図的にサポートしていません。

​

スナップショットと refs

• AI スナップショット（数値 refs）: openclaw browser snapshot（デフォルト。--format ai）
  • 出力: 数値 refs を含むテキストスナップショット。
  • アクション: openclaw browser click 12、openclaw browser type 23 "hello"。
  • 内部的には、ref は Playwright の aria-ref で解決されます。
• Role スナップショット（e12 のような role refs）: openclaw browser snapshot --interactive（または --compact、--depth、--selector、--frame）
  • 出力: [ref=e12]（およびオプションの [nth=1]）を含む role ベースの一覧/ツリー。
  • アクション: openclaw browser click e12、openclaw browser highlight e12。
  • 内部的には、ref は getByRole(...)（重複時は nth() を追加）で解決されます。
  • --labels を追加すると、e12 ラベルを重ねたビューポートスクリーンショットを含められます。

• refs はナビゲーションをまたいで安定しません。何か失敗した場合は、snapshot を再実行して新しい ref を使用してください。
• role スナップショットを --frame 付きで取得した場合、role refs は次の role スナップショットまでその 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

​

デバッグワークフロー

1. openclaw browser snapshot --interactive
2. click <ref> / type <ref> を使う（interactive モードでは role refs を優先）
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 出力

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

​

状態および環境ノブ

• Cookie: cookies、cookies set、cookies clear
• Storage: 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）
• Geolocation: set geo <lat> <lon> --origin "https://example.com"（または --clear）
• Media: 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 など）については、Browser login + X/Twitter posting を参照してください。
• Gateway/ノードホストはプライベート（loopback または tailnet-only）に保ってください。
• リモート CDP エンドポイントは強力です。トンネル化し、保護してください。

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // オプションの完全一致許可
    },
  },
}

​

トラブルシューティング

​

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

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

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

​

関連

• Tools Overview — 利用可能なすべてのエージェントツール
• Sandboxing — サンドボックス環境でのブラウザ制御
• Security — ブラウザ制御のリスクとハードニング