opencli-browser

この CLI の最初の読み手はヒトではなくエージェントです。すべてのサブコマンドは構造化されたエンベロープを返し、何にマッチしたか、マッチの信頼度はどのくらいか、マッチしなかった場合は何をすべきかを正確に伝えます。これらのエンベロープを活用してください — 推測はしないでください。

このスキルは、エージェントタスクを達成するためにライブブラウザを操作するためのものです。~/.opencli/clis/<site>/ の下で再利用可能なアダプターを構築している場合は、代わりに opencli-adapter-author を使用してください。

---

前提条件

opencli doctor

doctor が緑になるまで、他には何も機能しません。一般的な失敗: Chrome が実行されていない、拡張機能がインストールされていない、デバッグポートが 1Password / 他の拡張機能によってブロックされています。doctor の出力はどちらかを教えてくれます。

---

セッションライフサイクル

• opencli browser * コマンドは browser の直後に <session> ポジショナル引数を必要とします。複数ステップのフローに同じセッション名を使用し、並列ブラウザ作業を分離するために異なる名前を使用してください。
• マルチコマンドまたはヒト主導のブラウザワークフローには安定したセッション名を使用してください。例: opencli browser fb-yaya-warmup open https://example.com、その後 opencli browser fb-yaya-warmup state、extract、click などを再利用します。
• 所有されたブラウザセッションは呼び出し間でタブリースを生きたままにします。opencli browser <session> close でリリースするか、アイドルタイムアウトの期限切れを待ちます。
• opencli browser <session> bind はすでに開いている Chrome タブをそのセッションにバインドします。ログイン済みページ、SSO フロー、またはエージェントに制御を渡す前に手動で配置したページに使用してください。
• --window foreground|background（または OPENCLI_WINDOW=foreground|background）は、OpenCLI が所有されたセッション用のフォアグラウンドブラウザウィンドウを作成/フォーカスするか、バックグラウンドブラウザウィンドウを使用するかを選択します。

バインドタブ

opencli browser gmail bind
opencli browser gmail state
opencli browser gmail click "Search"
opencli browser gmail network
opencli browser gmail unbind

バインディングはユーザーウィンドウを所有することなく、ユーザータブを閉じることもありません。タブが閉じられるか、デバッグ不可になった場合は失敗します。異なる実際のタブに切り替えるときは opencli browser <session> bind を再実行してください。

バインドされたセッションではナビゲーションが許可されています。セッションが現在そのタブの明示的なエージェント所有を表しているためです。タブミューテーション（tab new、tab select、tab close）はバインドされたセッション用でもブロックされています。OpenCLI にタブライフサイクルを管理させたい場合は、所有されたセッションを使用してください。

バインドされたセッションには OpenCLI アイドルクローズタイマーがありません。バインディングは unbind、タブクローズ、ウィンドウクローズ、またはデーモン再起動まで続きます。

---

メンタルモデル

1. セレクタ優先のターゲットコントラクト。 すべてのインタラクションコマンド（click、type、select、get text/value/attributes）は 1 つの <target> を取ります。これは state/find からの数値参照 または CSS セレクタです。複数の CSS マッチを明確にするには --nth <n> を使用してください。
2. すべてのエンベロープが matches_n と match_level をレポート します。 match_level は exact、stable、または reidentified です — CLI はすでに適度な DOM ドリフトから復帰しましたが、このレベルは信頼度を示しています。
3. コンパクト出力第一、詳細ペイロードはオンデマンド。 state は予算対応スナップショット; get html --as json は --depth/--children-max/--text-max をサポート; network は形状プレビューを返し、単一ボディを --detail <key> で再フェッチします。巨大なペイロードを出力すると、不要なコンテキストを焼いています。
4. 構造化エラーはマシン可読。 失敗時、CLI は {error: {code, message, hint?, candidates?}} を発します。メッセージ文字列ではなく code で分岐してください。

---

重要なルール

