OpenClaw で分離ブラウザを構築：安全な自動化環境をセットアップ

OpenClawでは、エージェントが制御する専用の Chrome/Brave/Edge/Chromium プロフィールを実行できます。これは個人のブラウザからは隔離されており、Gateway 内のローカル制御サービス（ループバックのみ）を通じて管理されます。

初心者向けの解説：

エージェント専用の独立したブラウザだと考えてください。
openclaw プロフィールは、あなたの個人のブラウザプロフィールには一切触れません。
エージェントは安全な環境で、タブを開く、ページを読み取る、クリックする、入力するといった操作ができます。
標準の user プロフィールは、Chrome MCP を通じて、あなたが実際にサインインしている Chrome セッションに接続します。

得られるもの

openclaw という名前の独立したブラウザプロフィール（デフォルトではオレンジ色のアクセント）。
確実なタブ制御（一覧取得、開く、フォーカス、閉じる）。
エージェントによるアクション（クリック、入力、ドラッグ、選択）、スナップショット、スクリーンショット、PDF作成。
オプションでのマルチプロフィール対応（openclaw, work, remote など）。

このブラウザは、普段使いのためのものではありません。エージェントによる自動化や検証のための、安全で隔離された領域です。

クイックスタート

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

もし「Browser disabled」と表示される場合は、設定で有効化し（下記参照）、Gateway を再起動してください。

openclaw browser コマンドが全く見当たらない場合や、エージェントがブラウザツールを利用できないと言っている場合は、Missing browser command or tool のセクションを確認してください。

プラグインによる制御

デフォルトの browser ツールは、最初から有効化された状態で同梱されているプラグインになりました。つまり、OpenClaw のプラグインシステム全体を削除することなく、ブラウザ機能だけを無効化したり、別のものに置き換えたりできます。

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

同じ browser というツール名を提供する別のプラグインをインストールする前に、同梱されているプラグインを無効化してください。デフォルトのブラウザ機能を利用するには、以下の両方が必要です。

plugins.entries.browser.enabled が無効化されていないこと
browser.enabled=true であること

プラグインだけをオフにすると、同梱のブラウザ CLI（openclaw browser）、Gateway のメソッド（browser.request）、エージェントツール、そしてデフォルトのブラウザ制御サービスがすべてまとめて削除されます。browser.* の設定自体は保持されるため、別のプラグインで再利用することも可能です。

現在、同梱のブラウザプラグインがブラウザの実行環境の実装も受け持っています。コア側には、共有の Plugin SDK ヘルパーと、古い内部インポートパスのための互換用エクスポートのみが残されています。実際には、ブラウザプラグインのパッケージを削除または置換すると、コア側に実行環境が残ることなく、ブラウザ機能セットが削除されます。

ブラウザの設定を変更した後は、同梱プラグインが新しい設定でブラウザサービスを再登録できるよう、Gateway の再起動が必要です。

ブラウザコマンドやツールが見つからない場合

アップグレード後に openclaw browser が突然不明なコマンドになったり、エージェントがブラウザツールが見つからないと報告したりする場合、最も一般的な原因は plugins.allow リストに browser が含まれていないことです。

問題のある設定例：

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

プラグインの許可リスト（allowlist）に browser を追加することで解決します。

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

重要な注意点：

plugins.allow が設定されている場合、browser.enabled=true だけでは不十分です。
plugins.entries.browser.enabled=true も、plugins.allow が設定されている場合はそれだけでは不十分です。
tools.alsoAllow: ["browser"] は、同梱のブラウザプラグインをロードしません。これはプラグインがロードされた後のツールポリシーを調整するだけのものです。
制限の厳しいプラグイン許可リストが必要ない場合は、plugins.allow を削除することでも、デフォルトのブラウザの挙動を復元できます。

よくある症状：

openclaw browser が不明なコマンドになる。
browser.request が見つからない。
エージェントが、ブラウザツールが利用不可または欠落していると報告する。

プロファイル: `openclaw` vs `user`

openclaw: 管理された、隔離されたブラウザです（拡張機能は不要です）。
user: あなたが実際にサインインして使用している Chrome セッションのための、組み込みの Chrome MCP アタッチ用プロファイルです。

エージェントのブラウザツール呼び出しについては、以下を参考にしてください：

デフォルト：隔離された openclaw ブラウザを使用します。
既存のログインセッションが必要な場合や、ユーザーがコンピュータの前にいてアタッチのプロンプトをクリック・承認できる場合は、profile="user" を優先してください。
profile は、特定のブラウザモードを指定したい場合の明示的なオーバーライド設定です。

