ブラウザー（OpenClaw管理）

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​

得られるもの

• openclaw という名前の別ブラウザープロファイル（既定ではオレンジのアクセント）。
• 決定的なタブ制御（一覧表示/開く/フォーカス/閉じる）。
• エージェント操作（クリック/入力/ドラッグ/選択）、スナップショット、スクリーンショット、PDF。
• ブラウザー Plugin が有効なときに、スナップショット、 安定タブ、古い参照、手動ブロッカーの復旧ループをエージェントに教える、同梱の browser-automation skill。
• 任意のマルチプロファイル対応（openclaw、work、remote、…）。

​

クイックスタート

openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw doctor --deep
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

​

Plugin 制御

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

​

エージェントのガイダンス

{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

• browser ツールの説明には、常時有効なコンパクトな契約が含まれます。適切なプロファイルを選ぶ、 参照を同じタブに保つ、タブのターゲット指定に tabId/ラベルを使う、 複数ステップの作業ではブラウザー skill を読み込む、という内容です。
• 同梱の browser-automation skill には、より長い運用ループが含まれます。 まずステータス/タブを確認する、タスクタブにラベルを付ける、操作前にスナップショットを取る、UI 変更後に再スナップショットを取る、 古い参照は一度復旧を試みる、ログイン/2FA/captcha または カメラ/マイクのブロッカーは推測せず手動操作として報告する、という内容です。

​

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

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

​

プロファイル: openclaw と user

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

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

​

設定

{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms)
    localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms)
    actionTimeoutMs: 60000, // default browser act timeout (ms)
    tabCleanup: {
      enabled: true, // default: true
      idleMinutes: 120, // set 0 to disable idle cleanup
      maxTabsPerSession: 8, // set 0 to disable the per-session cap
      sweepMinutes: 5,
    },
    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",
        headless: true,
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      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" },
    },
  },
}

​

Brave または別の Chromium ベースのブラウザーを使用する

openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
  },
}

{
  browser: {
    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
  },
}

{
  browser: {
    executablePath: "/usr/bin/brave-browser",
  },
}

​

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

• ローカル制御 (デフォルト): Gateway は loopback 制御サービスを開始し、ローカルブラウザーを起動できます。
• リモート制御 (Node ホスト): ブラウザーがあるマシンで Node ホストを実行します。Gateway はブラウザー操作をそこへプロキシします。
• リモート CDP: リモートの Chromium ベースブラウザーにアタッチするには、 browser.profiles.<name>.cdpUrl (または browser.cdpUrl) を設定します。この場合、OpenClaw はローカルブラウザーを起動しません。
• loopback 上の外部管理 CDP サービス (たとえば Docker で 127.0.0.1 に公開された Browserless) では、 attachOnly: true も設定します。attachOnly のない loopback 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)

​

Node ブラウザープロキシ (設定不要のデフォルト)

• Node ホストは プロキシコマンド 経由でローカルブラウザー制御サーバーを公開します。
• プロファイルは Node 自身の browser.profiles 設定 (ローカルと同じ) から取得されます。
• nodeHost.browserProxy.allowProfiles は任意です。従来/デフォルト動作にするには空のままにします。設定済みのすべてのプロファイルは、プロファイルの作成/削除ルートを含め、プロキシ経由で到達可能なままになります。
• nodeHost.browserProxy.allowProfiles を設定すると、OpenClaw はそれを最小権限の境界として扱います。許可リストにあるプロファイルだけを対象にでき、永続プロファイルの作成/削除ルートはプロキシ面でブロックされます。
• 不要な場合は無効にします:
  • Node 側: 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 を検出させることができます。

​