1. 常に行動する前に検査してください。 最初に state または find を実行してください。メモリ全体からセッション間でハードコードされた参照またはセレクタを決してしないでください — インデックスはスナップショットごとです。
2. 生のブラウザ駆動の前にサイトアダプターを優先してください。 opencli <site> <command> がすでにタスクをカバーしている場合は、最初にそのアダプターコマンドを使用してください（opencli facebook notifications、opencli reddit read など）。opencli browser ... はギャップ、デバッグ、またはアダプターが公開していないワンオフ UI フロー用のみです。
3. 一度数値参照を取得したら CSS より数値参照を優先してください。 数値参照は CLI が各タグ付き要素に指紋を付けるため、穏やかな DOM シフトから生き残ります。手で書かれた CSS セレクタはサイトが再レンダリングするたびに最初に壊れます。
4. すべての書き込み後に match_level を読んでください。 exact = すべてよし。stable = 要素は同じですが、いくつかのソフト属性がドリフトしました — アクションは依然として適用されました。reidentified = 元の参照は消えて、CLI は一意の置換を見つけました。正しい要素をヒットしたことを再確認してください。
5. フォームコントロール用に compound フィールドを使用してください。 日付形式を正規表現で推測しないでください、完全な <select> オプションリストを取得するために state を 2 回実行しないでください。複合エンベロープには形式文字列、最大 50 のフルオプションリスト、オーバーフロー用の options_total、および <input type=file> 用の accept/multiple があります。
6. 重要な書き込みを検証してください。 type <target> <text> の後、get value <target> を実行してください。select の後、get value を実行してください。オートコンプリートウィジェット、React 制御入力、およびマスクされたフィールドはすべてサイレントに文字を食べます。CLI はこれを検出できません。
7. ページ変更後 state → アクション → state。 ナビゲーション、フォーム送信、および SPA ルート変更は参照を無効にします。新しいスナップショットを取得してください。遷移前の参照を再利用しないでください。
8. 新しく解析された参照を再利用するときは && でチェーンしてください。 チェーンされたシーケンスは 1 つのシェルで実行されるため、出力から読んだばかりの参照を次のコマンドに直接渡すことができます。別々のシェル呼び出しは名前付きブラウザセッションを保ちますが、前のコマンドからのシェルローカル変数またはコピーされた参照はページ変更後に古くなる可能性があります。
9. eval は読み取り専用。 JS を IIFE でラップして JSON を返してください。ページを 変更 する必要がある場合は、代わりに構造化 click / type / select / keys コマンドを使用してください — 構造化出力と指紋を生成し、eval はそうしません。
10. スクリーンスクレイピングより network を優先してください。 あなたが気にするページが JSON API からデータを取得する場合、API はほぼ常にレンダリングされた DOM をスクレイピングするより信頼性があります。一度キャプチャして形状を検査し、その後必要なボディを --detail <key> で再フェッチします。

---

ターゲットコントラクト（click / type / select / get text|value|attributes 用の <target>）

<target> ::= <numeric-ref> | <css-selector>

• 数値参照 — state または find からの [N] インデックス。安価で、穏やかな DOM ドリフトに耐性があります。
• CSS セレクタ — querySelectorAll が受け入れるもの。書き込み操作では明確である必要があります。明確でない場合は --nth <n> とペアにしてください。

成功時のエンベロープ

{ "clicked": true, "target": "3", "matches_n": 1, "match_level": "exact" }

{ "value": "kalevin@example.com", "matches_n": 1, "match_level": "stable" }

match_level

level	意味	対応
exact	指紋がタグ + 強 ID と一致、最大 1 つのソフトドリフト	続行してください。
stable	タグ + 強 ID がまだ一致、ソフト信号（aria-label、role、text）がドリフト	続行してください。ただし、入力/クリック した内容 が重要な場合は、get value または state で再確認してください。
reidentified	元の参照が消えた。一意のライブ要素が指紋と一致し、古い参照で再タグ付けされた	続行する前に正しい要素をヒットしたことを再確認してください。

構造化エラーコード

ヒト向けメッセージではなく、これらで分岐してください:

code	意味
not_found	数値参照が DOM にもはや存在しません。state を再実行してください。
stale_ref	参照は存在しますが、その参照の要素は同一性が変わりました。state を再実行してください。
invalid_selector	CSS が querySelectorAll に拒否されました。セレクタを修正してください。
selector_not_found	CSS が 0 要素にマッチします。より広いセレクタで find を試してください。
selector_ambiguous	CSS が >1 にマッチし、--nth がありません。--nth を追加するか、セレクタを絞ってください。
selector_nth_out_of_range	--nth がマッチ数を超えています。
option_not_found	select がそのラベル/値にマッチするオプションを見つけられませんでした。エラーエンベロープは実オプションラベルの available: string[] を含みます。
not_a_select	select が非 <select> 要素で呼ばれました。

