Chrome エクステンション（ブラウザリレー）

OpenClaw Chrome エクステンションを使うと、別の openclaw 管理 Chrome プロファイルを起動する代わりに、既存の Chrome タブ（通常の Chrome ウィンドウ）をエージェントが制御できます。

アタッチ/デタッチは Chrome ツールバーのボタン 1 つで行います。

OpenClaw エクステンションリレーの代わりに Chrome 公式の DevTools MCP アタッチフローを使いたい場合は、existing-session ブラウザプロファイルを使用してください。ブラウザ を参照してください。Chrome 側のセットアップドキュメントについては、Chrome for Developers: Use Chrome DevTools MCP with your browser session および Chrome DevTools MCP README を参照してください。

構成要素（コンセプト）

3 つのパーツがあります:

  • ブラウザコントロールサービス（Gateway またはノード）: エージェント/ツールが（Gateway 経由で）呼び出す API
  • ローカルリレーサーバー（ループバック CDP）: コントロールサーバーとエクステンション間のブリッジ（デフォルト: http://127.0.0.1:18792）
  • Chrome MV3 エクステンション: chrome.debugger を使用してアクティブタブにアタッチし、CDP メッセージをリレーにパイプ

OpenClaw は、適切なプロファイルを選択して通常の browser ツールインターフェース経由でアタッチされたタブを制御します。

インストール / 読み込み（未パッケージ化）

  1. エクステンションを安定したローカルパスにインストール:
openclaw browser extension install
  1. インストールされたエクステンションのディレクトリパスを表示:
openclaw browser extension path
  1. Chrome で chrome://extensions を開く
  • 「デベロッパーモード」を有効化
  • 「パッケージ化されていない拡張機能を読み込む」を選択し、上記で表示されたディレクトリを指定
  1. エクステンションをピン留め。

更新（ビルドステップなし）

エクステンションは OpenClaw リリース（npm パッケージ）内に静的ファイルとして同梱されています。別途「ビルド」ステップはありません。

OpenClaw のアップグレード後:

  • openclaw browser extension install を再実行して、OpenClaw ステートディレクトリ配下のインストールファイルを更新。
  • Chrome で chrome://extensions を開き、エクステンションの「再読み込み」をクリック。

使い方（Gateway トークンを一度設定）

OpenClaw には、デフォルトポートのエクステンションリレーを指す chrome という組み込みブラウザプロファイルが含まれています。

初回アタッチ前に、エクステンションのオプションを開いて以下を設定:

  • Port（デフォルト 18792）
  • Gateway token（gateway.auth.token / OPENCLAW_GATEWAY_TOKEN と一致させる必要あり）

使用方法:

  • CLI: openclaw browser --browser-profile chrome tabs
  • エージェントツール: browser で profile="chrome" を指定

別の名前やリレーポートを使いたい場合は、独自のプロファイルを作成:

openclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

カスタム Gateway ポート

カスタム Gateway ポートを使用している場合、エクステンションリレーポートは自動的に導出されます:

エクステンションリレーポート = Gateway ポート + 3

例: gateway.port: 19001 の場合:

  • エクステンションリレーポート: 19004（gateway + 3）

エクステンションのオプションページで、導出されたリレーポートを設定してください。

アタッチ / デタッチ（ツールバーボタン）

  • OpenClaw に制御させたいタブを開く。
  • エクステンションアイコンをクリック。
    • バッジに ON が表示されればアタッチ完了。
  • 再度クリックでデタッチ。

どのタブが制御されるか？

  • 「今見ているタブ」が自動的に制御されるわけではありません。
  • ツールバーボタンをクリックして明示的にアタッチしたタブのみが制御されます。
  • 切り替えるには: 別のタブを開いてそこでエクステンションアイコンをクリック。

バッジとよくあるエラー

  • ON: アタッチ済み。OpenClaw がそのタブを操作可能。
  • …: ローカルリレーに接続中。
  • !: リレーに到達不能/認証失敗（最も一般的: リレーサーバーが動作していない、または Gateway トークンが未設定/不正）。

! が表示される場合:

  • Gateway がローカルで動作していることを確認（デフォルト構成）。Gateway が別の場所で動作している場合は、このマシンでノードホストを実行。
  • エクステンションのオプションページを開くと、リレーの到達性と Gateway トークン認証が検証される。