デフォルトで管理モードを使用したい場合は、browser.defaultProfile: "openclaw" を設定してください。

設定

ブラウザの設定は ~/.openclaw/openclaw.json に保存されます。

{
  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)
    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" },
      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" },
    },
  },
}

注意点：

ブラウザ制御サービスは、gateway.port（デフォルトは 18791、つまり Gateway + 2）から派生したポートのループバックにバインドされます。
Gateway ポート（gateway.port または OPENCLAW_GATEWAY_PORT）をオーバーライドすると、派生するブラウザポートも同じ「ファミリー」内に留まるようにシフトします。
cdpUrl が未設定の場合、デフォルトで管理対象のローカル CDP ポートが使用されます。
remoteCdpTimeoutMs は、リモート（ループバック以外）の CDP 到達可能性チェックに適用されます。
remoteCdpHandshakeTimeoutMs は、リモートの CDP WebSocket ハンドシェイクの到達可能性チェックに適用されます。
ブラウザのナビゲーションやタブを開く動作は、ナビゲーション前に SSRF ガードによって保護され、ナビゲーション後の最終的な http(s) URL でもベストエフォートで再チェックされます。
厳格な SSRF モードでは、リモート CDP エンドポイントの検出やプローブ（cdpUrl、/json/version のルックアップを含む）もチェックされます。
browser.ssrfPolicy.dangerouslyAllowPrivateNetwork はデフォルトで無効です。プライベートネットワークへのブラウザアクセスを意図的に信頼する場合のみ、true に設定してください。
browser.ssrfPolicy.allowPrivateNetwork は、互換性のためのレガシーなエイリアスとして引き続きサポートされます。
attachOnly: true は、「ローカルブラウザを起動せず、すでに実行されている場合にのみアタッチする」ことを意味します。
color とプロファイルごとの color は、どのプロファイルがアクティブであるかを確認できるようにブラウザ UI を着色します。
デフォルトのプロファイルは openclaw（OpenClaw が管理するスタンドアロンブラウザ）です。サインイン済みのユーザーブラウザを使用するには、defaultProfile: "user" を設定してください。
自動検出の順序：Chromium ベースであればシステムデフォルトのブラウザ、そうでなければ Chrome → Brave → Edge → Chromium → Chrome Canary の順です。
ローカルの openclaw プロファイルは cdpPort/cdpUrl を自動的に割り当てます。これらはリモート CDP の場合にのみ設定してください。
driver: "existing-session" は、生の CDP ではなく Chrome DevTools MCP を使用します。このドライバーに対して cdpUrl を設定しないでください。
existing-session プロファイルを Brave や Edge などのデフォルト以外の Chromium ユーザープロファイルにアタッチさせる場合は、browser.profiles.<name>.userDataDir を設定してください。

Brave（またはその他の Chromium ベースのブラウザ）の使用

システムデフォルトのブラウザが Chromium ベース（Chrome/Brave/Edge など）である場合、OpenClaw はそれを自動的に使用します。自動検出をオーバーライドするには、browser.executablePath を設定してください。

CLI の例：

openclaw config set browser.executablePath "/usr/bin/google-chrome"

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

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

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

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

ローカル制御（デフォルト）： Gateway がループバック制御サービスを開始し、ローカルブラウザを起動できます。
リモート制御（node host）： ブラウザがインストールされているマシンで node host を実行します。Gateway はブラウザのアクションをそのホストにプロキシします。
リモート CDP： リモートの Chromium ベースのブラウザにアタッチするには、browser.profiles.<name>.cdpUrl（または browser.cdpUrl）を設定します。この場合、OpenClaw はローカルブラウザを起動しません。

停止時の動作はプロファイルモードによって異なります：

ローカル管理プロファイル：openclaw browser stop は、OpenClaw が起動したブラウザプロセスを停止します。
アタッチ専用およびリモート CDP プロファイル：openclaw browser stop は、アクティブな制御セッションを終了し、Playwright/CDP のエミュレーション設定（ビューポート、配色、ロケール、タイムゾーン、オフラインモードなどの状態）を解除します。OpenClaw によってブラウザプロセスが起動されていない場合でも、これらの設定は解除されます。

リモート CDP の URL には認証情報を含めることができます：

クエリトークン（例：https://provider.example?token=<token>）
HTTP 基本認証（例：https://user:pass@provider.example）