エラーエンベロープは常に error.code と error.message を含みます。ターゲットエラー（selector_not_found、selector_ambiguous など）はしばしば提案セレクタ付きの error.candidates: string[] を追加します。option_not_found は代わりに error.available: string[] を追加します。

---

コマンドリファレンス

検査

コマンド	目的
browser state	スナップショット: [N] 参照を含むテキストツリー、スクロールヒント、隠された対話的ヒント、日付/select/ファイル参照用 compounds (N): サイドカー。
browser state --source ax	オプトイン アクセシビリティツリースナップショット。カスタムコントロール、ポータル、または iframe コンテンツが通常の state で特定しにくい場合に使用してください。AX 参照は穏やかな React 再レンダリングをロール/名前/nth で復帰でき、同一オリジン iframe 参照をルーティングできます。Chrome が拡張機能に添付可能 OOPIF ターゲットを公開しないため、クロスオリジン iframe 参照はベストエフォートです。
browser state --compare-sources	メトリクスのみ DOM vs AX 比較。AX がデフォルトになるべきかを決定するためのもの。ページテキストではなくカウントとサイズを印刷するため、検証共有がより安全です。
browser find --css <sel> [--limit N] [--text-max N]	CSS クエリを実行し、{nth, ref, tag, role, text, attrs, visible, compound?} を含む マッチごとに 1 エントリを返します。前のスナップショットがタグ付けしなかったマッチの参照を割り当てます。セレクタをすでに知っている場合、state への廉価な代替。
browser find --role button --name Save	セマンティックロケータクエリ。--label、--text、--testid もサポート。生の CSS を使用する前に使用してください。コントロールがアクセシブルラベルを持つ場合に使用してください。
browser frames	クロスオリジン iframe ターゲットをリスト化。インデックスを eval の --frame に渡してください。
browser screenshot [path]	ビューポート PNG。パスなし → stdout へ base64。構造が必要な場合は state を優先してください。
browser screenshot --annotate [path]	ビジュアル参照マップ。DOM 参照を更新し、見える [N] ラベルをオーバーレイするため、スクリーンショットは browser click <ref> ターゲットにマップバックします。アイコンのみコントロール、ビジュアルレイアウト、チャート、またはテキスト状態があいまいな場合に使用してください。

取得（読み取り専用）

コマンド	返却値
browser get title	プレーンテキスト
browser get url	プレーンテキスト
browser get text <target> [--nth N]	{value, matches_n, match_level}
browser get value <target> [--nth N]	{value, matches_n, match_level}
browser get attributes <target> [--nth N]	{value: {attr: val, ...}, matches_n, match_level}
browser get text --role option --name Travel	前の state 呼び出しなしセマンティックロケータ読み取り。browser find と同じフラグ。
browser get html [--selector <css>] [--as html|json] [--depth N] [--children-max N] [--text-max N] [--max N]	生 HTML、または構造化ツリー。JSON ツリーノードは {tag, attrs, text, children[], compound?} を持ちます。切り詰めは truncated: {depth?, children_dropped?, text_truncated?} でレポートされます。

インタラクト