リモート Gateway（ノードホストを使用）

ローカル Gateway（Chrome と同じマシン）— 通常は追加手順不要

Gateway が Chrome と同じマシンで動作している場合、ループバックでブラウザコントロールサービスを起動し、リレーサーバーも自動起動します。エクステンションはローカルリレーと通信し、CLI/ツール呼び出しは Gateway に送られます。

リモート Gateway（Gateway が別のマシン）— ノードホストを実行

Gateway が別のマシンで動作している場合、Chrome が動作しているマシンでノードホストを起動してください。Gateway がそのノードにブラウザアクションをプロキシします。エクステンションとリレーはブラウザマシンのローカルに留まります。

複数のノードが接続されている場合は、gateway.nodes.browser.node でピン留めするか、gateway.nodes.browser.mode を設定してください。

サンドボックス（ツールコンテナ）

エージェントセッションがサンドボックス化されている場合（agents.defaults.sandbox.mode != "off"）、browser ツールが制限される可能性があります:

  • デフォルトでは、サンドボックス化されたセッションはサンドボックスブラウザ（target="sandbox"）を対象とし、ホストの Chrome ではありません。
  • Chrome エクステンションリレーの制御にはホストブラウザコントロールサーバーへのアクセスが必要です。

対処法:

  • 最も簡単: サンドボックス化されていないセッション/エージェントからエクステンションを使用。
  • またはサンドボックス化されたセッションにホストブラウザ制御を許可:
{
  agents: {
    defaults: {
      sandbox: {
        browser: {
          allowHostControl: true,
        },
      },
    },
  },
}

ツールポリシーで拒否されていないことを確認し、必要に応じて browser を target="host" で呼び出してください。

デバッグ: openclaw sandbox explain

リモートアクセスのヒント

  • Gateway とノードホストは同じテイルネット上に配置し、リレーポートを LAN やパブリックインターネットに公開しない。
  • ノードは意図的にペアリングし、リモート制御が不要な場合はブラウザプロキシルーティングを無効化（gateway.nodes.browser.mode="off"）。
  • 実際のクロスネームスペースの必要性がない限り、リレーはループバックのまま。WSL2 などの分割ホスト構成では、browser.relayBindHost を 0.0.0.0 などの明示的なバインドアドレスに設定し、Gateway 認証、ノードペアリング、プライベートネットワークでアクセスを制限。

“extension path” の仕組み

openclaw browser extension path は、エクステンションファイルが格納されたインストール済みのディスク上のディレクトリを表示します。

CLI は意図的に node_modules パスを表示しません。必ず最初に openclaw browser extension install を実行して、OpenClaw ステートディレクトリ配下の安定した場所にエクステンションをコピーしてください。

インストールディレクトリを移動または削除すると、有効なパスから再読み込みするまで Chrome がエクステンションを破損状態としてマークします。

セキュリティへの影響（必ずお読みください）

この機能は強力であると同時にリスクがあります。モデルに「ブラウザの操作権限」を与えるようなものだと考えてください。

  • エクステンションは Chrome のデバッガー API（chrome.debugger）を使用します。アタッチ中、モデルは以下が可能です:
    • そのタブ内でのクリック/入力/ナビゲーション
    • ページコンテンツの読み取り
    • タブのログインセッションがアクセスできるものすべてへのアクセス
  • 専用の openclaw 管理プロファイルのような分離はありません。
    • 日常使用のプロファイル/タブにアタッチすると、そのアカウントの状態へのアクセスを許可することになります。

推奨事項:

  • エクステンションリレー用には、個人のブラウジングとは別の専用 Chrome プロファイルの使用を推奨。
  • Gateway とノードホストはテイルネット専用に。Gateway 認証とノードペアリングに依存する。
  • リレーポートを LAN（0.0.0.0）で公開したり、Funnel（パブリック）を使用したりしない。
  • リレーは非エクステンションオリジンをブロックし、/cdp と /extension の両方で Gateway トークン認証を要求します。

関連:

arrow_back
前へ
Browser Login
次へ
Browser Linux Troubleshooting
arrow_forward