browser-use

ブラウザーの使用

ユーザーが現在使用している実際の Chrome プロファイルを操作します。特に、ログインが必要な作業や実際の UI の検証に使用します。

経路

1. アクティブなセッションで Codex の Chrome または Chrome [Internal] プラグインを呼び出せる場合は、それを使用します。ディスク上にインストールされているだけでは不十分です。
2. それ以外の場合は、OpenClaw 拡張機能を介した mcporter の経路を優先します。
3. 従来の DevTools への直接接続は、明示的に最後の代替手段として使用します。

mcporter では、MCP 呼び出しが引き続きエージェント向けの制御インターフェースです。OpenClaw 拡張機能はその下位のトランスポートであり、別個のツールではありません。リレーのみのルーティングを強制するには、標準のグローバル Chrome サーバー定義で chromeDevtoolsRelay: "require" を設定します。呼び出し側のポリシーも明示したままにします。

MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.<tool>

そのため、エージェントが chrome-devtools MCP ツールを要求するのは想定どおりです。Chrome の リモートデバッグを許可しますか？ というプロンプトやリレーポリシーのエラーが表示された場合は、拡張機能のトランスポートが使用されていません。共有デーモンが標準ポリシーを保持します。シェル環境のプレフィックスだけでは、そのポリシーを変更できません。

ユーザーが分離されたブラウザーや新しいブラウザーを明示的に求めない限り、分離された Chrome、Codex のアプリ内ブラウザー、Playwright、Puppeteer、AppleScript、osascript、汎用 GUI スクリプト、macOS の open を、ブラウザー操作の代替手段として使用しないでください。Peekaboo は、Chrome や拡張機能のセットアップ、および画面に表示されるプロンプトに限り使用できます。ログインが必要なサイトでは、実際のプロファイルの Cookie、SSO、デバイスの信頼設定、拡張機能に依存することがよくあります。

レンダリングされたブラウザーで発生するバグについては、この実際のプロファイルを通じて動作を検証してください。curl、ソースコードの確認、API のチェック、分離されたテスト用ブラウザーは補足的な証拠として扱い、実際の UI による検証の代わりにはしないでください。

拡張機能のリレーモデル

OpenClaw は、モード 0600 の認証情報ディレクトリに、ホストごとのランダムなリレーキーを作成します。拡張機能と同一ホスト上のクライアントは、nonce に紐付けられた相互 HMAC 証明を使用します。再利用可能なキーが、未検証のループバックリスナーに送信されたり、URL に含められたり、子 MCP プロセスに渡されたりすることはありません。認証情報を設定、コマンド出力、チャット、ログ、スクリーンショットに含めないでください。

同一ホスト上のリレーでは、mcporter が /json/version を認証し、保持している同じソケットを /cdp にアップグレードしたうえで、保護された一回限りのローカルハンドオフを chrome-devtools-mcp に渡します。エージェントは引き続き標準の MCP ツールを呼び出します。リレー経由のルーティングが成功すれば、DevTools への直接接続と Chrome の承認プロンプトが不要になります。

新しいペアリングのデフォルトは すべてのタブ です。ポップアップで明示的に一時停止されたタブを除き、対象となる通常のタブがすべて公開されます。既存のペアリングでは、保存済みのモードが引き続き使用されます。選択したタブ モードでは、Chrome の OpenClaw というタイトルのタブグループに含まれていることが共有範囲の境界となります。どちらのモードでも、制限付き／内部ページ、シークレットモード、他のプロファイル、対象となる URL がないタブは除外されます。

トポロジーの境界

wss:// を使ったリモート Gateway の直接ペアリングでは、OpenClaw の Gateway 側のブラウザーツールからローカルの Chrome を操作できます。ただし、ローカルの mcporter プロセス用のローカルリレーは作成されません。リモートのシークレットを日常的にコピーしたり、この境界を迂回するアドホックな SSH トンネルを構築したりしないでください。

ローカル mcporter がローカルリレーを認証できない場合、拡張機能を介した mcporter の経路は利用できません。そのことを明確に伝えるか、明示された従来の代替手段を使用してください。リモート Gateway による制御や直接接続を、ローカルリレーの成功として示してはなりません。

セットアップと修復