コマンド	注記
browser click <target> [--nth N]	{clicked, target, matches_n, match_level} を返します。
browser click --role button --name Submit	セマンティッククリック。書き込みアクション は一意のマッチを必要とします。あいまいなロケータは最初のマッチをクリックする代わりに候補を返します。
browser hover [target] [--role R --name N] [--nth N]	マウスを要素上に移動します。state またはサブメニュー項目のクリック前にホバーメニュー/ツールチップに使用してください。{hovered, target, matches_n, match_level} を返します。
browser focus [target] [--role R --name N] [--nth N]	入力なしで要素にフォーカスします。keys 前またはページがフォーカス/ぼかしに反応するときに有用。{focused, target, matches_n, match_level} を返します。
browser dblclick [target] [--role R --name N] [--nth N]	利用可能な場合、ネイティブマウスイベント経由で要素をダブルクリック。{dblclicked, target, matches_n, match_level} を返します。
browser check [target] [--role R --name N] [--nth N]	チェックボックス/ラジオ/aria-checked コントロールがチェックされていることを確認。{checked, changed, target, matches_n, match_level, kind} を返します。ターゲット状態が重要な場合、ブラインド click より優先してください。
browser uncheck [target] [--role R --name N] [--nth N]	チェックボックス/aria-checked コントロールがチェックされていないことを確認。ラジオボタンは直接チェック解除できません。グループ内の別のラジオを選択してください。
browser upload [target] <file...> [--role R --name N] [--nth N]	ローカルファイルパス を CDP 経由で input[type=file] に添付。セマンティックフラグで、target を省略し、ファイルをポジショナルとして渡してください。{uploaded, files, file_names, target, matches_n, match_level, multiple?, accept?} を返します。
browser drag [source] [target] [--from-role R --from-name N] [--to-role R --to-name N] [--from-nth N] [--to-nth N]	1 つの解決された要素の中心から別の要素へのマウスベースドラッグ。マウスリスナードラッグライブラリで機能; ネイティブ HTML5 dataTransfer ドロップはサイト固有のフォールバックが必要な場合があります。{dragged, source, target, source_matches_n, target_matches_n, ...} を返します。
browser type [target] <text> [--role R --name N] [--nth N]	クリック後、テキスト入力。セマンティックフラグで、target を省略し、テキストを唯一のポジショナルとして渡してください。{typed, text, target, matches_n, match_level, autocomplete} を返します。autocomplete: true は コンボボックス/datalist ポップアップが入力後に表示されたことを意味します — 値をコミットするには keys Enter またはフォローアップ click がほぼ常に必要です。
browser fill [target] <text> [--role R --name N] [--nth N]	input、textarea、contenteditable ターゲット用の正確な置換。セマンティックフラグで、target を省略し、テキストを唯一のポジショナルとして渡してください。{filled, verified, text, actual, matches_n, match_level} を返します。キーボード/オートコンプリート動作ではなく、生テキストセット検証が必要な場合に使用してください。パイプラインフォーム { fill: { ref, text, submit: true } } をサポート。
browser select [target] <option> [--role R --name N] [--nth N]	ネイティブ <select> オプションをラベル優先、次に値でマッチ。セマンティックフラグで、target を省略し、オプションを唯一のポジショナルとして渡してください。find/state から compound を使用して、利用可能なラベルが正確に何かを見てください。
browser keys <key>	Enter、Escape、Tab、Control+a など。フォーカスされた要素に対して実行。
browser scroll <direction> [--amount px]	up / down。デフォルト量 500。

待機

browser wait selector "<css>" [--timeout ms]    # セレクタがマッチするまで待機
browser wait text "<substring>" [--timeout ms]  # テキストが表示されるまで待機
browser wait download [pattern] [--timeout ms]  # ファイル名/URL/mime が pattern を含む Chrome ダウンロードを待機
browser wait time <seconds>                     # ハードスリープ、最後の手段

デフォルトタイムアウト 10000 ms。SPA ルート、ログインリダイレクト、遅延ロードリストは state/get 前に wait を必要とします。

browser wait download は Chrome のダウンロードライフサイクル API を使用するため Browser Bridge 拡張機能 1.0.8+ が必要です。receipt.pdf のような狭いファイル名または URL サブストリングを渡してください; 空のパターンはタイムアウトウィンドウ内の次/最近のダウンロードを待機します。コマンドは成功時に {downloaded, filename, url, state, elapsedMs} をレポートし、タイムアウト/失敗時に JSON エラーエンベロープを返します。

抽出

• web read --url <url> — 任意のページ用のワンショット Markdown リーダー。関連する同一オリジン iframe をデフォルトで拡張するため、古い iframe シェルサイトはトップドキュメント専用スクレイプより良く機能します。完全性が Markdown ノイズより重要な場合、--frames all-same-origin を使用してください。AJAX シェルページの場合、opencli web read --url <url> --wait-for "<selector>" --wait-until networkidle --diagnose を使用してください; 診断はフレーム URL、空のコンテナ、API 風 XHR を表示します。必要な値がテーブル/API データの場合、Markdown 依存の代わりに専用アダプターまたは browser network に切り替えてください。
• browser eval <js> [--frame N] — ページ内（または --frame 経由でクロスオリジンフレーム内）で式を実行。IIFE でラップして JSON を返してください。読み取り専用: document.forms[0].submit()、クリック、ナビゲーションなし。結果が文字列の場合、stdout は生文字列; そうでない場合は JSON。
• browser extract [--selector <css>] [--chunk-size N] [--start N] — 継続カーソル付きの長形式コンテンツの Markdown 抽出。{url, title, selector, total_chars, chunk_size, start, end, next_start_char, content} を返します。next_start_char が null になるまで next_start_char でループ。セレクタを渡さない場合、<main>/<article>/<body> に自動スコープ。

