open-browser-use

Open Browser Use

概要

Open Browser Use は、MV3 Chrome 拡張機能、ローカルのネイティブメッセージングホスト、CLI、SDK、およびオプションの stdio MCP サーバーを接続し、エージェントが実際の Chrome プロファイルを自動操作できるようにします。Codex.app 専用ではありません。使用しているエージェントのランタイムに合わせて、コマンド、MCP の設定、SDK の例を調整してください。

基本的なワークフロー

1. open-browser-use ping または obu ping でセットアップを確認します。セットアップが完了していないために失敗する場合は、references/installation.md をお読みください。
2. 接続されているターゲットから適切なブラウザーとプロファイルを選びます。ブラウザーコマンドを実行する前に、以下の「ブラウザーとプロファイルの扱い」をご覧ください。
3. タブを開いたり取得したりする前に、現在のエージェントタスク用の一意なブラウザーセッション ID を選びます。利用できる場合は、実行環境の会話／セッション ID を使用してください。そうでなければ、obu-<task-slug>-<timestamp> のような短い一意の ID を作成します。このタスクでは、すべての Open Browser Use コマンドで同じ ID を再利用してください。
4. タブを開いたり取得したりする前に、現在のブラウザータスクグループに名前を付けます。短いタスク名の後に - OBU を付けてください。適切なタスク名がない場合は、Task - OBU を使用します。
5. 新しいタブを開く前に、user-tabs ／ user_tabs を実行し、✅ Open Browser Use または以前の handoff タスクグループ内のタブも含め、既存のタブからタスクを続行できるか確認します。URL／タイトル／グループが現在のタスクに明らかに一致する場合は、そのタブを取得して続行し、重複するタブを開かないでください。ローカルの変更を検証または受け入れる場合、ユーザーがすでに開いている開発サーバーのタブ（たとえば、localhost、127.0.0.1、または *.local ／ *.test ホスト）も対象です。同じアプリのタブをもう一つ開くのではなく、そのタブを取得して再利用してください。
6. 簡単な確認や単発の操作には、CLI の info、tabs、user-tabs、history、open-tab、navigate、cdp、call を使用します。
7. 少数の行単位のアクションプランで十分で、SDK コードを書く必要がない場合は、CLI レベルの複数ステップのオーケストレーションに open-browser-use run ／ obu run を使用します。
8. 使用中のエージェントランタイムがローカル MCP サーバーに対応している場合は、obu mcp を設定し、公開されたブラウザーツールを直接呼び出します。MCP から同じ行単位のオーケストレーションを行うには、run_action_plan MCP ツールを使用します。references/sdk-and-protocol.md をお読みください。
9. より大規模な複数ステップのワークフロー、イベントサブスクリプション、より柔軟な制御フロー、または使用中のエージェントランタイムですでにコードを実行している場合は、JavaScript、Python、または Go SDK を使用します。references/sdk-and-protocol.md をお読みください。
10. ブラウザーでの作業を終える前に、open-browser-use finalize-tabs --session-id "$OBU_SESSION_ID" --keep '<json-array>'、MCP の finalize_tabs ツール、または SDK の finalizeTabs ／ finalize_tabs ／ FinalizeTabs メソッドを使って、セッションのタブを解放するか、維持してください。
11. セットアップ後に通信に失敗した場合は、references/troubleshooting.md をお読みください。

運用ルール