• Load unpacked の前に openclaw browser extension install を実行します。拡張機能を OpenClaw が管理する安定したパスにコピーし、そのパスの決定論的な Chrome ID を事前登録して、読み込むパスを表示します。最初のネイティブ呼び出し時に、ローカルまたはブラウザーノードのトポロジーで自動的にペアリングされます。
• openclaw browser extension status --json を使って、インストール済みのコピー、正確なオリジン、ネイティブホストの登録を確認します。ステータスに問題がなく、manualSetupRequired: false と表示される必要があります。
• Settings で自動セットアップの準備が完了していること、ポップアップで Connected と表示されていることを確認します。ユーザーがアクセスモードを変更しない限り、新規インストールでは All tabs と表示されます。通常のローカルフローでは、ペアリング文字列のコピーもポップアップのセットアップも必要ありません。
• 以前のネイティブホスト接続失敗は Chrome プロセスにキャッシュされます。拡張機能のインストール前にネイティブメッセージングを試みた場合は、インストール後に Chrome を一度再起動してください。同じプロセス内で繰り返し再試行しても、そのキャッシュは修復できません。
• ペアリング後、またはリレールートの変更後に、リレーのみの動作確認を再実行する前に mcporter デーモンを停止してください。Gateway を再起動すると、上流ソケットが切断されたままの Chrome DevTools 子プロセスが残る場合があります。次の呼び出しで新しい接続が作成される前に、mcporter daemon stop を実行してそのプロセスを終了させます。
• Gateway への直接リモートペアリングは、引き続き Advanced の手動フローです。Gateway のブラウザーパスには対応しますが、ローカル mcporter 用のローカルリレーは作成しません。

検出タイムアウトとデーモンの設定

MCPorter は openclaw browser extension cdp --json を使って実際のリレーを検出します。パッケージ版の OpenClaw でも、コールドスタートに 5 秒以上かかることがあります。mcporter 0.13.10 では、検出に失敗するとポート 18799 にフォールバックします。そのため、タイムアウトが誤ったエンドポイントでの network-error として現れたり、後続の検出で実際のエンドポイントが返されたときに browser_owner_conflict として現れたりすることがあります。このような一連の動作を、別の Chrome オーナーや認証情報のローテーションが失敗の原因である証拠だと解釈しないでください。

共有 Chrome オーナーには、OS アカウントの標準設定ファイル ~/.mcporter/mcporter.json（JSON ファイルが存在しない場合に限り mcporter.jsonc）を使用してください。既存の Chrome 定義に、コマンドや引数、その他の設定を維持したまま、次のフィールドを統合してください。

{
  "chromeDevtoolsRelay": "require",
  "env": {
    "MCPORTER_CHROME_DEVTOOLS_RELAY_TIMEOUT_MS": "20000"
  }
}

リレーのタイムアウトは、各検出ステップまたは認証ステップの上限を定めるものであり、クライアントの操作全体の期限を延長するものではありません。Chrome の初回起動では、MCP の初期化と要求されたツール呼び出しの前に、複数回の検出チェックが実行されることがあります。古いクライアントがインストールされている場合は、標準設定の 1 ステップあたり 20000 と、初回呼び出しまたはスキーマ一覧表示での明示的な --timeout 300000 を組み合わせてください。例：

MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.list_pages --timeout 300000 --output text

Chrome 固有の新しい外側のデフォルト値を適用するには、呼び出し元のクライアントをアップグレードする必要があります。明示的な --timeout、MCPORTER_CALL_TIMEOUT、MCPORTER_LIST_TIMEOUT は引き続きこれらのデフォルト値を上書きします。より小さい値で上書きすると、起動が途中で打ち切られることがあります。

デーモンは、標準の Chrome 環境から継承した MCPORTER_CHROME_DEVTOOLS_RELAY_* と OPENCLAW_* の制御用変数を意図的に除外します。シェルでのエクスポートは既存のオーナーには反映されず、再起動後も有効な恒久的な対処にはなりません。これらの変数が除外されることを前提としたプレースホルダーは使わず、標準定義の env にリテラル値を設定してください。明示的なエンドポイントが必要な場合は、ポートを確認したうえで、認証情報を含まない検証済みの HTTP ループバックベース URL（例：ポートを確認した後の http://127.0.0.1:28799）を、そこで MCPORTER_CHROME_DEVTOOLS_RELAY_URL に設定してください。この上書きには、ws://127.0.0.1:28799/cdp のような WebSocket CDP URL は使用できません。特に複数の OpenClaw インストールが共存している場合は、推測したポートやハードコードしたポートを使わず、十分なタイムアウトを設定して検出することを推奨します。