OpenClaw は、/json/* エンドポイントへの呼び出しや CDP WebSocket への接続時に認証情報を保持します。トークンについては、設定ファイルに直接記述するのではなく、環境変数やシークレットマネージャーの使用を推奨します。

Node browser proxy (ゼロ構成のデフォルト設定)

ブラウザがインストールされているマシンで node host を実行している場合、OpenClaw は特別な設定なしでブラウザツールの呼び出しをそのノードに自動ルーティングできます。これはリモートの Gateway におけるデフォルトの構成です。

注意点：

node host は、proxy command を介してローカルのブラウザ制御サーバーを公開します。
プロフィールは、ノード自身の browser.profiles 設定（ローカルと同じ）から取得されます。
nodeHost.browserProxy.allowProfiles は任意の設定です。空のままにすると、従来通りすべてのプロフィールにアクセスでき、プロフィールの作成・削除ルートも利用可能です。
nodeHost.browserProxy.allowProfiles を設定した場合、OpenClaw はそれを最小権限の境界として扱います。許可リストにあるプロフィールのみが対象となり、永続的なプロフィールの作成・削除ルートはプロキシ上でブロックされます。
この機能を無効にする方法：
- ノード側：nodeHost.browserProxy.enabled=false
- Gateway 側：gateway.nodes.browser.mode="off"

Browserless (ホスト型リモート CDP)

Browserless は、HTTPS や WebSocket 経由で CDP 接続 URL を提供するホスト型の Chromium サービスです。OpenClaw ではどちらの形式も利用できますが、リモートのブラウザプロフィールを作成するなら、Browserless のドキュメントにある直接の WebSocket URL を使うのが一番シンプルでおすすめです。

設定例：

{
  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 が提供されている場合、それを wss:// に変換して直接 CDP 接続するか、HTTPS URL のままにして OpenClaw に /json/version を自動検出させることもできます。

直接 WebSocket を使用する CDP プロバイダー

一部のホスト型ブラウザサービスでは、標準的な HTTP ベースの CDP 検出（/json/version）ではなく、直接の WebSocket エンドポイントを提供しています。OpenClaw はその両方をサポートしています。

HTTP(S) エンドポイント — OpenClaw が /json/version を呼び出して WebSocket デバッガー URL を見つけ、接続します。
WebSocket エンドポイント (ws:// / wss://) — OpenClaw が直接接続し、/json/version のステップをスキップします。Browserless や Browserbase など、WebSocket URL が提供されるサービスで利用してください。

Browserbase

Browserbase は、ヘッドレスブラウザを実行するためのクラウドプラットフォームです。CAPTCHA 回避、ステルスモード、レジデンシャルプロキシなどの機能が組み込まれています。

{
  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 key に置き換えます。
Browserbase は WebSocket 接続時にブラウザセッションを自動作成するため、手動でセッションを作成するステップは不要です。
無料枠では、同時接続 1 セッション、月間 1 時間のブラウザ利用が可能です。有料プランの制限については価格ページを確認してください。
API リファレンスや SDK ガイド、統合例については Browserbase のドキュメントを参照してください。

セキュリティ

重要なポイント：

ブラウザ制御はループバック（loopback）のみに制限されています。アクセスは Gateway の認証またはノードのペアリングを通じて行われます。
スタンドアロンのループバックブラウザ HTTP API は、共有シークレット認証のみを使用します。具体的には、Gateway のトークン認証、x-openclaw-password、または設定された Gateway パスワードによる HTTP Basic 認証です。
Tailscale Serve の ID ヘッダーや gateway.auth.mode: "trusted-proxy" 設定は、このスタンドアロンのループバックブラウザ API の認証には使用されません。
ブラウザ制御が有効で、共有シークレット認証が設定されていない場合、OpenClaw は起動時に gateway.auth.token を自動生成し、設定ファイルに保存します。
gateway.auth.mode がすでに password、none、または trusted-proxy に設定されている場合、トークンの自動生成は行われません。
Gateway やノードホストは Tailscale などのプライベートネットワーク内で運用し、公衆網への公開は避けてください。
リモート CDP の URL やトークンは機密情報として扱い、環境変数やシークレットマネージャーでの管理を推奨します。

リモート CDP のヒント：

可能な限り、暗号化されたエンドポイント（HTTPS または WSS）と有効期限の短いトークンを使用してください。
長期間有効なトークンを設定ファイルに直接書き込むのは避けてください。

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

OpenClawは、複数の名前付きプロファイル（ルーティング設定）をサポートしています。プロファイルには以下の種類があります。

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 の範囲で割り当てられます。
プロファイルを削除すると、そのローカルデータディレクトリはゴミ箱に移動されます。

すべてのコントロールエンドポイントは ?profile=<name> を受け付けます。CLI では --browser-profile を使用します。

Chrome DevTools MCP を介した既存セッション

OpenClawは、公式の Chrome DevTools MCP サーバーを介して、実行中の Chromium ベースのブラウザプロファイルにアタッチすることもできます。これにより、そのブラウザプロファイルですでに開いているタブやログイン状態を再利用できます。

公式の背景情報とセットアップのリファレンス：

組み込みプロファイル：

user

オプション：別の名前、色、またはブラウザデータディレクトリを使用したい場合は、独自のカスタム既存セッションプロファイルを作成してください。

デフォルトの動作：

組み込みの user プロファイルは Chrome MCP の自動接続を使用し、デフォルトのローカル Google Chrome プロファイルをターゲットにします。

Brave、Edge、Chromium、またはデフォルト以外の Chrome プロファイルを使用する場合は、userDataDir を指定します。

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}

次に、対応するブラウザで以下の操作を行います。

リモートデバッグ用に、そのブラウザの inspect ページを開きます。
リモートデバッグを有効にします。
ブラウザを実行したままにし、OpenClaw がアタッチする際の接続プロンプトを承認します。

一般的な inspect ページ：

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 が、選択されたライブタブからの参照を返す

アタッチが機能しない場合のチェック項目：

ターゲットの Chromium ベースのブラウザのバージョンが 144+ であること
そのブラウザの inspect ページでリモートデバッグが有効になっていること
ブラウザに表示されたアタッチの同意プロンプトを承認したこと
openclaw doctor は古い拡張機能ベースのブラウザ構成を移行し、デフォルトの自動接続プロファイル用に Chrome がローカルにインストールされているかチェックしますが、ブラウザ側のリモートデバッグを自動で有効にすることはできません。

エージェントでの利用：

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

注意点：

この方法は、サインイン済みのブラウザセッション内で動作するため、隔離された openclaw プロファイルよりもリスクが高くなります。
OpenClaw はこのドライバーのためにブラウザを起動しません。既存のセッションにアタッチするだけです。
OpenClaw はここで公式の Chrome DevTools MCP --autoConnect フローを使用します。userDataDir が設定されている場合、OpenClaw はそれを渡して、特定の Chromium ユーザーデータディレクトリをターゲットにします。
既存セッションのスクリーンショットは、ページキャプチャとスナップショットからの --ref 要素キャプチャをサポートしていますが、CSS の --element セレクターはサポートしていません。
既存セッションのページスクリーンショットは、Chrome MCP を介して Playwright なしで動作します。参照ベースの要素スクリーンショット（--ref）も動作しますが、--full-page を --ref や --element と組み合わせることはできません。
既存セッションでのアクションは、管理されたブラウザパスよりも制限されています。
- click, type, hover, scrollIntoView, drag, および select は、CSS セレクターではなくスナップショットの参照（refs）が必要です。
- click は左ボタンのみです（ボタンのオーバーライドや修飾キーは不可）。
- type は slowly=true をサポートしていません。fill または press を使用してください。
- press は delayMs をサポートしていません。
- hover, scrollIntoView, drag, select, fill, および evaluate は、呼び出しごとのタイムアウトのオーバーライドをサポートしていません。
- select は現在、単一の値のみをサポートしています。
既存セッションの wait --url は、他のブラウザドライバーと同様に、完全一致、部分一致、およびグロブパターンをサポートしています。wait --load networkidle はまだサポートされていません。
既存セッションのアップロードフックは ref または inputRef を必要とし、一度に 1 つのファイルをサポートします。CSS の element 指定はサポートしていません。
既存セッションのダイアログフックは、タイムアウトのオーバーライドをサポートしていません。
一部の機能（一括アクション、PDF エクスポート、ダウンロードのインターセプト、responsebody など）は、引き続き管理されたブラウザパスを必要とします。
既存セッションはホストローカルです。Chrome が別のマシンや別のネットワーク名前空間にある場合は、リモート CDP または Node.js ホストを使用してください。

分離の保証

専用のユーザーデータディレクトリ: 個人のブラウザプロファイルには一切触れません。
専用ポート: 開発ワークフローとの衝突を避けるため、デフォルトで 9222 を避け、他のポートを使用します。
決定論的なタブ制御: 「最後のタブ」といった曖昧な指定ではなく、targetId によってターゲットのタブを制御します。

ブラウザの選択

ローカルで起動する場合、OpenClaw は利用可能なブラウザを以下の順序で選択します。

Chrome
Brave
Edge
Chromium
Chrome Canary

browser.executablePath を設定することで、この動作を上書きできます。

プラットフォームごとの動作：

macOS: /Applications および ~/Applications をチェックします。
Linux: google-chrome, brave, microsoft-edge, chromium などを探索します。
Windows: 一般的なインストール場所をチェックします。

Control API（オプション）

ローカル環境での統合のために、Gatewayは小規模なループバックHTTP APIを公開しています。

ステータス/開始/停止: GET /, POST /start, POST /stop
タブ操作: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
スナップショット/スクリーンショット: GET /snapshot, POST /screenshot
アクション: POST /navigate, POST /act
フック: POST /hooks/file-chooser, POST /hooks/dialog
ダウンロード: POST /download, POST /wait/download
デバッグ: GET /console, POST /pdf
デバッグ: GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
ネットワーク: POST /response/body
状態管理: GET /cookies, POST /cookies/set, POST /cookies/clear
状態管理: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
設定: POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

すべてのエンドポイントで ?profile=<name> パラメータを使用できます。

共有シークレットによる Gateway 認証が設定されている場合、ブラウザのHTTPルートにも認証が必要です。

Authorization: Bearer <gateway token>
x-openclaw-password: <gateway password> または、そのパスワードを使用した HTTP Basic 認証

注意点：

このスタンドアロンのループバックブラウザ API は、trusted-proxy や Tailscale Serve の ID ヘッダーを使用しません。
gateway.auth.mode が none または trusted-proxy の場合、これらのループバックルートはそれらの ID 情報を保持するモードを継承しません。これらはループバック専用として運用してください。

`/act` のエラー定義

POST /act は、ルートレベルのバリデーションやポリシー違反に対して、以下のような構造化されたエラーレスポンスを返します。

{ "error": "<message>", "code": "ACT_*" }

現在の code 値の一覧です：

ACT_KIND_REQUIRED (HTTP 400): kind が不足しているか、認識できません。
ACT_INVALID_REQUEST (HTTP 400): アクションのペイロードの正規化またはバリデーションに失敗しました。
ACT_SELECTOR_UNSUPPORTED (HTTP 400): サポートされていないアクションの種類で selector が使用されました。
ACT_EVALUATE_DISABLED (HTTP 403): 設定により evaluate（または wait --fn）が無効化されています。
ACT_TARGET_ID_MISMATCH (HTTP 403): トップレベルまたはバッチ処理の targetId がリクエスト対象と競合しています。
ACT_EXISTING_SESSION_UNSUPPORTED (HTTP 501): 既存セッション（existing-session）プロファイルではサポートされていないアクションです。

その他の実行時エラーについては、code フィールドなしで { "error": "<message>" } のみが返される場合があります。

Playwright の要件

一部の機能（navigate/act/AI snapshot/role snapshot, element screenshots, PDF）を利用するには Playwright が必要です。Playwright がインストールされていない場合、これらのエンドポイントは 501 エラーを返します。

Playwright なしでも動作する機能：

ARIA snapshots
個別のタブで CDP WebSocket が利用可能な場合の、管理下にある openclaw ブラウザのページスクリーンショット
existing-session / Chrome MCP プロファイルのページスクリーンショット
スナップショット出力からの existing-session 参照ベースのスクリーンショット（--ref）

Playwright が必要な機能：

navigate
act
AI snapshots / role snapshots
CSS セレクターによる要素のスクリーンショット（--element）
ブラウザ全体の PDF エクスポート

また、要素のスクリーンショットでは --full-page は使用できません。その場合、ルートは fullPage is not supported for element screenshots というエラーを返します。

もし Playwright is not available in this gateway build というメッセージが表示された場合は、playwright-core ではなくフルパッケージの Playwright をインストールして Gateway を再起動するか、ブラウザサポートを含む形で OpenClaw を再インストールしてください。

Docker での Playwright インストール

Gateway を Docker で実行している場合は、npx playwright の使用を避けてください（npm のオーバーライドが競合するためです）。代わりに、同梱されている CLI を使用します。

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

ブラウザのダウンロードを永続化するには、PLAYWRIGHT_BROWSERS_PATH（例：/home/node/.cache/ms-playwright）を設定し、/home/node が OPENCLAW_HOME_VOLUME またはバインドマウント経由で永続化されていることを確認してください。詳細は Docker を参照してください。

動作の仕組み（内部構造）

ハイレベルな処理フローは以下の通りです：

小さな control server が HTTP リクエストを受け取ります。
CDP を介して Chromium ベースのブラウザ（Chrome/Brave/Edge/Chromium）に接続します。
クリック、入力、スナップショット、PDF 作成などの高度なアクションには、CDP 上で動作する Playwright を使用します。
Playwright がインストールされていない場合は、それを使用しない操作のみが提供されます。

この設計により、エージェントは安定した決定論的なインターフェースを維持しつつ、ローカルやリモートのブラウザ、プロファイルを柔軟に切り替えることができます。

CLI クイックリファレンス

すべてのコマンドで --browser-profile <name> を指定して、特定のプロファイルを対象にできます。また、すべてのコマンドで --json を使用でき、マシン読み取り可能な出力（安定したペイロード）を取得できます。

基本操作:

- openclaw browser status
- openclaw browser start
- openclaw browser stop
- openclaw browser tabs
- openclaw browser tab
- openclaw browser tab new
- openclaw browser tab select 2
- openclaw browser tab close 2
- openclaw browser open https://example.com
- openclaw browser focus abcd1234
- openclaw browser close abcd1234

調査:

- openclaw browser screenshot
- openclaw browser screenshot --full-page
- openclaw browser screenshot --ref 12
- openclaw browser screenshot --ref e12
- openclaw browser snapshot
- openclaw browser snapshot --format aria --limit 200
- openclaw browser snapshot --interactive --compact --depth 6
- openclaw browser snapshot --efficient
- openclaw browser snapshot --labels
- openclaw browser snapshot --selector "#main" --interactive
- openclaw browser snapshot --frame "iframe#main" --interactive
- openclaw browser console --level error

ライフサイクルに関する注意点:

attach-only やリモート CDP プロファイルの場合でも、テスト後のクリーンアップには openclaw browser stop を使用してください。これは基盤となるブラウザを終了させるのではなく、アクティブな制御セッションを閉じ、一時的なエミュレーションの上書きをクリアします。

- openclaw browser errors --clear
- openclaw browser requests --filter api --clear
- openclaw browser pdf
- openclaw browser responsebody "**/api" --max-chars 5000

