- これはエージェント専用の独立したブラウザと考えてください。
openclawプロファイルが個人用ブラウザプロファイルに触れることはありません。 - エージェントは、この分離された経路でタブを開き、ページを読み、クリックし、入力します。
- 一方、組み込みの
userプロファイルは、Chrome DevTools MCP を介して、実際にサインイン済みの Chrome セッションに接続します。
利用できる機能
- openclaw という名前の独立したブラウザプロファイル(デフォルトではオレンジ色のアクセント)。
- 決定論的なタブ制御(一覧表示/開く/フォーカス/閉じる)。
- エージェント操作(クリック/入力/ドラッグ/選択)、スナップショット、スクリーンショット、PDF。
- Playwright ベースのプロファイルは、添付ファイルへの直接ナビゲーションを管理対象のダウンロードディレクトリに保存し、最終 URL のポリシー検証後に
{ url, suggestedFilename, path }メタデータを返します。 - Playwright ベースのエージェント操作は、その操作によって 1 つ以上のダウンロードが直ちに開始された場合、同じ管理対象メタデータを含む
downloads配列を返します。 - ブラウザ Plugin が有効な場合に、スナップショット、
安定したタブ、古くなった参照、手動ブロッカーからの復旧ループをエージェントに教える、
バンドル済みの
browser-automationskill。 - オプションのマルチプロファイル対応(
openclaw、work、remote、…)。
openclaw browser CLI リファレンスを参照してください。
クイックスタート
browser.enabled が無効であることを意味します。
設定とPlugin の制御を参照してください。
openclaw browser が完全に見つからない場合、またはエージェントがブラウザツールを
利用できないと報告する場合は、ブラウザコマンドまたはツールが見つからない場合に進んでください。
Plugin の制御
デフォルトのbrowser ツールは、バンドル済みの Plugin です。同じ browser ツール名を登録する別の Plugin に置き換えるには、これを無効にします。
plugins.entries.browser.enabled と browser.enabled=true の両方が必要です。Plugin のみを無効にすると、openclaw browser CLI、browser.request Gateway メソッド、エージェントツール、制御サービスが一体として削除されます。置き換え用に browser.* 設定はそのまま維持されます。
ブラウザ設定を変更した場合、Plugin がサービスを再登録できるように Gateway の再起動が必要です。
エージェント向けガイダンス
ツールプロファイルに関する注意:tools.profile: "coding" には web_search と
web_fetch が含まれますが、完全な browser ツールは含まれません。エージェントまたは
生成されたサブエージェントがブラウザ自動化を使用できるようにするには、プロファイル
段階で browser を追加します。
agents.entries.*.tools.alsoAllow: ["browser"] を使用します。
サブエージェントのポリシーはプロファイルのフィルタリング後に適用されるため、
tools.subagents.tools.allow: ["browser"] だけでは不十分です。
ブラウザ Plugin には、2 段階のエージェント向けガイダンスが付属しています。
browserツールの説明には、常に有効な簡潔な契約が含まれています。適切なプロファイルを選択し、 参照を同じタブ内に維持し、タブの対象指定にはtabId/ラベルを使用し、 複数ステップの作業ではブラウザ skill を読み込みます。- バンドル済みの
browser-automationskill には、より詳細な操作ループが含まれています。 まずステータスとタブを確認し、タスク用タブにラベルを付け、操作前にスナップショットを取得し、UI の変更後に 再度スナップショットを取得し、古くなった参照から一度だけ復旧を試み、ログイン/2FA/CAPTCHA や カメラ/マイクのブロッカーについては推測せず、手動操作が必要であると報告します。
ブラウザコマンドまたはツールが見つからない場合
アップグレード後にopenclaw browser が認識されない、browser.request が見つからない、またはエージェントがブラウザツールを利用できないと報告する場合、通常の原因は、browser を含まない plugins.allow リストがあり、ルートの browser 設定ブロックが存在しないことです。次のように追加します。
browser ブロック(browser 配下の任意のキー。たとえば
browser.enabled=true または browser.profiles.<name>)は、制限的な plugins.allow のもとでも
バンドル済みのブラウザ Plugin を有効化し、バンドル済みチャンネルの設定動作と一致します。
plugins.entries.browser.enabled=true と tools.alsoAllow: ["browser"] は、それだけでは
許可リストへの登録の代わりにはなりません。plugins.allow を完全に削除しても、デフォルトが復元されます。
プロファイル: openclaw、user、chrome
openclaw: 管理された分離ブラウザ(拡張機能は不要)。user: 実際にサインイン済みの Chrome セッション用の、組み込み Chrome DevTools MCP 接続プロファイル。OpenClaw が初めて接続するとき、Chrome に処理をブロックする「Allow remote debugging?」 プロンプトが表示されるため、誰かがコンピューターの前にいる必要があります。chrome: 実際にサインイン済みの Chrome セッション用の、組み込みChrome 拡張機能プロファイル。 リモートデバッグポートではなく OpenClaw ブラウザ拡張機能を介してタブを操作するため、 「Allow remote debugging?」プロンプトは表示されません。そのため、デスクに誰もいなくても スマートフォンから動作します。
- デフォルト: 分離された
openclawブラウザを使用します。 - 既存のログイン済みセッションが重要で、ユーザーがコンピューターから離れている
場合(Telegram、WhatsApp など)は、
profile="chrome"(拡張機能)を優先します。 - 既存のログイン済みセッションが重要で、ユーザーが接続プロンプトを承認するため
コンピューターの前にいる場合は、
profile="user"(Chrome MCP)を優先します。 - 特定のブラウザモードを使用する場合、
profileで明示的に上書きします。
browser.defaultProfile: "openclaw" を設定します。
設定
ブラウザ設定は~/.openclaw/openclaw.json にあります。
browser.snapshotDefaults.mode: "efficient" は、呼び出し元が明示的な snapshotFormat または
mode を渡さなかった場合の、デフォルトの snapshot
抽出モードを変更します。呼び出しごとのスナップショットオプションについては、
ブラウザ制御 APIを参照してください。
タブクリーンアップの所有権
セッションのタブクリーンアップは、OpenClaw ブラウザツールがaction: "open" で作成したタブにのみ適用されます。OpenClaw は、すでに開かれていたタブ、
ユーザーが開いたタブ、または所有権が不明なタブを引き継ぎません。
browser.tabCleanup ブロックは、プライマリセッションに対する定期的なアイドル状態および上限の
スイープを制御します。これを無効にしても、明示的なセッションライフサイクルのクリーンアップは無効になりません。
ホストローカルで開いた場合、安定したネイティブ CDP ターゲットとブラウザ
ID による所有権が共有 SQLite 状態に保存されます。これらのレコードは Gateway の
再起動後も維持され、/new およびその他のセッションライフサイクルクリーンアップの対象であり続けます。
セッションライフサイクルクリーンアップには、サブエージェント、Cron、ACP セッションの終了が含まれます。
ツール向けターゲットがネイティブ CDP ターゲットであるレコードは、再起動後も
アイドル状態およびセッションごとの上限スイープの対象であり続けます。Chrome MCP のターゲットハンドルは
プロセスローカルであるため、コールド状態の既存セッションレコードは、再起動後に安全に帰属できない
アクティビティに対してアイドルスイープを行うリスクを避け、ライフサイクルクリーンアップを待機します。
この永続的な経路は、OpenClaw 管理プロファイル、通常のリモート CDP プロファイル、および明示的な
cdpUrl を持つ既存セッションプロファイルを対象にできます。ただし、OpenClaw がネイティブターゲットと安定した
ブラウザ ID の両方を解決できる必要があります。永続レコードを閉じる前に、OpenClaw は
設定されたプロファイルとブラウザインスタンスが引き続き一致していることを確認します。
Chrome MCP --autoConnect、/json/version の応答に安定したブラウザ ID がない
CDP エンドポイント、およびネイティブターゲットを解決できないオープン操作は、
プロセスローカルのベストエフォート追跡のままです。その Gateway プロセスが実行中であれば
クリーンアップできますが、Gateway の再起動後に自動的に閉じられることはありません。
永続追跡が利用可能になる前から開いていたタブは、遡及的に引き継がれません。そのようなタブは手動で閉じてください。
クリーンアップはベストエフォートであり、対象となるすべてのタブが
直ちに閉じられることを保証するものではありません。一時的な所有権確認またはクローズの失敗が発生した場合、永続的な
クリーンアップは後で再試行できるよう保留されます。再試行は無制限ではありません。ブラウザに
到達できない状態が続き、タブが 1 日を超えて使用されていない場合、その追跡行は
廃止され、二度と検証できないタブで永続ストアが埋まらないようにします。
スクリーンショットの視覚認識(テキスト専用モデルのサポート)
メインモデルがテキスト専用(視覚/マルチモーダル非対応)の場合、ブラウザの スクリーンショットは、そのモデルが読み取れない画像ブロックを返します。ブラウザのスクリーンショットは 既存の画像理解設定を再利用するため、メディア理解用に設定された画像モデルは、 ブラウザ固有のモデル設定なしでスクリーンショットをテキストとして説明できます。- エージェントが
browser screenshotを呼び出すと、通常どおり画像がディスクに保存されます。 - ブラウザツールは、設定済みのメディア画像モデル、共有メディアモデル、画像モデルのデフォルト、または認証に基づく画像プロバイダーを使用してスクリーンショットを説明できるかどうかを、既存の画像理解ランタイムに問い合わせます。
- ビジョンモデルはテキストの説明を返します。これは
wrapExternalContent(プロンプトインジェクションガード)でラップされ、画像ブロックではなくテキストブロックとしてエージェントに返されます。 - 画像理解が利用できない場合、スキップされた場合、または失敗した場合、ブラウザは元の画像ブロックを返すようフォールバックします。
tools.media.image / tools.media.models フィールドを使用してください。
アクティブなメインモデルがすでにビジョンをサポートしており、明示的な画像理解モデルが設定されていない場合、OpenClaw は通常の画像結果を維持し、メインモデルがスクリーンショットを直接読み取れるようにします。
ポートと到達可能性
ポートと到達可能性
- 制御サービスは、
gateway.portから派生したポート(デフォルトは18791= Gateway + 2)のループバックにバインドします。OPENCLAW_GATEWAY_PORTはgateway.portより優先され、どちらを使用しても同じポート系列の派生ポートが移動します。 - ローカルの
openclawプロファイルは、制御ポートの9ポート上から始まる範囲(デフォルトは18800~18899)からcdpPort/cdpUrlを自動割り当てします。これらを設定するのは、リモート CDP プロファイルまたは既存セッションのエンドポイントへの接続の場合だけにしてください。cdpUrlが未設定の場合、管理対象のローカル CDP ポートがデフォルトになります。 - リモートおよび
attachOnlyの CDP 到達可能性、WebSocket ハンドシェイク、ローカルの管理対象 Chrome の起動には、組み込みの期限が使用されます。 - 管理対象 Chrome の起動または準備完了が繰り返し失敗すると、プロファイルごとにサーキットブレーカーが作動します。数回連続して失敗すると、ブラウザツールの呼び出しごとに Chromium を起動する代わりに、OpenClaw は新しい起動試行を短時間停止します。起動時の問題を修正するか、ブラウザが不要な場合は無効にするか、修復後に Gateway を再起動してください。
SSRF ポリシー
SSRF ポリシー
- ブラウザのナビゲーションおよびタブを開くリクエストは、事前チェックされます。アクションの実行中および制限されたアクション後の猶予期間中、保護された Playwright 操作(クリック、座標クリック、ホバー、ドラッグ、スクロール、選択、キー入力、テキスト入力、フォーム入力、evaluate)は、HTTP リクエストのバイトが送信される前に、ポリシーで拒否されたトップレベルおよびサブフレームのドキュメント読み込みを遮断し、その後、最終的な
http(s)URL をベストエフォートで再チェックします。 - OpenClaw が管理する Chrome を新たに起動するたびに、OpenClaw はベストエフォートでネットワーク予測を無効化し、拒否された読み込みに対して Chromium で確認されている投機的な事前接続を抑止します。これは多層防御であり、ポリシー境界ではありません。制御サービスの再起動をまたいで再利用されるブラウザや、その他のブラウザバックエンドには、この強化策が適用されない可能性があります。Playwright のルーティングは依然としてネットワークファイアウォールではなく、リダイレクトの各段階、ポップアップの最初のリクエスト、Service Worker のトラフィック、制限されたガード期間後に実行されるページコード、またはすべてのバックグラウンド/サブリソース経路を遮断するものではありません。完全な外向き通信の分離には、所有者側での分離またはポリシーを適用するプロキシが必要です。
- 厳格な SSRF モードでは、リモート CDP エンドポイントの検出および
/json/versionプローブ(cdpUrl)もチェックされます。 - Gateway/プロバイダーの
HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、およびNO_PROXY環境変数によって、OpenClaw 管理ブラウザが自動的にプロキシ経由になることはありません。プロバイダーのプロキシ設定によってブラウザの SSRF チェックが弱まらないように、管理対象 Chrome はデフォルトで直接接続を使用して起動します。 - OpenClaw が管理するローカル CDP の準備完了プローブおよび DevTools WebSocket 接続は、起動された正確なループバックエンドポイントについて管理対象ネットワークプロキシを迂回するため、オペレーターのプロキシがループバックへの外向き通信をブロックしている場合でも
openclaw browser startは機能します。 - 管理対象ブラウザ自体をプロキシ経由にするには、
browser.extraArgsを通じて--proxy-server=...や--proxy-pac-url=...などの明示的な Chrome プロキシフラグを渡してください。厳格な SSRF モードでは、プライベートネットワークへのブラウザアクセスが意図的に有効化されていない限り、明示的なブラウザのプロキシルーティングがブロックされます。 browser.ssrfPolicy.dangerouslyAllowPrivateNetworkはデフォルトで無効です。プライベートネットワークへのブラウザアクセスを意図的に信頼する場合にのみ有効にしてください。browser.ssrfPolicy.allowPrivateNetworkは従来のエイリアスとして引き続きサポートされます。
プロファイルの動作
プロファイルの動作
attachOnly: trueは、ローカルブラウザを起動せず、すでに実行中のブラウザがある場合にのみ接続することを意味します。headlessは、グローバルまたはローカルの管理対象プロファイルごとに設定できます。プロファイルごとの値はbrowser.headlessを上書きするため、ローカルで起動した1つのプロファイルをヘッドレスのままにし、別のプロファイルを表示状態にできます。POST /start?headless=trueおよびopenclaw browser start --headlessは、browser.headlessまたはプロファイル設定を書き換えることなく、ローカルの管理対象プロファイルに対して1回限りのヘッドレス起動を要求します。既存セッション、接続専用、およびリモート CDP プロファイルでは、OpenClaw がそれらのブラウザプロセスを起動しないため、この上書きは拒否されます。DISPLAYまたはWAYLAND_DISPLAYのない Linux ホストでは、環境またはプロファイル/グローバル設定で表示モードが明示的に選択されていない場合、ローカルの管理対象プロファイルは自動的にヘッドレスをデフォルトとします。曖昧さのないブラウザレベルの形式openclaw browser --json statusを使用してください。statusは独自の--jsonを定義していないため、末尾のopenclaw browser status --jsonも機能します。このコマンドは、headlessSourceをenv、profile、config、request、linux-display-fallback、またはdefaultとして報告します。OPENCLAW_BROWSER_HEADLESS=1は、現在のプロセスにおけるローカルの管理対象ブラウザの起動を強制的にヘッドレスにします。OPENCLAW_BROWSER_HEADLESS=0は通常の起動を強制的に表示モードにし、ディスプレイサーバーのない Linux ホストでは対処方法を示すエラーを返します。ただし、明示的なstart --headlessリクエストは、その1回の起動について引き続き優先されます。- ブラウザ制御ルートとプログラムクライアントは、ディスプレイがない場合のエラーについて、人間が読める
errorを維持し、安定した理由no_display_for_headed_profileを公開します。そのdetailsにはprofile、requestedHeadless、headlessSource、およびdisplayPresentのみが含まれるため、API クライアントはメッセージテキストを照合せずに正しい修復方法を選択できます。 - 実行中のローカル管理対象プロファイルに対し、status と doctor は Chrome のブラウザレベル CDP エンドポイントを照会し、レンダラー、バックエンド、デバイス/ドライバー、機能の状態、ドライバーの回避策、アクセラレーション動画機能を取得します。結果はそのブラウザプロセスについてキャッシュされ、
openclaw browser --json statusによって完全な形で公開されます。受動的な status 呼び出しでは Chrome は起動されません。既存セッション、拡張機能、リモート CDP、およびサンドボックスブラウザは引き続き別扱いとなり、この管理対象ホスト経路を通じて検査されることはありません。 - ヘッドレスの管理対象 Chrome でも、保守的な
--disable-gpuのデフォルトが引き続き使用されます。診断によってアクセラレーションが有効化されたり、グローバルなアクセラレーション設定が追加されたり、サンドボックスブラウザにデバイスアクセスが付与されたりすることはありません。 executablePathは、グローバルまたはローカルの管理対象プロファイルごとに設定できます。プロファイルごとの値はbrowser.executablePathを上書きするため、管理対象プロファイルごとに異なる Chromium ベースのブラウザを起動できます。どちらの形式でも、OS のホームディレクトリを表す~を使用できます。color(トップレベルおよびプロファイルごと)はブラウザ UI に色を付け、どのプロファイルがアクティブかを確認できるようにします。- デフォルトプロファイルは
openclaw(管理対象のスタンドアロン)です。サインイン済みのユーザーブラウザを使用するには、defaultProfile: "user"を使用してください。 - 自動検出の順序:Chromium ベースの場合はシステムのデフォルトブラウザ、それ以外は Chrome、Brave、Edge、Chromium、Chrome Canary。
driver: "existing-session"は、生の CDP の代わりに Chrome DevTools MCP を使用します。Chrome MCP の自動接続を通じて接続するか、実行中のブラウザ用の DevTools エンドポイントがすでにある場合はcdpUrlを通じて接続できます。driver: "extension"は、OpenClaw Chrome 拡張機能を通じてサインイン済みの Chrome を操作します。リレーが自身のループバックエンドポイントを所有するため、これらのプロファイルはcdpUrlを受け付けません。これは、コンピューターの前に誰もいない状態でも機能する唯一のサインイン済みブラウザモードです。- 既存セッションのプロファイルをデフォルト以外の Chromium ユーザープロファイル(Brave、Edge など)に接続する場合は、
browser.profiles.<name>.userDataDirを設定してください。この経路では、OS のホームディレクトリを表す~も使用できます。
Brave または別の Chromium ベースのブラウザを使用する
システムのデフォルトブラウザが Chromium ベース(Chrome/Brave/Edge など)の場合、OpenClaw はそれを自動的に使用します。自動検出を上書きするには、browser.executablePath を設定してください。トップレベルおよびプロファイルごとの executablePath 値では、OS のホームディレクトリを表す ~ を使用できます。
- macOS
- Windows
- Linux
executablePath は、OpenClaw が起動するローカルの管理対象プロファイルにのみ影響します。existing-session プロファイルは代わりにすでに実行中のブラウザへ接続し、リモート CDP プロファイルは cdpUrl の接続先ブラウザを使用します。
ローカル制御とリモート制御
- ローカル制御(デフォルト): Gateway がループバック制御サービスを開始し、ローカルブラウザを起動できます。
- リモート制御(Node ホスト): ブラウザがあるマシンで Node ホストを実行します。Gateway はブラウザ操作をそのホストにプロキシします。
- リモート CDP: リモートの Chromium ベースブラウザに接続するには、
browser.profiles.<name>.cdpUrl(またはbrowser.cdpUrl)を設定します。この場合、OpenClaw はローカルブラウザを起動しません。 - ループバック上の外部管理 CDP サービス(たとえば Docker で
127.0.0.1に公開された Browserless)の場合は、attachOnly: trueも設定してください。attachOnlyのないループバック CDP は、OpenClaw が管理するローカルブラウザプロファイルとして扱われます。 headlessは、OpenClaw が起動するローカルの管理対象プロファイルにのみ影響します。既存セッションまたはリモート CDP ブラウザを再起動したり変更したりすることはありません。executablePathにも、同じローカル管理対象プロファイルのルールが適用されます。実行中のローカル管理対象プロファイルでこれを変更すると、そのプロファイルは再起動/再調整の対象としてマークされ、次回の起動で新しいバイナリが使用されます。
- ローカル管理対象プロファイル:
openclaw browser stopは、OpenClaw が起動したブラウザプロセスを停止します - 接続専用およびリモート CDP プロファイル:
openclaw browser stopは、OpenClaw がブラウザプロセスを起動していなくても、アクティブな制御セッションを閉じ、Playwright/CDP のエミュレーション上書き(ビューポート、カラースキーム、ロケール、タイムゾーン、オフラインモード、および同様の状態)を解除します
- クエリトークン(例:
https://provider.example?token=<token>) - HTTP Basic 認証(例:
https://user:pass@provider.example)
/json/* エンドポイントの呼び出し時および
CDP WebSocket への接続時に認証情報を保持します。トークンを設定ファイルに
コミットするのではなく、環境変数またはシークレットマネージャーを使用してください。
Node ブラウザプロキシ(設定不要のデフォルト)
ブラウザがあるマシンで Node ホストを実行すると、OpenClaw は追加のブラウザ設定なしで、 ブラウザツールの呼び出しをその Node に自動的にルーティングできます。 これはリモート Gateway のデフォルト経路です。 注記:- Node ホストは、ローカルのブラウザ制御サーバーをプロキシコマンド経由で公開します。
- プロファイルは Node 自身の
browser.profiles設定(ローカルと同じ)から取得されます。 - プロキシコマンドは、
allowProfilesの設定にかかわらず、永続的なプロファイル変更(create-profile、delete-profile、reset-profile)を許可しません。これらの変更は Node 上で直接行ってください。 nodeHost.browserProxy.allowProfilesは任意です。従来のデフォルト動作を使用する場合は空のままにしてください。設定済みのすべてのプロファイルにプロキシ経由で引き続きアクセスできます。nodeHost.browserProxy.allowProfilesを設定すると、OpenClaw はこれを最小権限の境界として扱い、プロキシが対象にできるプロファイル名を制限します。- 使用しない場合は無効にしてください:
- Node 側:
nodeHost.browserProxy.enabled=false - Gateway 側:
gateway.nodes.browser.mode="off"(接続済みブラウザ Node を1つ選択するための"auto"、または明示的な Node パラメーターを必須にするための"manual"も指定できます)
- Node 側:
Browserless(ホスト型リモート CDP)
Browserless は、HTTPS および WebSocket 経由で CDP 接続 URL を公開するホスト型 Chromium サービスです。OpenClaw はどちらの形式も使用できますが、 リモートブラウザプロファイルでは、Browserless の接続ドキュメントに記載されている 直接 WebSocket URL を使用するのが最も簡単です。 例:<BROWSERLESS_API_KEY>を実際の Browserless トークンに置き換えてください。- Browserless アカウントに対応するリージョンエンドポイントを選択してください(同社のドキュメントを参照)。
- Browserless から HTTPS ベース URL が提供された場合は、直接 CDP 接続用の
wss://に変換するか、HTTPS URL のままにして OpenClaw に/json/versionを検出させることができます。
同一ホスト上の Browserless Docker
Browserless を Docker でセルフホストし、OpenClaw をホスト上で実行する場合は、 Browserless を外部管理の CDP サービスとして扱います:browser.profiles.browserless.cdpUrl のアドレスは、
OpenClaw プロセスから到達可能でなければなりません。また、Browserless は到達可能な対応エンドポイントを通知する必要があります。
Browserless の EXTERNAL を、ws://127.0.0.1:3000、ws://browserless:3000、または安定したプライベート Docker
ネットワークアドレスなど、OpenClaw から到達可能な同じ WebSocket ベースに設定してください。
/json/version が、OpenClaw から到達できないアドレスを指す
webSocketDebuggerUrl を返す場合、CDP HTTP が正常に見えても WebSocket
アタッチは失敗します。
local loopback の Browserless プロファイルでは、attachOnly を未設定のままにしないでください。
attachOnly がない場合、OpenClaw は local loopback ポートをローカル管理のブラウザ
プロファイルとして扱い、そのポートは使用中だが OpenClaw が所有していないと報告する場合があります。
直接 WebSocket CDP プロバイダー
一部のホスト型ブラウザサービスは、標準の HTTP ベースの CDP 検出(/json/version)ではなく、
直接 WebSocket エンドポイントを公開します。OpenClaw は3種類の
CDP URL 形式を受け付け、適切な接続方式を自動的に選択します:
- HTTP(S) 検出 -
http://host[:port]またはhttps://host[:port]。 OpenClaw は/json/versionを呼び出して WebSocket デバッガー URL を検出し、その後 接続します。WebSocket へのフォールバックはありません。 - 直接 WebSocket エンドポイント -
/devtools/browser|page|worker|shared_worker|service_worker/<id>パスを持つws://host[:port]/devtools/<kind>/<id>またはwss://...。 OpenClaw は WebSocket ハンドシェイクを介して直接接続し、/json/versionを完全にスキップします。 - ベア WebSocket ルート -
/devtools/...パスを持たないws://host[:port]またはwss://host[:port](例: Browserless、 Browserbase)。OpenClaw は最初に HTTP/json/version検出を試みます(スキームをhttp/httpsに正規化)。 検出でwebSocketDebuggerUrlが返された場合はそれを使用し、それ以外の場合は ベアルートでの直接 WebSocket ハンドシェイクにフォールバックします。通知された WebSocket エンドポイントが CDP ハンドシェイクを拒否しても、設定されたベアルートが 受け入れる場合、OpenClaw はそのルートにもフォールバックします。これにより、ローカルの Chrome を指すベアws://でも接続できます。Chrome は/json/versionから取得したターゲット固有の パスでのみ WebSocket アップグレードを受け入れる一方、ホスト型 プロバイダーは、検出エンドポイントが Playwright CDP に適さない 短期間有効な URL を通知する場合でも、ルート WebSocket エンドポイントを使用できます。
openclaw browser doctor は、実行時アタッチと同じ検出優先・WebSocket フォールバック
ロジックを使用するため、正常に接続できるベアルート URL が診断で
到達不能と報告されることはありません。
Browserbase
Browserbase は、組み込みの CAPTCHA 解決、ステルスモード、住宅用 プロキシを備えたヘッドレスブラウザを実行するためのクラウドプラットフォームです。- サインアップし、Overview dashboard から API Key をコピーしてください。
<BROWSERBASE_API_KEY>を実際の Browserbase API キーに置き換えてください。- Browserbase は WebSocket 接続時にブラウザセッションを自動作成するため、 手動でセッションを作成する必要はありません。
- 現在の無料枠の制限と有料プランについては、料金を参照してください。
- 完全な API リファレンス、SDK ガイド、統合例については、 Browserbase ドキュメントを参照してください。
Notte
Notte は、組み込みのステルス機能、住宅用プロキシ、CDP ネイティブの WebSocket Gateway を備えたヘッドレスブラウザを実行するためのクラウドプラットフォームです。- サインアップし、コンソールの設定ページから API Key を コピーしてください。
<NOTTE_API_KEY>を実際の Notte API キーに置き換えてください。- Notte は WebSocket 接続時にブラウザセッションを自動作成するため、手動で セッションを作成する必要はありません。WebSocket が切断されると、 セッションは破棄されます。
- 現在の無料枠の制限と有料プランについては、料金を参照してください。
- 完全な API リファレンス、SDK ガイド、統合例については、 Notte ドキュメントを参照してください。
セキュリティ
重要なポイント:- ブラウザ制御は local loopback 限定です。アクセスは Gateway の認証または Node のペアリングを経由します。
- スタンドアロンの local loopback ブラウザ HTTP API は、共有シークレット認証のみを使用します:
Gateway トークンの Bearer 認証、
x-openclaw-password、または設定済みの Gateway パスワードによる HTTP Basic 認証です。 - Tailscale Serve の ID ヘッダーと
gateway.auth.mode: "trusted-proxy"は、 このスタンドアロンの local loopback ブラウザ API を認証しません。 - ブラウザ制御が有効で共有シークレット認証が設定されていない場合、OpenClaw は
起動時にブラウザ制御用の認証情報を自動生成して永続化します:
gateway.auth.modeがnoneの場合はトークン、trusted-proxyの場合は パスワードです(プロセス外の local loopback クライアントが解決できるように、gateway.auth.passwordを介して永続化されます)。そのモード用の明示的な 文字列認証情報がすでに設定されている場合、またはgateway.auth.modeがpasswordの場合、自動生成は行われません。 - 生成されたシークレットではなく、自身で管理する安定したシークレットを使用する場合は、
gateway.auth.token、gateway.auth.password、OPENCLAW_GATEWAY_TOKEN、またはOPENCLAW_GATEWAY_PASSWORDを明示的に設定してください。
- 可能な場合は、暗号化されたエンドポイント(HTTPS または WSS)と短期間有効なトークンを使用してください。
- 長期間有効なトークンを設定ファイルに直接埋め込まないでください。
- Gateway とすべての Node ホストをプライベートネットワーク(Tailscale)上に配置し、公開を避けてください。
- リモート CDP の URL/トークンはシークレットとして扱い、環境変数またはシークレットマネージャーを使用してください。
プロファイル(複数ブラウザ)
OpenClaw は複数の名前付きプロファイル(ルーティング設定)をサポートします。プロファイルには次の種類があります:- OpenClaw 管理: 独自のユーザーデータディレクトリと CDP ポートを持つ専用の Chromium ベースのブラウザインスタンス
- リモート: 明示的な CDP URL(別の場所で実行されている Chromium ベースのブラウザ)
- 既存のセッション: Chrome DevTools MCP の自動接続を介した既存の Chrome プロファイル
openclawプロファイルが存在しない場合は自動作成されます。userプロファイルは、Chrome MCP の既存セッションへのアタッチ用として組み込まれています。- 既存セッションプロファイルは
user以外ではオプトインです。--driver existing-sessionで作成してください。 - ローカル CDP ポートはデフォルトで 18800-18899 から割り当てられます。
- プロファイルを削除すると、そのローカルデータディレクトリはゴミ箱に移動されます。
?profile=<name> を受け付け、CLI は --browser-profile を使用します。
Chrome DevTools MCP を介した既存セッション
OpenClaw は、公式の Chrome DevTools MCP サーバーを介して、実行中の Chromium ベースの ブラウザプロファイルにアタッチすることもできます。これにより、そのブラウザプロファイルですでに開いている タブとログイン状態が再利用されます。 公式の背景情報とセットアップの参考資料: 組み込みプロファイル:user。別の名前、色、またはブラウザデータディレクトリを使用する場合は、
独自の既存セッションプロファイルを作成してください。
デフォルトでは、組み込みの user プロファイルは Chrome MCP の自動接続を使用し、
デフォルトのローカル Google Chrome プロファイルを対象にします。Brave、
Edge、Chromium、またはデフォルト以外の Chrome プロファイルには userDataDir を使用してください。~ は OS のホーム
ディレクトリに展開されます:
- リモートデバッグ用のブラウザの検査ページを開きます。
- リモートデバッグを有効にします。
- ブラウザを実行したままにし、OpenClaw がアタッチするときに接続プロンプトを承認します。
- Chrome:
chrome://inspect/#remote-debugging - Brave:
brave://inspect/#remote-debugging - Edge:
edge://inspect/#remote-debugging
statusはdriver: existing-sessionを表示しますstatusはtransport: chrome-mcpを表示しますstatusはrunning: trueを表示しますtabsは、すでに開いているブラウザータブを一覧表示しますsnapshotは、選択したライブタブから ref を返します
- 対象の Chromium ベースのブラウザーのバージョンが
144+である - そのブラウザーの検査ページでリモートデバッグが有効になっている
- ブラウザーにアタッチ同意プロンプトが表示され、それを承認した
- Chrome が明示的な
--remote-debugging-portを指定して起動された場合は、Chrome MCP の自動接続に 依存せず、browser.profiles.<name>.cdpUrlをその DevTools エンドポイントに設定する openclaw doctorは、古い拡張機能ベースのブラウザー設定を移行し、 デフォルトの自動接続プロファイル向けに Chrome がローカルにインストールされているか確認しますが、 ブラウザー側のリモートデバッグを有効にすることはできません
- ユーザーがログイン済みのブラウザー状態が必要な場合は、
profile="user"を使用します。 - カスタムの既存セッションプロファイルを使用する場合は、その明示的なプロファイル名を渡します。
- ユーザーがコンピューターの前にいて、アタッチプロンプトを承認できる場合にのみ、このモードを選択します。
- Gateway または Node ホストは
npx chrome-devtools-mcp@latest --autoConnectを起動できます。
- このパスは、ログイン済みのブラウザーセッション内で操作できるため、分離された
openclawプロファイルよりもリスクが高くなります。 - OpenClaw はこのドライバー用のブラウザーを起動せず、アタッチのみを行います。
- ここでは、OpenClaw は公式の Chrome DevTools MCP
--autoConnectフローを使用します。userDataDirが設定されている場合、そのユーザーデータディレクトリを対象にするため、そのまま渡されます。 - 既存セッションは、選択したホスト上、または接続済みのブラウザー Node 経由でアタッチできます。 Chrome が別の場所にあり、ブラウザー Node が接続されていない場合は、代わりにリモート CDP または Node ホストを使用します。
- Chrome MCP のターゲットとスナップショット ref は、1 つの MCP サブプロセスにスコープされます。
そのプロセスが再起動した後は、
browser tabsを再度実行し、ターゲット固有の作業を行う前に 新しいターゲットを明示的に選択し、ref を使用する前に新しいスナップショットを取得します。 各 ref は、そのターゲットと最新のスナップショットに対してのみ有効です。URL が一致していても、 古いエイリアスは置き換え先のタブには引き継がれません。 - Chrome DevTools MCP は現在、プロセスローカルの数値ページ ID に基づいてページツールを ルーティングします。プロセススコープのハンドルにより、サブプロセス置換をまたいだ再利用は防止されますが、 隣接するツール呼び出しの間にプロセス内でブラウザーコンテキストが置き換えられると、操作の対象が 切り替わる可能性は残ります。完全にアトミックなルーティングには、安定したターゲット ID に対する アップストリームのページツールサポートが必要です。
カスタム Chrome MCP 起動
デフォルトのnpx chrome-devtools-mcp@latest フローが要件に合わない場合
(オフラインホスト、固定バージョン、ベンダー提供バイナリ)は、プロファイルごとに
起動される Chrome DevTools MCP サーバーを上書きします:
既存セッションプロファイルに
cdpUrl が設定されている場合、OpenClaw は
--autoConnect をスキップし、エンドポイントを Chrome MCP に自動的に転送します:
http(s)://...→--browserUrl <url>(DevTools HTTP 検出エンドポイント)。ws(s)://...→--wsEndpoint <url>(直接接続する CDP WebSocket)。
userDataDir は併用できません。cdpUrl が設定されている場合、
Chrome MCP はプロファイルディレクトリを開くのではなく、エンドポイントの背後で実行中のブラウザーに
アタッチするため、Chrome MCP の起動時に userDataDir は無視されます。
既存セッション機能の制限
既存セッション機能の制限
マネージド
openclaw プロファイルと比べると、既存セッションドライバーにはより多くの制約があります:- スクリーンショット - ページキャプチャと
--ref要素キャプチャは機能しますが、CSS--elementセレクターは機能しません。ページまたは ref ベースの要素スクリーンショットに Playwright は不要です。(--full-pageは既存セッションに限らず、どのプロファイルでも--refまたは--elementと併用できません。) - 操作 -
click、type、hover、scrollIntoView、drag、selectにはスナップショット ref が必要です(CSS セレクターは使用できません)。click-coordsは表示中のビューポート座標をクリックし、スナップショット ref は不要です。clickは左ボタンのみに対応します(ボタンの上書きや修飾キーは使用できません)。typeはslowly=trueをサポートしていません。fillまたはpressを使用してください。pressはdelayMsをサポートしていません。type、hover、scrollIntoView、drag、select、fillは、呼び出しごとのtimeoutMsの上書きをサポートしていませんが、evaluateはサポートしています。selectは単一の値を受け付けます。batchはサポートされていないため、操作を個別に送信してください。 - 待機 / アップロード / ダイアログ -
wait --urlは完全一致、部分文字列、glob パターンをサポートします(マネージドと同じ)。wait --load networkidleは既存セッションプロファイルではサポートされません(マネージドおよび raw/リモート CDP プロファイルでは機能します)。アップロードフックにはrefまたはinputRefが必要で、ファイルは一度に 1 つ、CSSelementは使用できません。ダイアログフックでは、タイムアウトの上書きやdialogIdはサポートされません。 - ダイアログの可視性 - マネージドブラウザーの操作レスポンスには、操作によってモーダルダイアログが開かれた場合に
blockedByDialogとbrowserState.dialogs.pendingが含まれます。スナップショットにも保留中のダイアログ状態が含まれます。ダイアログが保留中の間は、browser dialog --accept/--dismiss --dialog-id <id>で応答してください。OpenClaw の外部で処理されたダイアログは、browserState.dialogs.recentの下に表示されます。 - マネージド専用機能 - PDF エクスポート、ダウンロードのインターセプト、
responsebodyには、引き続きマネージドブラウザーパスが必要です。
分離の保証
- 専用ユーザーデータディレクトリ: 個人用ブラウザープロファイルには一切アクセスしません。
- 専用ポート: 開発ワークフローとの競合を防ぐため、
9222を回避します。 - 決定的なタブ制御:
tabsは、最初にsuggestedTargetIdを返し、続いてt1などの安定したtabIdハンドル、オプションのラベル、生のtargetIdを返します。 エージェントはsuggestedTargetIdを再利用する必要があります。生の ID は、 デバッグと互換性のために引き続き利用できます。
ブラウザーの選択
ローカルで起動する場合、OpenClaw は最初に利用可能なものを選択します:- Chrome
- Brave
- Edge
- Chromium
- Chrome Canary
browser.executablePath で上書きできます。
プラットフォーム:
- macOS:
/Applicationsと~/Applicationsを確認します。 - Linux:
/usr/bin、/snap/bin、/opt/google、/opt/brave.com、/usr/lib/chromium、/usr/lib/chromium-browserの配下にある一般的な Chrome/Brave/Edge/Chromium の場所に加え、PLAYWRIGHT_BROWSERS_PATHまたは~/.cache/ms-playwrightの配下にある Playwright 管理の Chromium を確認します。 - Windows: 一般的なインストール場所を確認します。
制御 API(オプション)
スクリプト作成とデバッグのために、Gateway は小規模な local loopback 専用 HTTP 制御 API と、対応するopenclaw browser CLI(スナップショット、ref、拡張待機機能、
JSON 出力、デバッグワークフロー)を公開します。完全なリファレンスについては、
ブラウザー制御 API を参照してください。
トラブルシューティング
Linux 固有の問題(特に snap Chromium)については、 ブラウザーのトラブルシューティング を参照してください。 WSL2 Gateway と Windows Chrome の分離ホスト構成については、 WSL2 + Windows + リモート Chrome CDP のトラブルシューティング を参照してください。CDP 起動失敗とナビゲーションの SSRF ブロック
これらは異なる種類の障害であり、それぞれ異なるコードパスを示します。- CDP の起動または準備状態の失敗は、OpenClaw がブラウザー制御プレーンの正常性を確認できないことを意味します。
- ナビゲーションの SSRF ブロックは、ブラウザー制御プレーンは正常ですが、ページナビゲーションの対象がポリシーによって拒否されたことを意味します。
- CDP の起動または準備状態の失敗:
Chrome CDP websocket for profile "openclaw" is not reachable after startRemote CDP for profile "<name>" is not reachable at <cdpUrl>- local loopback の外部 CDP サービスが
attachOnly: trueなしで設定されている場合のPort <port> is in use for profile "<name>" but not by openclaw
- ナビゲーションの SSRF ブロック:
startとtabsは引き続き機能する一方で、open、navigate、スナップショット、またはタブを開くフローがブラウザー/ネットワークポリシーエラーで失敗する
startがnot reachable after startで失敗した場合は、まず CDP の準備状態をトラブルシューティングします。startが成功してもtabsが失敗する場合、制御プレーンは依然として正常ではありません。ページナビゲーションの問題ではなく、CDP の到達性の問題として扱います。startとtabsが成功しても、openまたはnavigateが失敗する場合、ブラウザー制御プレーンは稼働しており、障害はナビゲーションポリシーまたは対象ページにあります。start、tabs、openがすべて成功した場合、基本的なマネージドブラウザー制御パスは正常です。
browser.ssrfPolicyを設定していない場合でも、ブラウザー設定のデフォルトはフェイルクローズの SSRF ポリシーオブジェクトです。- local loopback の
openclawマネージドプロファイルでは、OpenClaw 自身のローカル制御プレーンに対して、CDP ヘルスチェックがブラウザーの SSRF 到達性適用を意図的にスキップします。 - ナビゲーション保護は別です。
startまたはtabsが成功しても、後続のopenまたはnavigateの対象が許可されることを意味しません。
- デフォルトではブラウザーの SSRF ポリシーを緩和しないでください。
- 広範なプライベートネットワークアクセスよりも、
hostnameAllowlistやallowedHostnamesなどの限定的なホスト例外を優先してください。 - プライベートネットワークへのブラウザーアクセスが必要で、レビュー済みの意図的に信頼された環境でのみ、
dangerouslyAllowPrivateNetwork: trueを使用してください。
エージェントツールと制御の仕組み
エージェントには、ブラウザー自動化用の 1 つのツール が提供されます:browser- doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
browser snapshotは、安定した UI ツリー(AI または ARIA)を返します。browser actは、スナップショットのrefID を使用して、クリック、入力、ドラッグ、選択を行います。browser screenshotは、ピクセル(ページ全体、要素、またはラベル付き参照)をキャプチャします。browser doctorは、Gateway、plugin、プロファイル、ブラウザー、タブの準備状態を確認します。browserには、以下を指定できます。profile:名前付きブラウザープロファイル(openclaw、chrome、またはリモート CDP)を選択します。target(sandbox|host|node):ブラウザーの実行場所を選択します。- サンドボックス化されたセッションでは、
target: "host"にagents.defaults.sandbox.browser.allowHostControl=trueが必要です。 targetを省略した場合、サンドボックス化されたセッションではデフォルトでsandbox、サンドボックス化されていないセッションではデフォルトでhostが使用されます。- ブラウザー対応 Node が接続されている場合、
target="host"またはtarget="node"を固定しない限り、ツールはその Node に自動的にルーティングされることがあります。