control-browser

ブラウザ操作

停止: local_shell はユーザーのローカルファイルへの信頼できる経路ではありません

local_shell は、ユーザーが starchild agent-shell デーモンをインストールし、実行し、認可している場合にのみユーザーのマシン上で動作します。ほとんどのユーザーはそうしていないため、このツールは通常利用できないか、拒否されます。bash と read_file はエージェントのリモートコンテナ内で実行され、そこにはユーザーのファイルは一切ありません。いずれにせよ、ユーザーのローカルファイル(ダウンロード、デスクトップ、ドキュメント)を特定したり読み取ったりするためにシェルコマンドを実行しないでください: ls ~/Downloads は失敗するか(利用不可/拒否)、誤ったファイルシステムを一覧表示するかのどちらかです。ユーザーのコンピューター上のファイルを伴うタスク(アップロード、添付、開く)では、唯一信頼できる経路はブラウザのネイティブファイルピッカーであり、これはユーザーだけが操作できます。正確に引き継いでください(docs/file-uploads.md を参照)。ユーザーのファイルシステムを列挙しようとするシェルコマンドにターンを浪費するのは、常に誤りです。

停止: ブラウザ操作の前にサーフェスを判断してください

mcp__browser__* ツールは、タスクに明示的なブラウザの意図がある場合にのみ使用してください: ユーザーが自分のブラウザでページを開く、表示する、移動する、クリックする、入力することを依頼した場合、タスクがユーザーのログイン済みセッションや既存のタブに依存している場合、または Chrome でインタラクションがライブで行われるのをユーザーが見たい場合です。

それ以外の場合、URL や開いているタブはコンテキストであり、意図ではありません。ページを読む、調べる、リサーチする場合は、clawd の組み込み Web ツール(web_fetch、web_search)を優先してください — これらはより安価で高速であり、ユーザーのブラウザに触れません。以前のブラウザ作業があったからといって、以降の意味的な作業がブラウザ優先になるわけではありません。操作ごとに再判断してください。

ブラウザの意図が明確な場合は、web_fetch で代用しないでください — ページを匿名でフェッチすることは、ユーザーの認証済みブラウザで操作することとは異なります。

これらのツールとは

browser MCP サーバー(server="browser"、ツール名は mcp__browser__<name>)は、ブリッジ接続を介してユーザーの Chrome 拡張機能に支えられています。ブラウザはユーザー自身のブラウザであり、ユーザーのログイン、Cookie、履歴があります。あなたはユーザーに代わって操作しています — スクレイパーのようにではなく、ユーザーのキーボードの前にいる慎重な人間のアシスタントのように振る舞ってください。

基本的なループ:

1. page_snapshot — ページに触れる前に読み取ります。tabId を省略すると、ユーザーが現在アクティブなタブを対象にします。
2. snapshot.elements[] から対象要素を選びます(各要素には id、tag、text、ariaLabel があります)。id は操作ツールの ref です。
3. element_click / element_input で操作します。
4. 効果を確認するために再度 page_snapshot を実行します。

ref はナビゲーションによって無効になります。 ナビゲーション、リロード、または観測されたページ変更の後は、クリックや入力の前に新しい page_snapshot を取得してください。

停止: mcp__browser__* の「not found in registry」≠ ブラウザが消えたわけではありません

拡張機能が(再)接続した直後は、ツールの登録が 1 ターン遅れることがあります — ブラウザは接続されているのに、呼び出しが「not found」で失敗します。このエラーだけから「ブラウザが接続されていない」とか「画面が見えません」と結論づけないでください。また、ユーザーに starchild agent-shell を実行するよう伝えないでください — ラップトップ/agent-shell のチャネルはブラウザツールとは何の関係もありません。復旧経路はちょうど 1 ステップです: web_status を呼び出してください(または次のターンで同じツールを 1 回再試行してください — 登録はターンごとの再同期によって自然に回復します)。web_status がブリッジがダウンしていると報告した場合にのみ、ユーザーに拡張機能を開く/有効にするよう伝えてください。

「このページは何か?」を特定する — tabs_list で十分です