アクション:

- openclaw browser navigate https://example.com
- openclaw browser resize 1280 720
- openclaw browser click 12 --double
- openclaw browser click e12 --double
- openclaw browser type 23 "hello" --submit
- openclaw browser press Enter
- openclaw browser hover 44
- openclaw browser scrollintoview e12
- openclaw browser drag 10 11
- openclaw browser select 9 OptionA OptionB
- openclaw browser download e12 report.pdf
- openclaw browser waitfordownload report.pdf
- openclaw browser upload /tmp/openclaw/uploads/file.pdf
- openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'`
- openclaw browser dialog --accept
- openclaw browser wait --text "Done"
- openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
- openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
- openclaw browser highlight e12
- openclaw browser trace start
- openclaw browser trace stop

状態:

- openclaw browser cookies
- openclaw browser cookies set session abc123 --url "https://example.com"
- openclaw browser cookies clear
- openclaw browser storage local get
- openclaw browser storage local set theme dark
- openclaw browser storage session clear
- openclaw browser set offline on
- openclaw browser set headers --headers-json '{"X-Debug":"1"}'
- openclaw browser set credentials user pass
- openclaw browser set credentials --clear
- openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
- openclaw browser set geo --clear
- openclaw browser set media dark
- openclaw browser set timezone America/New_York
- openclaw browser set locale en-US
- openclaw browser set device "iPhone 14"