ネットワーク

browser network                        # 形状プレビュー + キャッシュキーリスト
browser network --detail <key>         # 1 つのキャッシュエントリの完全ボディ
browser network --filter "field1,field2"  # すべてのパス セグメント として field1,field2 を含むボディ形状を持つエントリのみ保持
browser network --all                  # 静的リソースを含む（通常ノイズ）
browser network --raw                  # 完全ボディインライン — 大きい; 控えめに使用
browser network --ttl <ms>             # キャッシュ TTL（デフォルト 24h）

リストエントリは {key, method, status, url, ct, size, shape, body_truncated?} のよう。詳細エンベロープは {key, url, method, status, ct, size, shape, body, body_truncated?, body_full_size?, body_truncation_reason}。キャッシュは ~/.opencli/cache/browser-network/ に存在するため、リクエストを再トリガーせずに再検査できます。

デフォルト出力は JSON/XML/プレーンテキストと JS 風 API 応答を保持し、その後明白な静的アセットとテレメトリを URL でドロップ。予期されたエンドポイントが見つからない場合、一度 browser network --all を実行し、異常なコンテンツタイプまたは URL フィルタがそれを隠しているかチェック。

タブ & セッション

コマンド	目的
browser tab list	{index, page, url, title, active} の JSON 配列。page 文字列は tab select / tab close へ <targetId> として渡すタブ同一性、または任意のサブコマンド上の --tab <targetId> へ。（--tab のプレースホルダは歴史的 — 値は常に page。）
browser tab new [url]	新しいタブを開く。新しい page 文字列を印刷。
browser tab select [targetId]	タブをデフォルトにします。すべてのサブコマンドはデフォルト変更せずに 1 つをターゲットするために --tab <targetId> を受け入れます。
browser tab close [targetId]	page でクローズ。
browser back	アクティブなタブで履歴バックを実行。
browser close	完了時に現在の所有されたブラウザセッションをリリース。
browser <session> bind	現在の Chrome タブを名前付きブラウザセッションにバインド。
browser <session> unbind	ユーザータブ/ウィンドウを閉じずに名前付きバウンドセッションをデタッチ。

---

複合フォームコントロール

すべての日付/時間、select、ファイル入力は compound フィールドを持ちます。これを使用してください — 属性を正規表現で推測しないでください。

日付ファミリー

{
  "control": "date",
  "format": "YYYY-MM-DD",
  "current": "2026-04-21",
  "min": "2026-01-01",
  "max": "2026-12-31"
}

control は date | time | datetime-local | month | week のいずれか。format は具体的なテンプレート文字列 — その正確な形式を使用してフィールドに入力するか、サイトが native 入力をカスタムウィジェットでラップする場合は select ラベルを使用してください。

Select

{
  "control": "select",
  "multiple": false,
  "current": "United States",
  "options": [
    { "label": "United States", "value": "us", "selected": true },
    { "label": "Canada", "value": "ca" }
  ],
  "options_total": 137
}

options[] は 50 エントリで制限されます。current は常に正しい — 選択されたオプションがキャップを超えている場合でも、切り詰められたリストではなくすべてのオプションをスキャンして計算されます。options_total > options.length で、options[] にないオプションが必要な場合、browser select <target> "<label>" を直接呼び出してください — CLI は切り詰められたリストではなくライブ DOM と照合します。

ファイル

{
  "control": "file",
  "multiple": true,
  "current": ["report.pdf", "cover.png"],
  "accept": "application/pdf,image/*"
}

ファイルパスを発明しないでください。アップロードは通常クリックフロー経由で実行されます — ユーザーに何をアップロードすべきか伝えるときは accept を尊重してください。

複合体がどこに表示されるか