• ブラウザーはユーザーの実際の Chrome プロファイルとして扱ってください。Cookie、パスワード、セッションストア、または無関係なブラウザーデータを調べないでください。
• 拡張機能のインストール、ユーザーに代わって Chrome を開くこと、拡張機能の権限の有効化、ローカルファイルのアップロード、クリップボードデータの読み取り／書き込み、フォームの送信、購入、削除、送信、またはその他の外部から見える変更を行う前に、ユーザーに確認してください。
• Codex.app ヘルパー、Node REPL グローバル、またはバンドルされたプラグイン UI が利用可能だと想定しないでください。インストール済みの open-browser-use / obu CLI または公開されている SDK を使用してください。
• タブ ID を推測しないでください。まずタブを一覧表示し、tabs、user-tabs、open-tab、または SDK 呼び出しから返された ID を使用してください。
• 既存のユーザータブには、claim-tab / claimUserTab を優先して使用してください。Claim は現在の user-tabs の結果と、URL、タイトル、最近使用された時刻、グループなどの目に見える根拠に基づいて行ってください。
• フォローアップタスクでは、タブを開く前に user-tabs を確認し、✅ Open Browser Use または以前の引き継ぎグループにある該当タブを再利用してください。成果物のタブが引き続きユーザー向けの結果である場合は、新しいタスクセッションに再度 Claim して作業し、再び deliverable として確定できます。これにより、同じページで作業を繰り返す際に、1 つのライブタブに集約できます。
• ✅ Open Browser Use にあるという理由だけで、無関係な成果物タブを Claim しないでください。該当する可能性のあるタブが複数ある場合は、URL またはタイトルが完全に一致する最も新しいタブを優先し、該当タブを特定できない場合はユーザーに確認してください。
• ローカルのコード変更を検証または受け入れる際は、新しいタブを開くよりも、ユーザーがすでに開いている開発サーバーのタブ（localhost:<port> など、ホスト、ポート、アプリが一致するもの）の再利用を優先してください。ホスト、ポート、パスまたはタイトルで一致するタブを探してください。該当する可能性のあるタブが複数ある場合、または一致を特定できない場合は、重複タブを開かずにユーザーに確認してください。
• ユーザーまたはランタイムから明示的にソケットが提供された場合にのみ --socket を使用してください。それ以外の場合は、CLI と SDK によるアクティブなソケットレジストリの検出に任せてください。
• エージェントのタスクで CLI のフォールバックセッション obu-cli に依存しないでください。CLI および MCP コマンドには、タスクごとに一意の --session-id を必ず渡すか、SDK クライアントで sessionId / session_id / SessionID を設定してください。フォールバックは手動での簡易利用向けであり、無関係なエージェントセッション間で古いタスクグループを再利用する可能性があります。
• 直接の CLI サブコマンドと open-browser-use run が同じブラウザーセッションを共有できるのは、同じ明示的な --session-id を使用した場合のみです。ブラウザーでの作業を終了する前に、同じセッションを確定してください。
• より安全な便利コマンドや SDK ラッパーが存在しない場合にのみ、call --method <method> --params '<json>' を使用してください。

ブラウザーとプロファイルの扱い

複数の対応ブラウザー（Google Chrome、Google Chrome Beta、BitBrowser など）を使っているユーザーや、各ブラウザー内に複数のプロファイルを持つユーザーもいます。インストール済みのターゲットは、ブラウザー／プロファイルが閉じていても表示されます。そのため、このタスクをどのターゲットで実行するかユーザーに確認する必要があるかどうかは、インストール済みターゲットの数ではなく、CONNECTED の状態を基準に判断してください。

1. ブラウザーのコマンドを実行する前に、インストール済みのブラウザー／プロファイルのターゲットを一覧表示します。

   open-browser-use profiles --connected
   

   列には BROWSER、DIRECTORY（Default、Profile 1 などの安定したプロファイル ID）、DISPLAY NAME（ブラウザーのアバターメニューに表示される名前）、VERSION、CONNECTED（そのターゲットのホストに現在接続できるかどうか）が含まれます。JSON 出力は --json で利用でき、chrome:Default、chrome-beta:Default、bitbrowser:<instance>:Default などの安定した target が含まれます。

2. ユーザーがすでにブラウザー／プロファイルを指定している場合は、そのターゲットを使用します。接続されていない場合は、再試行する前にユーザーに開いてもらうよう依頼してください。別の接続済みターゲットへ黙って切り替えてはいけません。

3. ユーザーがターゲットを指定していない場合は、接続済みのターゲット数を数えます。ターゲットがちょうど 1 つ接続されている場合は、ほかのインストール済みターゲットが切断状態で一覧表示されていても、確認せずに続行します。以降のコマンドには、その接続済みターゲットのセレクターを渡し、タスク中に対象が変わらないようにします。