補足事項:

upload と dialog は 準備（arming） のための呼び出しです。ファイル選択やダイアログをトリガーするクリックやキー入力の前に実行してください。
ダウンロードとトレースの出力パスは、OpenClaw の一時ルートディレクトリ内に制限されています。
- traces: /tmp/openclaw (フォールバック: ${os.tmpdir()}/openclaw)
- downloads: /tmp/openclaw/downloads (フォールバック: ${os.tmpdir()}/openclaw/downloads)
アップロードのパスは、OpenClaw の一時アップロードルートディレクトリ内に制限されています。
- uploads: /tmp/openclaw/uploads (フォールバック: ${os.tmpdir()}/openclaw/uploads)
upload は --input-ref または --element を使用して、ファイル入力を直接設定することもできます。
snapshot について:
- --format ai (Playwright がインストールされている場合のデフォルト): 数値 ref (aria-ref="<n>") を含む AI スナップショットを返します。
- --format aria: アクセシビリティツリーを返します（ref は含まれず、調査専用です）。
- --efficient (または --mode efficient): コンパクトなロールスナップショットのプリセットです（interactive + compact + depth + 低い maxChars）。
- 設定のデフォルト (ツール/CLI のみ): 呼び出し側がモードを渡さない場合に efficient スナップショットを使用するには、browser.snapshotDefaults.mode: "efficient" を設定してください（Gateway configuration を参照）。
- ロールスナップショットのオプション (--interactive, --compact, --depth, --selector) を指定すると、ref=e12 のような ref を持つロールベースのスナップショットが強制されます。
- --frame "<iframe selector>" は、ロールスナップショットの範囲を iframe に限定します（e12 のようなロール ref と組み合わせて使用します）。
- --interactive は、操作可能な要素をフラットで選択しやすいリストとして出力します（アクションを実行する際に最適です）。
- --labels は、ref ラベルがオーバーレイされたビューポートのみのスクリーンショットを追加します（MEDIA:<path> を出力します）。
click や type などには、snapshot から取得した ref（数値の 12 またはロール ref の e12）が必要です。アクションにおいて CSS セレクターは意図的にサポートされていません。