標準設定を変更した後は、実行中の呼び出しが完了するのを待ってから mcporter daemon stop を実行してください。呼び出しが残っているために停止が拒否された場合は、それらの完了を待ってから停止を再試行してください。停止に成功した後にのみ次へ進んでください。次の呼び出しで、保存済みの設定を使ってデーモンが起動し、その後の再起動にも同じ設定が使用されます。mcporter daemon status --json でリレーの選択結果を確認し、以下の準備完了確認をもう一度行ってください。新しいタイムアウトのデフォルト値や、検出失敗に関する明示的な診断に依存する前に、インストール済みの mcporter のバージョンを確認してください。ソースコードを修正しても、すでにインストール済みのバイナリや実行中のデーモンは更新されません。

現在の openclaw browser extension cdp --json は、デフォルトでは機密情報以外のメタデータを出力しますが、古いバージョンやレガシーベアラーオプションでは認証情報が露出することがあります。日常的な診断には mcporter のマスキング済みステータスを使い、レガシー認証情報は要求せず、プロセスの引数もダンプしないでください。認証情報が露出した疑いがある場合は、ホストごとのシークレットをローテーションし、再度ペアリングしてください。

フェイルクローズ方式の準備完了確認

拡張機能のルートを準備完了と判断する前に、以下の条件をすべて満たしていることを確認してください。

1. 拡張機能のステータスに安定版コピーと正確なネイティブ登録が問題なしと表示され、設定に自動セットアップの準備完了と表示されていること。
2. ポップアップに接続済みと表示され、対象の通常タブが一時停止されていないこと。選択したタブモードでは、そのタブがOpenClawグループにも属している必要があります。
3. ペアリング、リレールート、または正規設定を変更した後、mcporter が停止されており、次の呼び出しで新しいデーモンが起動していること。
4. 正規の Chrome 定義で chromeDevtoolsRelay: "require" を使用し、MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require を指定した呼び出しが成功すること。正規のポリシーでは DevTools への直接フォールバックが禁止されているため、成功すればリレーの確実な証明になります。
5. 既知の操作可能な使い捨てタブで、選択と評価の両方が成功すること。

MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.list_pages --args '{}' --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.select_page --args '{"pageId":9}' --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.evaluate_script --args '{"function":"() => ({title: document.title, href: location.href})"}' --output json

リレーポリシーエラーは、拡張機能のトランスポートが利用できないことを意味します。require を指定せずに再試行するのではなく、問題を報告するか修復してください。ブロック中の**リモートデバッグを許可しますか？**というプロンプトが表示された場合は、レガシー接続が試みられたことを示しています。

一般的なフロー

ページを一覧表示し、共有された対象だけを選択して、操作前にスナップショットを取得し、新しいスナップショット UID を使用します。レイアウトが重要でない限り、スクリーンショットより DOM スナップショットを優先してください。

MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.list_pages --args '{}' --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.select_page --args '{"pageId":9}' --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.take_snapshot --args '{}' --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.click --args '{"uid":"1_38","includeSnapshot":true}' --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.fill --args '{"uid":"1_13","value":"text","includeSnapshot":true}' --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.evaluate_script --args '{"function":"() => document.title"}' --output json

ライブ UI を確認するには、操作前に現在のページ状態を取得し、要求された操作を実行してから、レンダリング結果のスナップショットを取得するか評価してください。シークレットを DOM、入力、ネットワーク、コンソール、スクリーンショットの出力に含めないでください。認証情報を確認する場合は、存在の有無、長さ、ステータスコード、アカウント名や組織名など、安全な形式の情報だけを返してください。

自動化を利用できない場合は、禁止されたツールや分離されたツールに黙って切り替えるのではなく、検証できない点を報告してください。

引数と出力の仕組み

--args が受け付けるのはインライン JSON のみです。@file は読み込みません。フラグ形式の名前付き引数では読み込めます。

MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.navigate_page url=@/tmp/target-url.txt --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.evaluate_script function=@/tmp/probe.js --output json

これは使いやすさだけでなく、安全性を確保するための基本機能として扱ってください。サインイン URL、マジックリンク、コールバック URL は認証情報と同等です。モード 0600 のファイルに書き込み、ファイル参照で渡すことで、シェル履歴、プロセス引数、キャプチャされたツール出力に含まれないようにしてください。同じ形式を使えば、引用符や制御文字のエラーを避けて複数行の JavaScript 関数を渡すこともできます。

