openclaw browser
OpenClaw のブラウザー制御サーフェスを管理し、ブラウザーアクションを実行します: ライフサイクル、プロファイル、タブ、スナップショット、スクリーンショット、ナビゲーション、入力、状態エミュレーション、デバッグ。
関連: ブラウザーツール
共通フラグ
--url <gatewayWsUrl>: Gateway WebSocket URL (デフォルトは設定)。--token <token>: Gateway トークン (必要な場合)。--timeout <ms>: リクエストタイムアウト (ms、デフォルト:30000)。--expect-final: 最終 Gateway レスポンスを待ちます。--browser-profile <name>: ブラウザープロファイルを選択します (デフォルト:openclaw、またはbrowser.defaultProfile)。--json: 機械可読な出力 (対応している場合)。
クイックスタート (ローカル)
browser({ action: "doctor" }) で同じ準備状態チェックを実行できます。
クイックトラブルシューティング
start が not reachable after start で失敗する場合は、まず CDP 準備状態をトラブルシュートしてください。start と tabs は成功するが open または navigate が失敗する場合、ブラウザー制御プレーンは正常で、失敗の原因は通常ナビゲーション SSRF ポリシーブロックです。
最小シーケンス:
ライフサイクル
doctor --deepはライブスナップショットプローブを追加します: 基本的な CDP 準備状態は正常だが、現在のタブを検査できる証拠が必要な場合に便利です。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。
タブ
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 ref による要素クリップオーバーレイ)、--element(CSS セレクターによる要素クリップオーバーレイ) で動作します。要素クリップモードでは、ラベルは要素を基準に投影されます。レスポンスにはannotations配列 (空の場合は省略) も含まれ、各 ref の境界ボックスが含まれます: キャプチャ画像の座標空間 (ビューポート / フルページ / 要素相対) における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 は関数ソース、式、または文の本体を受け付けます。文の本体は async 関数としてラップされるため、返したい値には return を使用してください。ページ側の関数がデフォルトの evaluate タイムアウトより長くかかる可能性がある場合は、--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 に表示されます。
状態とストレージ
ビューポート + エミュレーション:デバッグ
MCP 経由の既存 Chrome
組み込みのuser プロファイルを使用するか、独自の existing-session プロファイルを作成します:
--cdp-url を渡してください。Docker、Browserless、または Chrome MCP セマンティクスが不要なその他のリモートセットアップでは、代わりに CDP プロファイルを使用してください。
現在の existing-session の制限:
- スナップショット駆動のアクションは CSS セレクターではなく refs を使用します。
browser.actionTimeoutMsは、呼び出し元がtimeoutMsを省略した場合、対応するactリクエストのデフォルトを 60000 ms にします。呼び出しごとのtimeoutMsが引き続き優先されます。clickは左クリックのみです。typeはslowly=trueに対応していません。pressはdelayMsに対応していません。hover、scrollintoview、drag、select、fill、evaluateは呼び出しごとのタイムアウト上書きを拒否します。selectは 1 つの値のみ対応します。wait --load networkidleはサポートされません (管理プロファイルおよび raw/remote CDP プロファイルでは動作します)。- ファイルアップロードには
--ref/--input-refが必要で、CSS--elementには対応せず、一度に 1 ファイルのみ対応します。 - ダイアログフックは
--timeoutに対応していません。 - スクリーンショットはページキャプチャと
--refに対応しますが、CSS--elementには対応していません。 responsebody、ダウンロードインターセプト、PDF エクスポート、バッチアクションには、引き続き管理ブラウザーまたは raw CDP プロファイルが必要です。
リモートブラウザー制御（ノードホストプロキシ）
Gateway がブラウザーとは別のマシンで実行されている場合は、Chrome/Brave/Edge/Chromium があるマシンでノードホストを実行します。Gateway はブラウザー操作をそのノードにプロキシします。別個のブラウザー制御サーバーは不要です。 自動ルーティングを制御するにはgateway.nodes.browser.mode を使用し、複数のノードが接続されている場合に特定のノードへ固定するには gateway.nodes.browser.node を使用します。
セキュリティ + リモートセットアップ: ブラウザーツール, リモートアクセス, Tailscale, セキュリティ