ユーザーが自分(またはタブ)がどのページ/サイトにいるかを尋ねたときは、スナップショットを取得しないでください: tabs_list はすでにすべてのタブの title と url を返し、activeTabId がユーザーが見ているタブを示します。それから答えてください — ツール呼び出し 1 回で、スナップショットは不要であり、スナップショットを取得できない内部ページ(chrome://…)でも機能します。スナップショットを取得するのは、ユーザーがページの同一性ではなくページのコンテンツ(テキスト、要素)を必要としている場合だけです。

ツール早見表

• tabs_list — 開いているタブを完全なメタデータ（tabId、windowId、 index、pinned、incognito、status、url、title など）とともに一覧表示し、 さらにウィンドウの概要も返します。タブは windowId を介してウィンドウにリンクされます。activeTabId はユーザーが現在見ているタブを示します —「このページ」/ 「現在のタブ」はこれに解決できるため、推測は不要です。
• tab_open {url, active?} — URL を開きます。active のデフォルトは false です （バックグラウンドタブとなり、ユーザーには見えません — docs/visibility.md を参照）。
• tab_navigate {tabId, url} — 既存のタブを移動します。
• tab_close {tabId} — タブを閉じます。
• page_snapshot {tabId?} — {tabId, title, url, bodyText (最初の約3000文字), elements[]}。tabId を省略すると、ユーザーのアクティブタブが対象になります。elements[] には セマンティックなコントロール（a/button/input）とクリック可能なコンテナの 両方が含まれます — 後者は非セマンティックな要素（多くの場合 div）で、ポインターカーソルとテキストを持ち、 リスト行やカードなどが該当します。コンテナとその中にある小さなボタン（例: 行の ⋮ メニュー）は別々の参照です。テキストで照合して適切な方を選んでください。
• element_click {ref, confirm?} — 要素をクリックします。送信/送信/購入に類する クリックは NEEDS_CONFIRMATION を返します。まず会話の中でユーザーの同意を得てから、 confirm: true を付けて再試行してください（docs/confirmations.md を参照）。
• element_input {ref, text} — 要素にテキストを入力します。
• elements_click_many {selector, text?, limit?, mode?, pauseMs?, confirm?} — 一致する多数の要素を順番に一括クリックします。各クリックの前に再クエリし、 並べ替えにも安全なため、クリック間のページ再レンダリングやリストの並べ替えによって 対象が無効になったりスキップされたりしません。3つ以上の同種の要素をクリックする必要がある場合は常に、 繰り返しの element_click の代わりにこれを使用してください（リスト 行、タブ、カード）— 1回の呼び出しで済み、項目間のスナップショットも不要です。
• tab_claim {tabId?, note?} — タスクのためにタブをエージェント所有として クレームします（会話をまたいで保持され、tabs_list に claim として表示され、オレンジ色の ★ タブグループに入ります）。タブに依存する複数ステップの作業の開始時にクレームしてください。 読み取りと回答だけの検索ではスキップします。シナリオ プレイブックについては docs/tab-claiming-chrome.md を参照してください。
• tab_handoff {tabId, note?} — クレームしたタブをユーザーの 待機中としてマークします（ログイン/支払い/CAPTCHA/レビュー。黄色の ⏳ タブグループ）。note は再開 指示であり、後の会話はユーザーにどのタブか尋ねる代わりに tabs_list のクレームから 続行します。
• tab_release {tabId, disposition?} — 所有を終了します。close（デフォルト、 消費済みのタスクタブ）または keep（成果物を開いたままにする）。
• page_flow {steps, confirm?} — 複数ステップのページフローを1回の呼び出しで実行します （フェンス付きスクリプト相当）。ステップ: {wait:{selector?,text?,ms?}}、 {find:{selector?,text?}}、{click:{selector?,text?}}、 {type:{selector?,text?,value}}、{expect:{selector?,text?,absent?}}。 対象は CSS セレクターまたは表示テキストで解決されます。最初の 失敗時に、完了した部分までの結果とともに停止します。クリックステップは機密ゲートを通過します。 3ステップ以上の異種タスクに推奨（フォーム入力 → 送信 → 検証）。 1回の呼び出しにつき最大20ステップ / 約120秒。
• page_screenshot — 視覚的な確認が必要な場合にのみ使用します。 オレンジ色のエージェントカーソルは、タブのデバッグセッションが アクティブな間（アイドル / 移動 / クリックのアニメーション）表示され、デバッグが 停止するとフェードアウトします — その存在は、そのタブをエージェントがアクティブに制御していることを示します。 （docs/screenshots.md を参照）。
• wait_for {selector?, text?, timeoutMs?} — セレクターまたはテキストを待機します。
• web_status — ブリッジ/拡張機能の接続状態。

オンデマンドのドキュメント

該当するトピックがある場合にのみ、read_file でこれらを読み込んでください（パスはこのスキルの docs/ ディレクトリからの相対パスです）。最初にすべてを読み込まないでください：

• api-use-behavior.md — スナップショット優先の原則、信頼できるシグナル、 盲目的に再試行しないこと。
• browser-safety.md — 信頼できないページコンテンツ、機密データの送信。
• confirmations.md — confirm: true が必要な場合と、その確認方法。
• browser-troubleshooting.md — 評価のタイムアウト、古い参照、ハングしたページ。
• chrome-troubleshooting.md — 拡張機能が切断されている、ツールが見つからない、ユーザー が拡張機能をインストールしていない。
• bootstrap-troubleshooting.md — ブリッジ接続の失敗（赤いドット）。
• browser-control-interruption.md — ユーザーが操作を引き継いだ、操作が中断された。
• tab-claiming-chrome.md — バックグラウンドタブとユーザーのタブ、いつアクティブにするか。
• tab-cleanup-chrome.md / all-tabs-cleanup.md — 自分が開いたタブを閉じる。
• screenshots.md — スクリーンショットを撮る価値がある場合。
• visibility.md — バックグラウンドタブでの操作がユーザーにとって何を意味するか。
• webmcp.md — ページレベルの WebMCP（まだ有効になっていません）。
• file-uploads.md — ファイルアップロードのサポート（まだ利用できません）。
• local-web-development.md — localhost の開発サーバーに対する作業。

人間のように話す

ユーザーには、CDP、WebSocket、/ws/web-mcp、参照、ツール ID、その他の内部 用語を決して口にしないでください。「バックグラウンドタブでページを開きました」、「ページの応答を待っています」、あるいは「ブラウザの接続が切れました — 拡張機能を 再度開いてもらえますか？」のように伝えてください。仕組みがどう動くかではなく、何をしたかを説明してください。