ログインフローの前に知っておくとよい、その他の呼び出しの仕組み：

• 汎用クライアントの既定値は、呼び出しが 60 秒、一覧表示が 30 秒です。これはリレーのステップごとの検出／認証タイムアウトとは別です。古いクライアントで Chrome の初回起動に時間がかかる場合は、前述のとおり --timeout 300000 が必要です。後続の対話操作では、必要に応じて明示的なタイムアウトを指定してください。
• filePath を指定した take_screenshot は、サーバーに設定されたワークスペースのルート内に制限され、任意のパスは拒否されます。filePath を省略し、--output json から base64 画像を読み取ってローカルでデコードしてください。
• 対象が共有されていない場合、new_page は制限中または利用不可のタブとして失敗することがあります。新しいタブを作成せず、すでに共有されているタブに移動してください。
• mcporter list <server> --schema は実際の関数シグネチャを表示します。パラメーター名を推測せず、これを使用してください。

クリックしても反応しない場合

uid を指定した click は成功を返しても、何も起きないことがあります。一部のページでは、合成クリックを無視するようにハンドラーが設定されています。反応がないからといって操作が実行されたとは限らないため、動作したと決めつけず、アクティベーションのたびに状態を確認してください。

クリックしても反応しない場合は、press_key （Tab、Shift+Tab、Enter）を使ってキーボードで操作し、確定する前にスクリーンショットでフォーカスを確認してください。 フォーカスリングは、次に Enter を受け取るコントロールを示す唯一の信頼できる証拠です。また、同意画面では、目立つ安全そうなボタンの隣に、強調度は低いものの実際に選びたいリンクが置かれていることがよくあります。そのようなページで確認せずに Enter を押すと、誤ったコントロールが選択されます。

スナップショットの uid 値は、ナビゲーションや再レンダリングが行われると無効になります。各手順の後に take_snapshot を再実行し、uid を取得し直してください。古い uid を使うと要素が存在しないというエラーが返されます。これは、同じ呼び出しを再試行するのではなく、スナップショットを取り直すべき合図です。

タスクの途中でリレーにタブが表示されなくなった場合

対象となるタブが閉じられた、現在のタブが制限または一時停止された、「Selected tabs」モードでグループのメンバーが失われた、あるいは拡張機能の接続が切れた場合、タスクの途中でリレーがタブを表示しなくなることがあります。問題が表面化しないこともあります。list_pages が空の結果を返し、その後の呼び出しがタイムアウトすることがあります。

ページリストが空の場合は、「ブラウザーが消えた」ではなく「リレーに対象となるタブがない」と判断してください。Chrome が実行中か確認し、ポップアップでの接続状態と現在のタブの Pause／Allow 状態を確認してから、アクセスモードを確認してください。「Selected tabs」モードでのみ、OpenClaw グループを復元する必要があります。mcporter を再起動しても、拡張機能の接続切れ、タブが対象外であること、アクセス設定は修復できません。

問題を回避するために、全プロファイルへの接続や分離されたブラウザーへ切り替えないでください。ユーザーがその場にいるサインイン作業の場合は、ユーザーがすでに操作しているブラウザーに URL を渡すほうが、迅速で誠実な対応です。フローのコールバックが別のホストで待ち受けている場合は、まずそのポートをユーザーのマシンに転送してください。それ以外の場合は、アクセスできないことを報告してください。

レガシーの代替手段：全プロファイルへの直接接続

呼び出し可能なプラグインと、認証済みのローカル拡張機能リレーがどちらも利用できない場合に限り、これを使用してください。実際のプロファイルにあるすべてのタブが公開され、Chrome の「Allow remote debugging?」というブロックプロンプトが表示されることがあります。

Chrome に接続を許可するか尋ねる、明確で誤解の余地がないプロンプトが表示された場合は、一度だけ許可してから list_pages を再実行してください。プロンプトが表示されない、内容が曖昧、または再試行に失敗した場合は中止し、ユーザーに確認するか、Chrome DevTools MCP を利用できないことを報告してください。許可を繰り返し求めたり、Chrome や mcporter を何度も再起動したり、ブラウザープロセスを強制終了したりしないでください。

操作する前に、list_pages に対象の実プロファイルのタブが表示されることを確認してください。この方法は必ず「全プロファイルへの直接接続」と明記し、OpenClaw 拡張機能リレーの接続成功とは表現しないでください。