4. 複数のターゲットが接続されている場合は、最初のブラウザーコマンドを実行する前に、どれを使用するかユーザーに確認してください。ユーザーが判別できるよう、接続済みターゲットごとにブラウザー名、ディレクトリ名、表示名を列挙します。

5. 接続済みのターゲットがない場合は、ブラウザーコマンドを実行する前に、いずれかを開いてもらうようユーザーに依頼してください。インストール済みターゲットが複数ある場合は、どのターゲットを開くか確認します。ちょうど 1 つの場合は、その名前を直接伝えます。インストール済みのターゲットがない場合は、インストール手順に従います。

6. ターゲットを選択したら、タスクの残りの CLI／MCP コマンドすべてに --browser <selector> を渡し、必要に応じて --profile <selector> も渡します。ブラウザーセレクターには、chrome、chrome-beta、bitbrowser などの ID、ブラウザーの表示名、BitBrowser のインスタンス ID を指定できます。プロファイルセレクターには、ディレクトリ名（Default、Profile 1）または表示名（Eva、cookiy.com）を指定できます。大文字と小文字は区別されません。タスクの途中でブラウザー／プロファイルを切り替えてはいけません。

7. --browser／--profile が実行中のホストに一致しない場合、CLI は現在接続されているターゲットを表示します。選択したブラウザー／プロファイルを開いてもらうようユーザーに依頼してから再試行してください。別のターゲットへ黙って切り替えてはいけません。

8. MCP の場合は、サーバーの起動時にブラウザー／プロファイルを固定します。

   [mcp_servers.open_browser_use]
   command = "obu"
   args = ["mcp", "--session-id", "obu-<task-id>", "--browser", "<browser>", "--profile", "<profile>"]
   

   ツール呼び出しごとの引数としてブラウザー／プロファイルを渡してはいけません。MCP サーバーは、起動時に指定されたセレクターをすべての呼び出しに適用します。

9. 無関係な別のタスクに、ユーザーのブラウザー／プロファイルの選択を引き継いではいけません。今後のタスクでは別のターゲットを使う可能性があるため、推測せずに再度確認してください。

よく使う CLI アクション

export OBU_SESSION_ID="obu-docs-scan-$(date +%Y%m%d%H%M%S)"
open-browser-use ping --session-id "$OBU_SESSION_ID"
open-browser-use info --session-id "$OBU_SESSION_ID"
open-browser-use name-session --session-id "$OBU_SESSION_ID" --name "Task - OBU"
open-browser-use tabs --session-id "$OBU_SESSION_ID"
open-browser-use user-tabs --session-id "$OBU_SESSION_ID"
open-browser-use history --session-id "$OBU_SESSION_ID" --query "example" --limit 20
open-browser-use open-tab --session-id "$OBU_SESSION_ID" --url https://example.com
open-browser-use navigate --session-id "$OBU_SESSION_ID" --tab-id <tab-id> --url https://example.com
open-browser-use cdp --session-id "$OBU_SESSION_ID" --tab-id <tab-id> --method Runtime.evaluate --params '{"expression":"document.title"}'
open-browser-use finalize-tabs --session-id "$OBU_SESSION_ID" --keep '[]'

SDK コードを書かずに CLI レベルでオーケストレーションする場合は、行指向のアクションプランを使用します。

open-browser-use run --session-id "$OBU_SESSION_ID" -c '
name-session "Docs scan - OBU"
open-tab https://docs.browser-use.com
wait-load domcontentloaded
page-info
finalize-tabs []
'

各アクション行は、1 つのセッション／ターンを共有します。open-tab と claim-tab は、wait-load、page-info、navigate、cdp、move-mouse、wait-file-chooser など、以降のタブを対象とするアクションで使うデフォルトのタブを設定します。

利用可能な場合は、短縮エイリアスとして obu を使用します。

MCP の使用方法

