- エージェント専用の別ブラウザと考えてください。
openclawプロファイルが個人用ブラウザプロファイルに触れることはありません。 - エージェントは、この分離されたレーンでタブを開き、ページを読み取り、クリックし、入力します。
- 組み込みの
userプロファイルは、代わりに Chrome DevTools MCP 経由で、実際にサインイン済みの Chrome セッションに接続します。
得られるもの
- openclaw という名前の別ブラウザプロファイル(デフォルトではオレンジのアクセント)。
- 決定論的なタブ制御(一覧表示/開く/フォーカス/閉じる)。
- エージェント操作(クリック/入力/ドラッグ/選択)、スナップショット、スクリーンショット、PDF。
- Playwright ベースのプロファイルは、直接添付ナビゲーションを管理対象ダウンロードディレクトリに保存し、最終 URL ポリシー検証後に
{ url, suggestedFilename, path }メタデータを返します。 - Playwright ベースのエージェント操作は、その操作がすぐに 1 つ以上のダウンロードを開始した場合、同じ管理対象メタデータを含む
downloads配列を返します。 - ブラウザ Plugin が有効な場合に、スナップショット、安定タブ、古い参照、手動ブロッカー復旧ループをエージェントに教える、同梱の
browser-automationSkill。 - 任意の複数プロファイル対応(
openclaw、work、remote、…)。
クイックスタート
browser.enabled がオフであることを意味します。設定 と Plugin 制御 を参照してください。
openclaw browser が完全に存在しない場合、またはエージェントがブラウザツールを利用できないと言う場合は、ブラウザコマンドまたはツールが見つからない に進んでください。
Plugin 制御
デフォルトのbrowser ツールは同梱 Plugin です。同じ browser ツール名を登録する別の Plugin に置き換えるには、無効にします。
plugins.entries.browser.enabled と browser.enabled=true の両方が必要です。Plugin だけを無効にすると、openclaw browser CLI、browser.request gateway メソッド、エージェントツール、制御サービスが 1 つの単位として削除されます。置き換え用に browser.* 設定はそのまま残ります。
ブラウザ設定の変更では、Plugin がサービスを再登録できるように Gateway の再起動が必要です。
エージェントガイダンス
ツールプロファイルの注意:tools.profile: "coding" には web_search と web_fetch が含まれますが、完全な browser ツールは含まれません。エージェントまたは生成されたサブエージェントがブラウザ自動化を使えるようにするには、プロファイル段階で browser を追加します。
agents.list[].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.enabled=true や browser.profiles.<name> など、browser 配下の任意のキー)は、制限的な plugins.allow の下でも同梱ブラウザ Plugin を有効化し、同梱チャネル設定の動作と一致します。plugins.entries.browser.enabled=true と tools.alsoAllow: ["browser"] は、それだけでは許可リストのメンバーシップの代わりにはなりません。plugins.allow を完全に削除してもデフォルトが復元されます。
プロファイル: openclaw、user、chrome
openclaw: 管理対象の分離ブラウザ(拡張機能不要)。user: 実際にサインイン済みの Chrome セッション向けの組み込み Chrome DevTools MCP 接続プロファイル。OpenClaw が初めて接続するとき、Chrome はブロッキングの「リモート デバッグを許可しますか?」プロンプトを表示するため、誰かがコンピュータの前にいる必要があります。chrome: 実際にサインイン済みの Chrome セッション向けの組み込み Chrome 拡張機能 プロファイル。リモートデバッグポートではなく OpenClaw ブラウザ拡張機能を通じてタブを操作するため、「リモート デバッグを許可しますか?」プロンプトはなく、机に誰もいなくてもスマートフォンから動作します。
- デフォルト: 分離された
openclawブラウザを使用します。 - 既存のログイン済みセッションが重要で、ユーザーがコンピュータから離れている場合(Telegram、WhatsApp など)は、
profile="chrome"(拡張機能)を優先します。 - 既存のログイン済みセッションが重要で、ユーザーが接続プロンプトを承認するためにコンピュータの前にいる場合は、
profile="user"(Chrome MCP)を優先します。 - 特定のブラウザモードを使いたい場合、
profileが明示的な上書きです。
browser.defaultProfile: "openclaw" を設定します。
設定
ブラウザ設定は~/.openclaw/openclaw.json にあります。
browser.snapshotDefaults.mode: "efficient" は、呼び出し元が明示的な snapshotFormat または mode を渡さない場合のデフォルトの snapshot 抽出モードを変更します。呼び出しごとのスナップショットオプションについては、ブラウザ制御 API を参照してください。
スクリーンショットビジョン(テキストのみモデル対応)
メインモデルがテキストのみ(ビジョン/マルチモーダル非対応)の場合、ブラウザスクリーンショットはモデルが読めない画像ブロックを返します。ブラウザスクリーンショットは既存の画像理解設定を再利用するため、メディア理解用に設定された画像モデルが、ブラウザ固有のモデル設定なしでスクリーンショットをテキストとして説明できます。- エージェントが
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ポートをデフォルトにします。 remoteCdpTimeoutMsは、リモートおよびattachOnlyのCDP HTTP到達性 チェックとタブを開くHTTPリクエストに適用されます。remoteCdpHandshakeTimeoutMsは、 それらのCDP WebSocketハンドシェイクに適用されます。永続リモートPlaywrightタブ列挙は、 2つのうち大きい方を操作期限として使用します。localLaunchTimeoutMsは、ローカルで起動された管理対象Chrome プロセスがCDP HTTPエンドポイントを公開するための予算です。localCdpReadyTimeoutMsは、 プロセス検出後のCDP WebSocket準備完了のための後続予算です。 Raspberry Pi、低スペックVPS、またはChromiumの起動が遅い古いハードウェアではこれらを引き上げてください。値は120000ms までの正の整数である必要があります。無効な config値は拒否されます。- 管理対象Chromeの起動/準備完了に繰り返し失敗すると、プロファイルごとに サーキットブレーカーが作動します。連続して何度か失敗した後、OpenClaw はすべてのブラウザツール呼び出しでChromiumを生成する代わりに、新しい起動 試行を短時間一時停止します。起動問題を修正するか、ブラウザが不要なら無効にするか、修復後に Gateway を再起動してください。
actionTimeoutMsは、呼び出し元がtimeoutMsを渡さない場合のブラウザactリクエストのデフォルト予算です。クライアントトランスポートは小さな猶予ウィンドウを追加するため、長い待機がHTTP境界でタイムアウトせずに完了できます。tabCleanupは、プライマリエージェントのブラウザセッションが開いたタブに対するベストエフォートのクリーンアップです。サブエージェント、Cron、ACPのライフサイクルクリーンアップは、セッション終了時に明示的に追跡されたタブを引き続き閉じます。プライマリセッションではアクティブなタブを再利用可能な状態に保ち、その後、バックグラウンドでアイドル状態または過剰な追跡対象タブを閉じます。
SSRFポリシー
SSRFポリシー
- ブラウザナビゲーションとタブを開く操作は、ナビゲーション前にSSRFガードされ、その後、最終的な
http(s)URLでベストエフォートにより再チェックされます。 - 厳格SSRFモードでは、リモートCDPエンドポイント検出と
/json/versionプローブ(cdpUrl)もチェックされます。 - Gateway/プロバイダーの
HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY環境変数は、OpenClaw管理のブラウザを自動的にプロキシしません。管理対象Chromeはデフォルトで直接起動されるため、プロバイダーのプロキシ設定によってブラウザのSSRFチェックが弱まることはありません。 - 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を上書きするため、ローカルで起動されるあるプロファイルをヘッドレスのままにし、別のプロファイルを表示状態のままにできます。POST /start?headless=trueとopenclaw browser start --headlessは、browser.headlessまたはプロファイルconfigを書き換えずに、ローカル管理対象プロファイルの 1回限りのヘッドレス起動をリクエストします。既存セッション、アタッチ専用、 リモートCDPプロファイルは、OpenClaw がそれらのブラウザプロセスを起動しないため、 この上書きを拒否します。DISPLAYまたはWAYLAND_DISPLAYがないLinuxホストでは、環境またはプロファイル/グローバル configのどちらも明示的に表示モードを選択していない場合、ローカル管理対象プロファイルは 自動的にヘッドレスをデフォルトにします。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回の起動については引き続き優先されます。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 はループバック制御サービスを開始し、ローカルブラウザを起動できます。
- リモート制御(ノードホスト): ブラウザがあるマシンでノードホストを実行します。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は、アクティブな 制御セッションを閉じ、Playwright/CDPエミュレーション上書き(ビューポート、 カラースキーム、ロケール、タイムゾーン、オフラインモード、および類似の状態)を解放します。ただし、 OpenClaw によってブラウザプロセスが起動されたわけではありません
- クエリトークン(例:
https://provider.example?token=<token>) - HTTP Basic認証(例:
https://user:pass@provider.example)
/json/* エンドポイントの呼び出し時とCDP WebSocketへの接続時に
認証を保持します。トークンをconfigファイルにコミットする代わりに、
環境変数またはシークレットマネージャーを使用することを推奨します。
Nodeブラウザプロキシ(ゼロconfigのデフォルト)
ブラウザがあるマシンで ノードホスト を実行している場合、OpenClaw は 追加のブラウザconfigなしで、ブラウザツール呼び出しをそのノードへ 自動ルーティングできます。これはリモートゲートウェイのデフォルトパスです。 メモ:- ノードホストは、プロキシコマンド 経由でローカルブラウザ制御サーバーを公開します。
- プロファイルはノード自身の
browser.profilesconfig(ローカルと同じ)から取得されます。 - プロキシコマンドは、
allowProfilesに関係なく、永続的なプロファイル変更(create-profile、delete-profile、reset-profile)を一切許可しません。これらの変更はノード上で直接行ってください。 nodeHost.browserProxy.allowProfilesは任意です。レガシー/デフォルト動作、つまり設定済みのすべてのプロファイルをプロキシ経由で到達可能にするには、空のままにします。nodeHost.browserProxy.allowProfilesを設定した場合、OpenClaw はそれを、プロキシが対象にできるプロファイル名を制限する最小権限境界として扱います。- 不要な場合は無効にします。
- ノード側:
nodeHost.browserProxy.enabled=false - Gateway側:
gateway.nodes.browser.mode="off"(単一の接続済みブラウザノードを選ぶ"auto"、または明示的なノードパラメーターを必須にする"manual"も受け付けます)
- ノード側:
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 ネットワークアドレスなど、同じ public-to-OpenClaw WebSocket ベースに設定してください。/json/version が、OpenClaw から到達できないアドレスを指す webSocketDebuggerUrl を返す場合、CDP HTTP は正常に見えても WebSocket アタッチは失敗することがあります。
loopback Browserless プロファイルでは、attachOnly を未設定のままにしないでください。attachOnly がない場合、OpenClaw は 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 エンドポイント -
ws://host[:port]/devtools/<kind>/<id>、または/devtools/browser|page|worker|shared_worker|service_worker/<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 解決、ステルスモード、住宅プロキシを備えたヘッドレスブラウザ実行用のクラウドプラットフォームです。- サインアップし、概要ダッシュボードからAPI キーをコピーします。
<BROWSERBASE_API_KEY>を実際の Browserbase API キーに置き換えます。- Browserbase は WebSocket 接続時にブラウザセッションを自動作成するため、手動のセッション作成手順は不要です。
- 現在の無料枠の制限と有料プランについては、料金を参照してください。
- 完全な API リファレンス、SDK ガイド、統合例については、Browserbase ドキュメントを参照してください。
Notte
Notte は、組み込みのステルス、住宅プロキシ、CDP ネイティブの WebSocket Gateway を備えたヘッドレスブラウザ実行用のクラウドプラットフォームです。- サインアップし、コンソール設定ページからAPI キーをコピーします。
<NOTTE_API_KEY>を実際の Notte API キーに置き換えます。- Notte は WebSocket 接続時にブラウザセッションを自動作成するため、手動のセッション作成手順は不要です。WebSocket が切断されると、セッションは破棄されます。
- 現在の無料枠の制限と有料プランについては、料金を参照してください。
- 完全な API リファレンス、SDK ガイド、統合例については、Notte ドキュメントを参照してください。
セキュリティ
重要な考え方:- ブラウザ制御は loopback 専用です。アクセスは Gateway の認証またはノードペアリングを通じて流れます。
- スタンドアロンの loopback ブラウザ HTTP API は、共有シークレット認証のみを使用します。
Gateway トークンの bearer 認証、
x-openclaw-password、または設定済み Gateway パスワードによる HTTP Basic 認証です。 - Tailscale Serve の ID ヘッダーと
gateway.auth.mode: "trusted-proxy"は、このスタンドアロンの loopback ブラウザ API を認証しません。 - ブラウザ制御が有効で、共有シークレット認証が設定されていない場合、OpenClaw は起動時にブラウザ制御用の認証情報を自動生成して永続化します。
gateway.auth.modeがnoneの場合はトークン、trusted-proxyの場合はパスワードです(プロセス外の loopback クライアントが解決できるようにgateway.auth.password経由で永続化されます)。そのモードに明示的な文字列認証情報がすでに設定されている場合、またはgateway.auth.modeがpasswordの場合、自動生成はスキップされます。 - 生成されたものではなく、自分で管理する安定したシークレットを使いたい場合は、
gateway.auth.token、gateway.auth.password、OPENCLAW_GATEWAY_TOKEN、またはOPENCLAW_GATEWAY_PASSWORDを明示的に設定してください。
- 可能な場合は、暗号化されたエンドポイント(HTTPS または WSS)と短命のトークンを優先してください。
- 長命のトークンを設定ファイルに直接埋め込むことは避けてください。
- Gateway とすべてのノードホストはプライベートネットワーク(Tailscale)上に保ち、公開露出を避けてください。
- リモート CDP URL/トークンはシークレットとして扱い、env vars またはシークレットマネージャーを優先してください。
プロファイル(複数ブラウザ)
OpenClaw は複数の名前付きプロファイル(ルーティング設定)をサポートします。プロファイルには次の種類があります。- openclaw-managed: 独自のユーザーデータディレクトリ + CDP ポートを持つ専用の Chromium ベースのブラウザインスタンス
- remote: 明示的な CDP URL(別の場所で実行されている Chromium ベースのブラウザ)
- existing session: Chrome DevTools MCP 自動接続を介した既存の Chrome プロファイル
openclawプロファイルは、存在しない場合に自動作成されます。userプロファイルは、Chrome MCP 既存セッションアタッチ用に組み込まれています。- 既存セッションプロファイルは、
user以外では opt-in です。--driver existing-sessionで作成してください。 - ローカル CDP ポートは、デフォルトで 18800-18899 から割り当てられます。
- プロファイルを削除すると、そのローカルデータディレクトリは Trash に移動されます。
?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 のホームディレクトリに展開されます。
- リモートデバッグ用のそのブラウザの inspect ページを開きます。
- リモートデバッグを有効にします。
- ブラウザを起動したままにし、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が選択されたライブタブから refs を返す
- 対象の Chromium ベースのブラウザがバージョン
144+である - そのブラウザの inspect ページでリモートデバッグが有効になっている
- ブラウザがアタッチ同意プロンプトを表示し、それを承認した
- Chrome が明示的な
--remote-debugging-portで起動されている場合は、Chrome MCP 自動接続に依存するのではなく、browser.profiles.<name>.cdpUrlをその DevTools エンドポイントに設定する openclaw doctorは古い拡張ベースのブラウザ設定を移行し、デフォルトの自動接続プロファイル用に Chrome がローカルにインストールされていることを確認しますが、ブラウザ側のリモートデバッグを有効にすることはできません
- ユーザーのログイン済みブラウザ状態が必要な場合は、
profile="user"を使用します。 - カスタム既存セッションプロファイルを使用する場合は、その明示的なプロファイル名を渡します。
- このモードは、ユーザーがコンピューターの前にいてアタッチプロンプトを承認できる場合にのみ選択してください。
- Gateway またはノードホストは
npx chrome-devtools-mcp@latest --autoConnectを起動できます。
- このパスは、サインイン済みブラウザセッション内で動作できるため、分離された
openclawプロファイルよりリスクが高くなります。 - OpenClaw はこのドライバー用にブラウザを起動しません。アタッチのみを行います。
- OpenClaw はここで公式 Chrome DevTools MCP
--autoConnectフローを使用します。userDataDirが設定されている場合は、そのユーザーデータディレクトリを対象にするために渡されます。 - 既存セッションは、選択されたホスト上、または接続済みブラウザノード経由でアタッチできます。Chrome が別の場所にあり、ブラウザノードが接続されていない場合は、代わりにリモート CDP またはノードホストを使用してください。
カスタム Chrome MCP 起動
デフォルトのnpx chrome-devtools-mcp@latest フローが目的に合わない場合(オフラインホスト、固定バージョン、ベンダー提供バイナリ)、プロファイルごとに起動される Chrome DevTools MCP サーバーを上書きします。
| フィールド | 内容 |
|---|---|
mcpCommand | npx の代わりに起動する実行ファイルです。そのまま解決され、絶対パスも尊重されます。 |
mcpArgs | mcpCommand にそのまま渡される引数配列です。デフォルトの chrome-devtools-mcp@latest --autoConnect 引数を置き換えます。 |
cdpUrl が設定されている場合、OpenClaw は --autoConnect をスキップし、エンドポイントを Chrome MCP に自動的に転送します。
http(s)://...→--browserUrl <url>(DevTools HTTP 検出エンドポイント)。ws(s)://...→--wsEndpoint <url>(直接 CDP WebSocket)。
userDataDir は組み合わせられません。cdpUrl が設定されている場合、Chrome MCP 起動では userDataDir は無視されます。これは Chrome MCP がプロファイルディレクトリを開くのではなく、エンドポイントの背後で実行中のブラウザにアタッチするためです。
既存セッション機能の制限
既存セッション機能の制限
管理対象の
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、evaluateは呼び出しごとのtimeoutMsオーバーライドをサポートしていません。selectは単一の値を受け付けます。batchはサポートされていません。アクションは個別に送信してください。 - 待機 / アップロード / ダイアログ -
wait --urlは完全一致、部分文字列、glob パターンをサポートします (managed と同じです)。wait --load networkidleは既存セッションプロファイルではサポートされていません (managed および raw/remote CDP プロファイルでは動作します)。アップロードフックにはrefまたはinputRefが必要で、一度に 1 ファイルのみ、CSSelementは使用できません。ダイアログフックはタイムアウトのオーバーライドやdialogIdをサポートしていません。 - ダイアログの可視性 - Managed ブラウザーのアクションレスポンスには、アクションがモーダルダイアログを開いたときに
blockedByDialogとbrowserState.dialogs.pendingが含まれます。スナップショットにも保留中のダイアログ状態が含まれます。ダイアログが保留中の間にbrowser dialog --accept/--dismiss --dialog-id <id>で応答してください。OpenClaw の外部で処理されたダイアログはbrowserState.dialogs.recentの下に表示されます。 - Managed 専用機能 - PDF エクスポート、ダウンロードインターセプト、
responsebodyには引き続き managed ブラウザーパスが必要です。
分離保証
- 専用ユーザーデータディレクトリ: 個人用ブラウザープロファイルには一切触れません。
- 専用ポート: 開発ワークフローとの衝突を防ぐため
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: 一般的なインストール場所を確認します。
Control API (任意)
スクリプト作成とデバッグのために、Gateway は小さな ループバック専用 HTTP コントロール API と、対応するopenclaw browser CLI (スナップショット、refs、wait
パワーアップ、JSON 出力、デバッグワークフロー) を公開します。完全なリファレンスは
ブラウザーコントロール API を参照してください。
トラブルシューティング
Linux 固有の問題 (特に snap Chromium) については、 ブラウザーのトラブルシューティング を参照してください。 WSL2 Gateway + Windows Chrome の split-host セットアップについては、 WSL2 + Windows + remote 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>- 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がすべて成功する場合、基本的な managed ブラウザーコントロールパスは正常です。
- ブラウザー設定は、
browser.ssrfPolicyを設定していない場合でも、デフォルトで fail-closed の SSRF ポリシーオブジェクトになります。 - local loopback の
openclawmanaged プロファイルでは、CDP ヘルスチェックは OpenClaw 自身のローカルコントロールプレーンに対するブラウザー 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 を使用して click/type/drag/select を行います。browser screenshotはピクセルをキャプチャします (フルページ、要素、またはラベル付き refs)。browser doctorは Gateway、Plugin、プロファイル、ブラウザー、タブの準備状況を確認します。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"で固定しない限り、ツールは自動ルーティングすることがあります。