• browser find --css <sel> エントリ: 各マッチ上でインライン。
• browser get html --as json ツリーノード: マッチするノード上でインライン。
• browser state スナップショット: 数値参照でキーになった compounds (N): サイドカー。一目で [N] エントリのどれが豊富なメタデータを持つかを見分けられます。

---

コストガイド

コール当たりのペイロードサイズについて考えてください。予算は理由のために存在します。

コマンド	粗コスト	いつ使用するか
state	中（内部予算で制限）	任意のページで最初のコール、すべてのナビゲーション後、参照が必要な場合。
find --css <sel>	小	セレクタをすでに知っています — 1 つクエリ、コンパクトエントリ。
get title / get url	極小	ステップ間の健全性チェック。
get text/value/attributes	コール当たり極小	1 つの特定フィールド検証。
get html (raw)	非常に大きい可能性	制限なしページで避ける。常に --selector と予算とペアにしてください。
get html --as json --depth 3 --children-max 20	中	特定フィールドではなく構造を理由にする必要がある場合。
screenshot	大	ページが視覚的な場合のみ（CAPTCHA、チャート）。state を優先。
extract	チャンクあたり中	長形式読み取り。next_start_char でループ。
network (デフォルト)	小	API への最初の見方。
network --detail <key>	異なる	1 つのボディをプル。
network --raw	非常に大きい	--filter が候補セットを絞った後のみ。
eval "JSON.stringify(...)"	制御された	上のいずれもフィットしない場合のターゲット抽出。

経験則: ページ遷移当たり 1 回 state、フォローアップクエリ当たり 1 回 find、アクション当たり 1 回 get/click/type。 あなたの計画がページあたり >10 コールを含む場合、おそらくインタラクトではなくスクレイピングしています — extract または network を検討してください。

---

チェーニングルール

良い — 1 シェル、ライブセッション:

opencli browser hn open "https://news.ycombinator.com" \
  && opencli browser hn state \
  && opencli browser hn click 3

悪い — 各行は新しいシェル、コール 1 の参照は コール 2 実行時にすでに忘れられています。 （シェルスコープ状態を依存する場合のみ問題; ブラウザ参照自体はページ内で永続しますが、関連のないシェル間隔はレースを招きます。）ステップが原子的だと意図された場合、&& を優先。

決して アクションがネットワークラウンドトリップを引き起こす場合、直後に state をチェーンしないでください — 応答前の DOM をスナップショットし、古いデータで悪い決定を下します。

---

レシピ

ログインフォームを入力

opencli browser login open "https://example.com/login"
opencli browser login state                          # メール、パスワード、送信の [N] を検索
opencli browser login type 4 "me@example.com"
opencli browser login type 5 "hunter2"
opencli browser login get value 4                    # 検証（オートコンプリートは文字を食べる可能性）
opencli browser login click 6                        # 送信
opencli browser login wait selector "[data-testid=account-menu]" --timeout 15000
opencli browser login state                          # ログイン済みページで新しい参照

長いドロップダウンから選択

opencli browser form state                          # サイドバーが [12] <select name=country> を表示
opencli browser form find --css "select[name=country]"
# compound.options_total は 137 ですが、compound.current は "" — 未選択。
opencli browser form select 12 "Uruguay"
opencli browser form get value 12                   # { value: "uy", match_level: "exact" }

カスタム React ドロップダウンから選択

これを Radix、shadcn、Material UI、Mercury スタイルカテゴリフィールド、および その他の native <select> ではないコントロール用に使用してください。

opencli browser mercury state                          # カテゴリトリガー参照を検索
# トリガー/オプションが明確でない場合、AX を使用:
opencli browser mercury state --source ax              # combobox/button/listbox/option 名を探す
opencli browser mercury click 7                        # カテゴリトリガーをクリック
opencli browser mercury state --source ax              # ポータル/リストボックス開放後、新しい参照
opencli browser mercury click 12                       # オプションをクリック
opencli browser mercury get text 7                     # 見える選択ラベルを検証

これらのウィジェット上で browser select を使用しないでください。browser select は native <select> 要素専用。カスタムドロップダウンは state -> click trigger -> state -> click option -> verify で駆動。

DOM vs AX 観測を比較

AX 参照がページに良いかを決定するとき、ページコンテンツを共有せずにメトリクス を収集してください:

opencli browser compare state --compare-sources

sources.dom.refs、sources.ax.refs、frame_sections、approx_tokens、elapsed_ms、および任意のソース当たり error をレポートしてください。AX がサイトのデフォルトになるべきと主張する前に これを使用してください。

ネットワークの代わりに DOM でリストをスクレイプ

opencli browser hn open "https://news.ycombinator.com"
opencli browser hn network --filter "title,score"
# -> /topstories エントリを検索、そのキーをメモ
opencli browser hn network --detail topstories-a1b2

長い記事をチャンクで読む

opencli browser article open "https://blog.example.com/long-post"
opencli browser article extract --chunk-size 8000
# -> content + next_start_char: 8000
opencli browser article extract --start 8000 --chunk-size 8000
# ...next_start_char が null になるまで

クロスオリジン iframe

opencli browser checkout frames
# -> [{"index": 0, "url": "https://checkout.stripe.com/...", ...}]
opencli browser checkout eval "(() => document.querySelector('input[name=cardnumber]')?.value)()" --frame 0

browser state --source ax は Chrome が拡張機能に添付可能 OOPIF ターゲットを公開しない場合、クロスオリジン iframe コンテンツを省略するか、アクションをそれらにルーティングできない可能性。その場合、browser frames + browser eval --frame、通常の DOM state、または可能な場合は iframe URL に直接ナビゲート/バインドを使用してください。

---

落とし穴

• eval "document.forms[0].submit()" 経由でフォームを送信しないでください — モダンサイト JS ハンドラでインターセプトし、サイレントにドロップ。参照経由で送信ボタンを click するか、（GET URL を知っている場合）単に直接 open してください。
• ページ遷移全体で参照を再利用しないでください。 新しい状態を wait し、再度 state。古い参照は 404 するか、（より悪い）新しいページ上の同様の形の要素に reidentify。
• match_level: reidentified はエラーではなく警告。 アクションは通りました、ただし 5 つ以上のさらなる書き込みすべてがそれが正しい要素であることに依存する場合、get text または get value で続行する前に検証してください。
• 予算対応コマンドはサイレントにキャップします。 get html --as json デフォルト予算で truncated: {...} を返します。ダウンストリームロジックが完全なサブツリーを必要とする場合、--depth / --children-max を上げるかセレクタを厳しくしてください。
• type 応答上の autocomplete: true はエラーではありません。 ポップアップ提案が開いて、値はコミットされていない。通常 keys Enter 最初の提案を受け入れるか、希望するものを click。
• network --filter は パス セグメント上の AND セマンティクス。 --filter "title,score" は本体形状が 両方の title と score パス セグメントを任意の深さで含むエントリを保持。正規表現ではありません。
• スクリーンショットはヒト用、エージェント用ではありません。 ページが本当に視覚的（captcha、チャート）でない限り、state + find を使用。スクリーンショットはトークンを焼き、エージェントが作用できるシグナルを追加することはほぼありません。

---

トラブルシューティング

症状	修正
opencli doctor 赤: "Browser not connected"	--remote-debugging-port=9222 で Chrome を開始するか、Chrome Web Store から拡張機能をインストール。
attach failed: chrome-extension://...	1Password / 他の CDP ハングリー拡張機能を一時的に無効。
selector_not_found state 直後	ページが変わった。wait selector "..." 後に再試行。
stale_ref すべてのコマンド全体	前ページからの参照を再利用している。state 再実行。
click 成功するがクリックは起こらない	要素はおそらく実クリック吸収装飾ラッパー。find --css "..." より狭いセレクタで再試行し、内側要素上で再試。
type 完了に見えるが値は間違い	オートコンプリート、マスク入力、または React 制御再レンダー。get value で検証。keys Enter または再入力を追加。
巨大 get html 出力	--selector + --as json --depth 3 --children-max 20 --text-max 200 を渡す。
ネットワークキャッシュが古い見え	--ttl を下げるか、期限切れを待つ。キャッシュは ~/.opencli/cache/browser-network/ に存在。

---

関連項目

• opencli-adapter-author — あなたが今解く ことを再利用可能 ~/.opencli/clis/<site>/<command>.js にする。
• opencli-autofix — 既存アダプターが壊れるとき、このスキル --trace retain-on-failure 証拠と修正ファイリングであなたを歩きます。