標準入出力経由でローカル MCP サーバーを起動できるランタイムでは、次を使用します。

[mcp_servers.open_browser_use]
command = "obu"
args = ["mcp", "--session-id", "obu-<task-or-conversation-id>"]

エージェントのタスクや会話ごとに、新しい --session-id の値を使用します。ランタイムに固定の会話 ID／セッション ID がある場合は、そこから MCP の --session-id を導出します。

MCP サーバーは、user_tabs、open_tab、claim_tab、navigate、wait_load、page_info、cdp、history、run_action_plan、finalize_tabs、制限のない call などのツールを公開します。

ランタイムで、ブラウザー操作ごとに個別のシェルコマンドを実行せず、open-browser-use run で利用できるものと同じコンパクトなアクションプラン形式を実行する場合は、run_action_plan を使用します。

タブのライフサイクル

• セッションタブとは、現在のエージェントのワークフローのために Open Browser Use が作成または取得したタブです。
• エージェントのタスクまたは会話ごとに、一意のセッション ID を 1 つ使用してください。関係のないタスク間で、フォールバックの obu-cli セッションを共有しないでください。
• タスクのセッショングループには、<short task> - OBU のパターンを使い、タスク名を付けてください。フォールバック名には Task - OBU を使用します。
• 関連するフォローアップタスクの開始時には、作業を始める前にユーザーのタブをすべて一覧表示し、tabGroup、title、url を確認してください。既存の一致する成果物または引き継ぎ用のタブ、あるいはユーザーがすでに開いているローカル開発サーバーのページを、現在のセッションに取得してください。適切なタブがない場合にのみ、新しいタブを開いてください。
• デフォルトではタブを残さないでください：open-browser-use finalize-tabs --session-id "$OBU_SESSION_ID" --keep '[]'。
• ユーザーがターンの後もそのページを表示する必要がある場合にのみ、タブを残してください。必要な情報を取得したら、調査用、ソース用、検索用、中間作業用、重複、空白、エラー、ログイン／ナビゲーション用のタブは残さないでください。
• タブ自体がユーザー向けの出力または表示を依頼されたページである場合は、status: "deliverable" を指定して残してください。たとえば、作成または編集したドキュメント、ダッシュボード、チェックアウト／カート、送信済みフォームの結果、あるいはユーザーが直接確認するよう明示的に依頼したページが該当します。
• タスクがまだ進行中で、ユーザーまたは後続のターンが現在のタスクグループから続行する場合にのみ、status: "handoff" を指定してタブを残してください。たとえば、ユーザーの入力、ログイン、承認、支払い、CAPTCHA、または未完了のワークフローを待っているページが該当します。
• 引き継ぎ用のタブはタスクのセッショングループに残します。成果物のタブは共有の ✅ Open Browser Use タブグループに移動します。
• ターン中の Open Browser Use によるブラウザー操作は、最後にタブの最終処理を実行してください。最終処理後は Open Browser Use のブラウザーツールを呼び出さないでください。ブラウザー操作がさらに必要な場合は、先に済ませ、最後にタブの状態を確定してください。

ファイル選択、ダウンロード、クリップボード

• ファイルのアップロードには、割り込み型のファイル選択フローを使用します。まず待機を開始し、ページ上でファイル選択ダイアログを表示させてから、set-file-chooser-files または SDK の同等機能を使って絶対ローカルパスを指定します。
• ダウンロードは、SDK の通知ハンドラーや waitForDownload、downloadPath などの Browser Use のメソッドで確認できます。
• クリップボードのヘルパーは現在制御中のタブを通じて動作するため、機微なユーザー操作として扱ってください。

参考資料

• references/installation.md：CLI とブラウザー拡張機能の初回セットアップ。ユーザーの協力が必要な場合についても説明しています。
• references/sdk-and-protocol.md：JavaScript、Python、Go、ソケット、JSON-RPC の使用方法について説明しています。
• references/troubleshooting.md：接続エラー、古いソケット、拡張機能／ネイティブホストの確認、権限の問題について説明しています。