同じホスト上の Browserless Docker

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    profiles: {
      browserless: {
        cdpUrl: "ws://127.0.0.1:3000",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}

​

直接 WebSocket CDP プロバイダー

• 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 が返された場合はそれを使用します。そうでない場合、OpenClaw は 素のルートで直接 WebSocket ハンドシェイクにフォールバックします。広告された WebSocket エンドポイントが CDP ハンドシェイクを拒否する一方で、設定された素のルートが それを受け入れる場合、OpenClaw はそのルートにもフォールバックします。これにより、ローカル Chrome を指す素の ws:// でも接続できます。Chrome は /json/version から得られるターゲットごとの特定パスでのみ WebSocket アップグレードを受け入れますが、ホスト型プロバイダーは、検出 エンドポイントが Playwright CDP に適さない短命 URL を広告する場合でも、 ルート WebSocket エンドポイントを引き続き使用できます。

​

Browserbase

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

• サインアップ し、概要ダッシュボード から API Key をコピーします。
• <BROWSERBASE_API_KEY> を実際の Browserbase API キーに置き換えます。
• Browserbase は WebSocket 接続時にブラウザーセッションを自動作成するため、 手動のセッション作成手順は不要です。
• 無料枠では、同時セッション 1 件と月 1 ブラウザー時間が許可されます。 有料プランの制限については 価格 を参照してください。
• 完全な API リファレンス、SDK ガイド、統合例については Browserbase ドキュメント を参照してください。

​

セキュリティ

• ブラウザー制御は local loopback のみです。アクセスは Gateway の認証またはノードのペアリングを通ります。
• スタンドアロンの 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 トークンを生成します。再起動後もクライアントが安定したシークレットを必要とする場合は、 gateway.auth.token、gateway.auth.password、OPENCLAW_GATEWAY_TOKEN、または OPENCLAW_GATEWAY_PASSWORD を明示的に設定してください。
• gateway.auth.mode がすでに password、none、または trusted-proxy の場合、OpenClaw はそのトークンを自動生成しません。
• Gateway とすべてのノードホストはプライベートネットワーク（Tailscale）上に置き、公開は避けてください。
• リモート CDP URL/トークンはシークレットとして扱い、環境変数またはシークレットマネージャーを優先してください。

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

​

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

• openclaw-managed: 専用のユーザーデータディレクトリ + CDP ポートを持つ、専用の Chromium ベースのブラウザーインスタンス
• remote: 明示的な CDP URL（別の場所で実行されている Chromium ベースのブラウザー）
• existing session: 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. リモートデバッグ用にそのブラウザーの検査ページを開きます。
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+ である
• そのブラウザーの検査ページでリモートデバッグが有効になっている
• ブラウザーが接続同意プロンプトを表示し、それを承認した
• openclaw doctor は古い拡張機能ベースのブラウザー設定を移行し、デフォルトの自動接続プロファイル用に Chrome がローカルにインストールされているか確認しますが、 ブラウザー側のリモートデバッグを有効にすることはできません

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

• この経路は、ログイン済みブラウザーセッション内で動作できるため、隔離された openclaw プロファイルよりもリスクが高くなります。
• OpenClaw はこのドライバー用にブラウザーを起動しません。接続するだけです。
• OpenClaw はここで公式の Chrome DevTools MCP --autoConnect フローを使用します。 userDataDir が設定されている場合は、そのユーザーデータディレクトリを対象にするためにそのまま渡されます。
• 既存セッションは、選択したホスト上または接続済みのブラウザーノード経由で接続できます。Chrome が別の場所にあり、ブラウザーノードが接続されていない場合は、 代わりにリモート CDP またはノードホストを使用してください。

​

カスタム Chrome MCP 起動

• http(s)://... → --browserUrl <url>（DevTools HTTP 探索エンドポイント）。
• ws(s)://... → --wsEndpoint <url>（直接 CDP WebSocket）。

​

隔離の保証

• 専用ユーザーデータディレクトリ: 個人用ブラウザープロファイルには一切触れません。
• 専用ポート: 開発ワークフローとの衝突を防ぐため、9222 を避けます。
• 決定論的なタブ制御: tabs は最初に suggestedTargetId を返し、その後に t1 などの安定した tabId ハンドル、省略可能なラベル、raw targetId を返します。 エージェントは suggestedTargetId を再利用してください。raw ID は デバッグと互換性のために引き続き利用できます。

​

ブラウザー選択

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

• 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（任意）

​

トラブルシューティング

​

CDP 起動失敗とナビゲーション SSRF ブロック

• CDP 起動または準備完了の失敗 は、OpenClaw がブラウザー制御プレーンの健全性を確認できないことを意味します。
• ナビゲーション SSRF ブロック は、ブラウザー制御プレーンは健全だが、ページナビゲーションの対象がポリシーにより拒否されたことを意味します。

• CDP 起動または準備完了の失敗:
  • Chrome CDP websocket for profile "openclaw" is not reachable after start
  • Remote 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 ブロック:
  • open、navigate、スナップショット、またはタブを開くフローが、start と tabs は引き続き動作する一方で、ブラウザー/ネットワークポリシーエラーにより失敗する

openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com

• start が not reachable after start で失敗した場合は、まず CDP の準備完了をトラブルシューティングしてください。
• start は成功するが tabs が失敗する場合、制御プレーンはまだ不健全です。これはページナビゲーションの問題ではなく、CDP 到達性の問題として扱ってください。
• start と tabs は成功するが open または navigate が失敗する場合、ブラウザー制御プレーンは起動しており、失敗はナビゲーションポリシーまたは対象ページにあります。
• start、tabs、open がすべて成功する場合、基本的な管理対象ブラウザー制御経路は健全です。

• browser.ssrfPolicy を設定していない場合でも、ブラウザー設定はデフォルトでフェイルクローズの SSRF ポリシーオブジェクトになります。
• ローカルの local loopback openclaw 管理対象プロファイルでは、CDP ヘルスチェックは OpenClaw 自身のローカル制御プレーンに対するブラウザー SSRF 到達性強制を意図的にスキップします。
• ナビゲーション保護は別です。start または tabs の結果が成功しても、その後の open または navigate の対象が許可されることを意味しません。

• 既定ではブラウザの SSRF ポリシーを緩和しないでください。
• 広範なプライベートネットワークアクセスではなく、hostnameAllowlist や allowedHostnames のような限定的なホスト例外を優先してください。
• dangerouslyAllowPrivateNetwork: true は、プライベートネットワークのブラウザアクセスが必要でレビュー済みの、意図的に信頼された環境でのみ使用してください。

​

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

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

• browser snapshot は安定した UI ツリー（AI または ARIA）を返します。
• browser act はスナップショットの ref ID を使ってクリック/入力/ドラッグ/選択します。
• browser screenshot はピクセルをキャプチャします（ページ全体、要素、またはラベル付き refs）。
• 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" に固定しない限り、ツールはそこへ自動ルーティングすることがあります。

​

関連

• ツール概要 - 利用可能なすべてのエージェントツール
• サンドボックス化 - サンドボックス化された環境でのブラウザ制御
• セキュリティ - ブラウザ制御のリスクと強化