スナップショットと ref

OpenClaw は 2 種類の「スナップショット」スタイルをサポートしています。

AI スナップショット (数値 ref): openclaw browser snapshot (デフォルト; --format ai)
- 出力: 数値 ref を含むテキストスナップショット。
- アクション: openclaw browser click 12, openclaw browser type 23 "hello"。
- 内部動作: ref は Playwright の aria-ref を通じて解決されます。
ロールスナップショット (e12 のようなロール ref): openclaw browser snapshot --interactive (または --compact, --depth, --selector, --frame)
- 出力: [ref=e12] (およびオプションで [nth=1]) を含むロールベースのリストまたはツリー。
- アクション: openclaw browser click e12, openclaw browser highlight e12。
- 内部動作: ref は getByRole(...) (重複がある場合は nth() を追加) を通じて解決されます。
- --labels を追加すると、e12 ラベルがオーバーレイされたビューポートのスクリーンショットが含まれます。

Ref の挙動:

Ref は ページ遷移（navigation）をまたいで保持されません。エラーが発生した場合は、再度 snapshot を実行して新しい ref を使用してください。
--frame を指定して取得したロールスナップショットの場合、ロール ref は次のロールスナップショットが実行されるまで、その iframe 内にスコープが制限されます。

Wait機能の強化

