openclaw browser
OpenClaw のブラウザ制御サーフェスを管理し、ライフサイクル、プロファイル、タブ、スナップショット、スクリーンショット、ナビゲーション、入力、状態エミュレーション、デバッグなどのブラウザ操作を実行します。
関連項目: ブラウザツール
共通フラグ
--url <gatewayWsUrl>: Gateway WebSocket URL（デフォルトは設定値）。--token <token>: Gateway トークン（必要な場合）。--timeout <ms>: リクエストのタイムアウト（ミリ秒、デフォルト:30000）。--expect-final: Gateway の最終応答を待機します。--browser-profile <name>: ブラウザプロファイルを選択します（デフォルト:openclaw、またはbrowser.defaultProfile）。--json: 機械可読な出力（サポートされている場合）。これはブラウザレベルのオプションであるため、openclaw browser --json statusのように、曖昧さのない形式にするにはサブコマンドの前に配置します。 選択した子コマンドが独自の--jsonを定義していない場合は、openclaw browser status --jsonのように末尾へ配置しても機能します。
クイックスタート（ローカル）
browser({ action: "doctor" }) を使用して同じ準備状況チェックを実行できます。
クイックトラブルシューティング
start が not reachable after start で失敗する場合は、まず CDP の準備状況をトラブルシューティングしてください。start と tabs が成功しても open または navigate が失敗する場合、ブラウザ制御プレーンは正常であり、通常はナビゲーションの SSRF ポリシーによるブロックが原因です。
最小限の手順:
ライフサイクル
doctor --deepはライブスナップショットプローブを追加します。基本的な CDP の準備状況は正常でも、現在のタブを検査できることを確認したい場合に役立ちます。- 実行中のローカル管理対象プロファイルでは、
statusとdoctorが Chrome からキャッシュされた グラフィックス診断を報告します。これには、ハードウェア／ソフトウェアの分類、レンダラー、 バックエンド、デバイス／ドライバー、機能と無効化状態の詳細、アクセラレーション対応の 動画機能が含まれます。openclaw browser --json statusは完全な構造化ペイロードを返します。 パッシブなステータス確認では、これらの情報を収集するためだけに Chrome を起動することはありません。 stopは、OpenClaw 自体がブラウザプロセスを起動していないattachOnlyおよびリモート CDP プロファイルでも、アクティブな制御セッションを閉じ、一時的なエミュレーションのオーバーライドを消去します。ローカル管理対象プロファイルでは、stopは起動したブラウザプロセスも停止します。start --headlessはその起動リクエストにのみ適用され、OpenClaw がローカル管理対象ブラウザを起動する場合に限られます。browser.headlessやプロファイル設定を書き換えることはなく、すでに実行中のブラウザに対しては何も行いません。DISPLAYまたはWAYLAND_DISPLAYがない Linux ホストでは、OPENCLAW_BROWSER_HEADLESS=0、browser.headless=false、またはbrowser.profiles.<name>.headless=falseが表示ブラウザを明示的に要求しない限り、ローカル管理対象プロファイルは自動的にヘッドレスで実行されます。
コマンドが見つからない場合
openclaw browser が不明なコマンドである場合は、~/.openclaw/openclaw.json の plugins.allow を確認してください。plugins.allow が存在する場合、設定にルートの browser ブロックがすでにない限り、バンドルされたブラウザ Plugin を明示的に一覧へ追加します。
browser ブロック（たとえば browser.enabled=true または browser.profiles.<name>）がある場合も、制限付き Plugin 許可リストのもとでバンドルされたブラウザ Plugin が有効になります。
関連項目: ブラウザツール
プロファイル
プロファイルは、名前付きのブラウザルーティング設定です。openclaw（デフォルト）: OpenClaw が管理する専用の Chrome インスタンスを起動するか接続します（ユーザーデータディレクトリは分離されます）。user: Chrome DevTools MCP を介して、ログイン済みの既存の Chrome セッションを制御します。- カスタム CDP プロファイル: ローカルまたはリモートの CDP エンドポイントを指定します。
--browser-profile <name> を使用して特定のプロファイルを指定できます。例: openclaw browser --browser-profile work tabs。
macOS では、system-profiles はホスト上で利用可能な実際の Chrome、Brave、Edge、または Chromium のプロファイルを一覧表示します。import-profile は、macOS キーチェーン／Touch ID の同意プロンプトを一度表示した後に Cookie を復号し、新しい OpenClaw 管理対象プロファイルへ注入します。インポートされるのは Cookie のみで、ローカルストレージと IndexedDB は変更されません。一部の Google セッションではデバイスにバインドされたセッション認証情報（DBSC）が使用されるため、インポート後も再認証が必要になる場合があります。
macOS アプリがローカル Gateway を使用している場合、このインポートを一度提示し、分離されたインポート済みプロファイルをエージェントのブラウジング用デフォルトに設定できます。インポートには必ず明示的なクリックが必要です。インポートの成功またはダイアログの終了後は、それ以降の自動プロンプトが抑制され、再インポートには Settings → General → Browser login を引き続き使用できます。
システムプロファイルのインポートはデフォルトで有効です。CLI とエージェントが開始するインポートの両方を無効にするには、browser.allowSystemProfileImport=false を設定します。インポートはホストローカルであり、ブラウザ Node プロキシを介して実行することはできません。
タブ
tabs は最初に suggestedTargetId、続いて安定した tabId（t1 など）、任意のラベル、生の targetId を返します。suggestedTargetId を focus、close、スナップショット、およびアクションへ渡してください。open --label、tab new --label、または tab label でラベルを割り当てます。ラベル、タブ ID、生のターゲット ID、一意なターゲット ID プレフィックスのいずれも使用できます。互換性のため、リクエストフィールドの名前は引き続き targetId ですが、これらのタブ参照をすべて受け付けます。
生のターゲット ID は揮発性の診断用ハンドルであり、永続的なエージェントメモリではありません。ナビゲーションまたはフォーム送信中に Chromium が基盤となる生のターゲットを置き換えた場合、OpenClaw は一致を確認できれば、安定した tabId／ラベルを置換後のタブに維持します。suggestedTargetId を優先してください。
スナップショット／スクリーンショット／アクション
スナップショット:--full-pageはページキャプチャ専用です。--refまたは--elementと組み合わせることはできません。existing-session／userプロファイルでは、ページのスクリーンショットと、スナップショット出力の--refのスクリーンショットをサポートしますが、CSS--elementのスクリーンショットはサポートしません。--labelsは、現在のスナップショット参照をスクリーンショット上にオーバーレイします。Playwright ベースのプロファイルでは、--full-page（ページ全体のオーバーレイ）、--ref（ARIA 参照による要素クリップのオーバーレイ）、--element（CSS セレクターによる要素クリップのオーバーレイ）で機能します。要素クリップモードでは、ラベルは要素を基準に投影されます。応答には、各参照の境界ボックスを含むannotations配列（空の場合は省略）も含まれます。キャプチャ画像の座標空間（ビューポート／ページ全体／要素相対）におけるref、number、role、任意のname、およびbox: {x, y, width, height}が格納されます。existing-sessionプロファイルは、ページのスクリーンショット上に chrome-mcp オーバーレイをレンダリングしますが、Playwright の投影ヘルパーは使用せず、annotationsも含みません。CSS--elementのスクリーンショットはサポートされません。Playwright または chrome-mcp がない場合、ラベル付きスクリーンショットは利用できません。snapshot --urlsは、検出されたリンク先を AI スナップショットに追加します。これにより、エージェントはリンクテキストだけから推測せず、直接のナビゲーション先を選択できます。
evaluate --fn は、関数ソース、式、または文の本体を受け付けます。文の本体は非同期関数としてラップされるため、返したい値には return を使用します。ページ側の関数がデフォルトの評価タイムアウトより長い時間を必要とする可能性がある場合は、--timeout-ms を使用します。browser.evaluateEnabled=false（デフォルト: true）は、evaluate と wait --fn の両方を無効にします。
アクションの応答は、OpenClaw が置換後のタブを確認できる場合、アクションによるページ置換後の現在の生の targetId を返します。長時間実行するワークフローでは、スクリプトは引き続き suggestedTargetId／ラベルを保存して渡す必要があります。
ファイルとダイアログのヘルパー:
/tmp/openclaw/downloads、または設定された一時ルート）に保存します。エージェントが特定のファイルを待機してそのパスを返す必要がある場合は、waitfordownload または download を使用します。これらの明示的な待機処理は、次のダウンロードを占有します。アップロードでは、OpenClaw の一時アップロードルートおよび OpenClaw が管理する受信メディアにあるファイルを使用できます。これには、media://inbound/<id> とサンドボックス相対の media/inbound/<id> 参照が含まれます。ネストされたメディア参照、パストラバーサル、任意のローカルパスは拒否されます。
アクションによってモーダルダイアログが開かれた場合、アクションの応答は browserState.dialogs.pending を持つ blockedByDialog を返します。直接応答するには --dialog-id を渡します。OpenClaw の外部で処理されたダイアログは browserState.dialogs.recent に表示されます。
一括アクション:
openclaw browser batch は、ネストされた BrowserActRequest アクション（wait、click、type、evaluate、…）を含む kind="batch" /act リクエストを送信します。open/navigate/snapshot/screenshot は /act の種類ではなく CLI サブコマンドであるため、これらは送信しません。--continue は stopOnError=false を設定します（デフォルトでは最初のエラーで停止します）。--target-id はバッチ全体のスコープを 1 つのタブに限定します。ネストされたアクションが失敗すると、コマンドは 0 以外で終了します。順序付けられた results レスポンスを保持するには、--json を使用します。完全な契約（ref のライフサイクル、ターゲット ID の競合、エラーの概要）については、ブラウザバッチ CLIを参照してください。batch は profile="user" / 既存セッションプロファイルではサポートされていません。
状態とストレージ
ビューポート + エミュレーション:デバッグ
MCP 経由の既存の Chrome
組み込みのuser プロファイルを使用するか、独自の existing-session プロファイルを作成します。
--cdp-url を渡すと、Chrome MCP は代わりにそのエンドポイントへ接続します。Chrome MCP のセマンティクスが不要な Docker、Browserless、またはその他のリモート構成では、代わりに CDP プロファイルを使用します。
現在の既存セッションの制限:
- スナップショット駆動のアクションでは、CSS セレクターではなく ref を使用します。
- サポートされている
actリクエストでは、呼び出し元がtimeoutMsを省略した場合、組み込みのデフォルト値 60000 ms が使用されます。呼び出しごとのtimeoutMsが指定されている場合は、引き続きそちらが優先されます。 clickは左クリックのみです。typeはslowly=trueをサポートしていません。pressはdelayMsをサポートしていません。hover、scrollintoview、drag、select、およびfillは、呼び出しごとのタイムアウト上書きを拒否します。evaluateは--timeout-msを受け付けます。selectは 1 つの値のみをサポートします。wait --load networkidleはサポートされていません（管理対象および raw/リモート CDP プロファイルでは動作します）。- ファイルのアップロードには
--ref/--input-refが必要です。CSS--elementはサポートされず、一度に 1 つのファイルのみをサポートします。 - ダイアログフックは
--timeoutをサポートしていません。 - スクリーンショットはページキャプチャと
--refをサポートしますが、CSS--elementはサポートしません。 responsebody、ダウンロードのインターセプト、PDF エクスポート、およびバッチアクションには、引き続き管理対象ブラウザまたは raw CDP プロファイルが必要です。
リモートブラウザ制御（Node ホストプロキシ）
Gateway がブラウザとは異なるマシンで実行されている場合は、Chrome/Brave/Edge/Chromium があるマシン上で Node ホストを実行します。Gateway はブラウザアクションをその Node にプロキシします。別個のブラウザ制御サーバーは不要です。 自動ルーティングを制御するにはgateway.nodes.browser.mode を使用し、複数の Node が接続されている場合に特定の Node を固定するには gateway.nodes.browser.node を使用します。
セキュリティ + リモート設定: ブラウザツール、リモートアクセス、Tailscale、セキュリティ