時間やテキストによる待機だけでなく、他にもさまざまな条件で待機させることができます。

URLを待機（Playwrightがサポートするglob形式を利用できます）:
- openclaw browser wait --url "**/dash"
ロード状態（load state）を待機:
- openclaw browser wait --load networkidle
JSの述語（predicate）を待機:
- openclaw browser wait --fn "window.ready===true"
セレクターが表示されるまで待機:
- openclaw browser wait "#main"

これらは組み合わせて使用することも可能です。

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

デバッグのワークフロー

「要素が表示されない」「strict mode違反」「他の要素に隠れている（covered）」といった理由でアクションが失敗した場合は、以下の手順を試してみてください。

openclaw browser snapshot --interactive を実行します。
click <ref> や type <ref> を使用します（interactive mode では role ref を使うのがおすすめです）。
それでも失敗する場合は、openclaw browser highlight <ref> を実行して、Playwright がどこをターゲットにしているかを確認します。
ページの挙動が不自然な場合：
- openclaw browser errors --clear を実行してエラーを確認・クリアします。
- openclaw browser requests --filter api --clear で API リクエストを確認・クリアします。
さらに深いデバッグが必要な場合は、trace を記録してください：
- openclaw browser trace start で記録を開始します。
- 問題の現象を再現させます。
- openclaw browser trace stop を実行します（TRACE:<path> が出力されます）。

JSON出力

--jsonフラグは、スクリプト作成や構造化されたツールでの利用に便利です。

openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json

JSON形式のRole snapshotsには、refsに加えて小さなstatsブロック（lines/chars/refs/interactive）が含まれています。これにより、ツール側でペイロードのサイズや密度を把握して処理できるようになります。

状態と環境の設定

これらは、「サイトを特定の条件で動作させる」といったワークフローで役立つ設定項目です。

Cookies: cookies, cookies set, cookies clear
Storage: storage local|session get|set|clear
Offline: set offline on|off
Headers: set headers --headers-json '{"X-Debug":"1"}'（以前の set headers --json '{"X-Debug":"1"}' も引き続きサポートされます）
HTTP basic auth: set credentials user pass（または --clear）
Geolocation: set geo <lat> <lon> --origin "https://example.com"（または --clear）
Media: set media dark|light|no-preference|none
Timezone / locale: set timezone ..., set locale ...
Device / viewport:
- set device "iPhone 14"（Playwrightのデバイスプリセット）
- set viewport 1280 720

セキュリティとプライバシー

openclaw のブラウザプロファイルには、ログイン済みのセッション情報が含まれることがあります。これは機密情報として慎重に扱ってください。
browser act kind=evaluate や openclaw browser evaluate、そして wait --fn は、ページ内で任意の JavaScript を実行します。プロンプトインジェクションによって操作が誘導されるリスクがあるため、もしこれらの機能が不要であれば browser.evaluateEnabled=false で無効化しておくのがベストな選択です。
ログインやアンチボットに関する注意点（X/Twitter など）については、Browser login + X/Twitter posting を確認してください。
Gateway や Node.js ホストは、ループバックアドレスや tailnet 限定にするなど、必ずプライベートな環境に保つようにしましょう。
リモートの CDP エンドポイントは非常に強力な権限を持ちます。必ずトンネル接続などで保護するようにしてください。

以下は、プライベート・内部ネットワークへの接続をデフォルトでブロックする厳格なモードの設定例です。

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // optional exact allow
    },
  },
}

トラブルシューティング

Linux 特有の問題（特に snap 版の Chromium など）については、Browser troubleshooting を参照してください。

WSL2 Gateway と Windows 上の Chrome を組み合わせた構成については、WSL2 + Windows + remote Chrome CDP troubleshooting に解決策をまとめています。

Agentツールと制御の仕組み

Agentがブラウザ操作のために使用できるツールは、1つだけです。

browser — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

それぞれの機能は以下のように対応しています。

browser snapshot は、安定したUIツリー（AIまたはARIA）を返します。
browser act は、スナップショットの ref IDを使用して、クリック、入力、ドラッグ、選択などを実行します。
browser screenshot は、ページ全体または特定の要素のピクセルをキャプチャします。
browser は以下のパラメータを受け取ります。
- profile: 使用するブラウザプロファイル（openclaw, chrome, またはリモートCDP）を選択します。
- target (sandbox | host | node): ブラウザを動作させる場所を選択します。
- Sandboxセッションにおいて target: "host" を使用する場合、agents.defaults.sandbox.browser.allowHostControl=true の設定が必要です。
- target が省略された場合、Sandboxセッションでは sandbox が、それ以外のセッションでは host がデフォルトになります。
- ブラウザ操作が可能なNodeが接続されている場合、target="host" または target="node" と指定して固定しない限り、ツールは自動的にそのNodeへルーティングされることがあります。

この仕組みにより、Agentの動作が確実（deterministic）になり、壊れやすいセレクターの使用を避けることができます。

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。

OpenClaw で分離ブラウザを構築：安全な自動化環境をセットアップ

得られるもの

クイックスタート

プラグインによる制御

ブラウザコマンドやツールが見つからない場合

プロファイル: openclaw vs user

設定

Brave（またはその他の Chromium ベースのブラウザ）の使用

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

Node browser proxy (ゼロ構成のデフォルト設定)

Browserless (ホスト型リモート CDP)

直接 WebSocket を使用する CDP プロバイダー

Browserbase

セキュリティ

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

Chrome DevTools MCP を介した既存セッション

分離の保証

ブラウザの選択

Control API（オプション）

/act のエラー定義

Playwright の要件

Docker での Playwright インストール

動作の仕組み（内部構造）

CLI クイックリファレンス

スナップショットと ref

Wait機能の強化

デバッグのワークフロー

JSON出力

状態と環境の設定

セキュリティとプライバシー

トラブルシューティング

Agentツールと制御の仕組み

関連情報

まだ解決しませんか？

プロファイル: `openclaw` vs `user`

`/act` のエラー定義