ブラウザ自動操作

ブラウザ自動操作 は何をしますか？

このスキルは、単一ページの確認を超えてbrowserツールが必要な場合に使用します。

操作ループ

1. アクションの前にブラウザ状態を確認：
   • openclaw browser doctor または action="status"：ブラウザやプラグインのセットアップ自体に問題がある可能性がある場合。
   • action="status"：利用可能性を確認。
   • action="profiles"：ログイン状態やプロファイルの選択が重要な場合。
   • action="tabs"：新しいタブを開く前に、リトライやタイムアウトでウィンドウが残っている可能性がある場合。
2. 安定したタブハンドルを優先：
   • 重要なタブは label で開く（例：label="meet"）。
   • action="tabs" または action="open" の後、suggestedTargetId を保存し、後続の呼び出しで targetId として渡す。
   • suggestedTargetId はラベルが存在する場合はラベル、そうでない場合は t1 のような安定した tabId ハンドル。
   • 生の DevTools targetId は即時診断以外では避ける。Chromium のターゲット置き換えにより変更される可能性がある。
3. クリックする前に読み取り：
   • 「ページを読んでXに答える」には、action="text" とオプションの selector および maxChars を使用（最初のセレクターマッチ、なければ article/main/body）。既存セッションプロファイルでは snapshot を代わりに使用。効率的なスナップショットはほとんどの散文を省略する。
   • 仮想化リストの場合、各セグメントをスクロールし、関連する行のみをキャプチャし、結果をマージする。
   • 目的の targetId に対して action="snapshot" を使用する。
   • スナップショットの query を追加して、すべてのクエリトークンを含む行（大文字小文字区別なし）を見つける。一致した行はその参照を保持する。
   • フォローアップアクションでも同じ targetId を使用し、参照が同じタブに留まるようにする。
   • 耐久性のある Playwright 参照の場合、サポートされていれば refs="aria" をリクエストする。snapshotFormat="aria" から axN 参照を受け取った場合、それらは同じスナップショット呼び出しの直後でのみ使用する。古くなった、またはバインドされていない axN 参照はすぐに失敗し、新しいスナップショットが必要になる。
   • リンクテキストがあいまいな場合、または直接ナビゲーションターゲットが脆弱なクリックを回避できる場合は、urls=true を使用する。
   • 視覚的な位置が重要な場合は、スナップショットまたはスクリーンショットで labels=true を使用する。Playwright ベースのプロファイルでは、レスポンスに annotations 配列（{ref, number, role, name?, box}）が含まれ、各参照のバウンディングボックスがキャプチャ画像の座標空間で提供されるため、再スナップショットせずに位置を推論できる。スクリーンショットラベルは fullPage=true（CLI: --full-page）と組み合わせてドキュメント全体にラベルを付けることも、ref / element で1つの要素にクリップすることもできる。profile="user" およびその他の既存セッション（chrome-mcp）プロファイルは、ページスクリーンショットにオーバーレイをレンダリングするが、annotations を添付したり、Playwright のフルページ/参照/要素投影ヘルパーを使用したりしないため、これらのプロファイルではラベル付き画像自体から位置を読み取る。生の CDP フォールバック（Playwright なし）はラベル付きスクリーンショットをまったくサポートせず、501 を返すため、Playwright が利用可能な場合にのみ labels をリクエストする。
4. 限定的に操作：
   • 最新のスナップショットからの参照を使用して、action="act" を優先する。
   • navigate はロードされたページのコンパクトなスナップショットをインラインで返し、クロスドキュメントナビゲーションを報告するバッチ act 結果には新しいページ状態が含まれるため、フォローアップのスナップショット呼び出しの代わりにそれらの参照を直接使用する。
   • ナビゲーションをトリガーする単一の act の後、モーダル変更またはフォーム送信の後は、次のアクションの前に再度スナップショットを取得する。
   • 盲目的な待機は避ける。可能な場合は可視の UI 状態を待つ。
   • これらの設定をテストする場合は、device、colorScheme、timezoneId、または locale を指定して action="emulate" を使用し、その後再度スナップショットを取得する。既存セッションプロファイルはエミュレーションをサポートしない。
5. 実際のブロッカーを報告：
   • ネットワーク障害のデバッグには action="requests" とオプションの URL/タイプ filter、limit（デフォルトは最近50エントリ）を使用する。clear=true は読み取り後に収集されたログをクリアする。管理されたプロファイルを使用する。既存セッションプロファイルはこのログをサポートしない。
   • ページエラーのデバッグには action="errors" と limit（デフォルトは最近50エントリ）を使用する。clear=true は読み取り後に収集されたログをクリアする。既存セッションプロファイルはこのログをサポートしない。
   • ページでログイン、権限、キャプチャ、2FA、カメラ/マイクの承認、またはその他の手動操作が必要な場合は、停止してユーザーに必要なものを正確に伝える。
   • 現在のページが権限やオンボーディングダイアログを表示しているという理由だけで、ブラウザがログインしていないと主張しない。最初に表示されている UI を検査する。

ブラウザバッチ CLI

openclaw browser batch は、ネストされた /act アクションの配列を1回の /act 呼び出しで実行します（エージェントツールを介して到達する同じ kind="batch" ランタイム）。これにより、CLI ユーザーとスクリプトは、wait、click、type、evaluate などのアクションを、アクションごとのラウンドトリップなしで1つの再生可能な計画に結合できます。actions[] の各エントリは BrowserActRequest（/act ルートが受け入れる closed union）であり、任意の openclaw browser サブコマンドではありません。batch は profile="user" およびその他の既存セッション（chrome-mcp）プロファイルではサポートされません。これらのプロファイルではアクションを個別に送信します。

• CLI: openclaw browser batch --actions '<json>'、--actions-file plan.json、または標準入力の場合は --actions-file -。--actions-file と標準入力は最大1,000,000バイトに制限されています。より大きな計画は複数のバッチコマンドに分割してください。--continue は stopOnError=false を設定します。デフォルトは最初のエラーで停止します。
• 参照のライフサイクル: 参照はバッチの前に実行された snapshot から取得されます（スナップショットはネストされたアクションではありません）。ページ状態を変更するネストされたアクション（ナビゲーションをトリガーする click や DOM を変更する evaluate など）は、バッチの残りに対して以前の参照を無効にする可能性があります。状態変更アクションを最初に配置するか、再スナップショット後にフォローアップバッチに分割します。ナビゲーションと再スナップショットはバッチの外部で行われます。open、navigate、snapshot は /act の種類ではないためです。
• ターゲット ID: ネストされたアクションはリクエストのタブを共有します。別のタブに解決される明示的なネストされた targetId は ACT_TARGET_ID_MISMATCH で拒否されます。
• レスポンス: { "results": [{ "ok": true } | { "ok": false, "error": "..." }, ...] } の順序。デフォルトの stopOnError では、配列は最初の失敗で終了します。失敗したエントリはゼロ以外で終了します。スクリプトで完全なレスポンスを保持するには --json を使用します。

コードモードループ

設定された決定モデルを使用した明示的なページブロッカーのトリアージについては、ページトリアージ を参照してください。ブラウザの action="judge" は、選択された決定プロバイダーを通じて制限された観測を分類し、プライマリモデルにページテキストではなく回答を返します。テキスト対応の Chromium および Lightpanda プロファイルで動作します。Lightpanda ネイティブの judge() ではありません。

tools.codeMode が有効な場合、ブラウザツールには通常のターンがありません。exec/wait の背後にカタログ化されます。exec セルから非同期グローバルとして呼び出し、exec クイックインデックスがブラウザツールに対してアドバタイズする呼び出し可能名（通常は browser）を使用します。名前が衝突する場合はサフィックスが付けられ、クライアントツールが同じ名前を獲得できます。正確な catalog.search("browser") は、すでに有効な呼び出し可能名にバインドされたハンドルを返すため、各セルでハンドルを解決し、リテラルグローバルをハードコーディングする代わりにそれを呼び出します。結果が空の場合、この実行ではブラウザツールがカタログ化されていません。

ループを通じて同じラベル付きタブを維持し、読み取りとアクションを交互に行います。各 exec セルは新しい VM を開始します。完了したセルからのバインディングは次のセルには存在せず、wait が再開するまで waiting のままの実行だけが状態を保持します。そのため、比較状態をセル間で返し、返された値を次のセルに再埋め込みます。

// previous = 最後に完了したセルによって返された url/newElements（新しい VM がこのセルを実行するため、以前のバインディングはここには存在しません）。
const previous = { url: "https://example.com/inbox", newElements: 0 };
const [browser] = await catalog.search("browser", { limit: 1 });
const details = await browser({
  action: "snapshot",
  snapshotFormat: "ai",
  targetId: "task",
  refs: "aria",
  interactive: true,
});
const changed =
  details?.url !== previous.url ||
  (details?.newElements ?? 0) > 0 ||
  details?.blockedByDialog === true;
return {
  targetId: details?.targetId,
  url: details?.url,
  newElements: details?.newElements,
  stats: details?.stats,
  text: details?.text,
  changed,
};

• コードモードの呼び出しは、ツールの構造化された details を直接返します。スナップショットとテキストの観測には、直接ツール出力と同じ信頼できないコンテンツラッパーを持つ制限付きの text が含まれます。ページデータをモデルに返すときは、そのラッパーを保持します。既存のアイデンティティ、stats、ダイアログフィールドは引き続き利用可能です。
• コードモード内で可視の散文を読むには、狭いセレクターで text をリクエストします。これは評価機能を必要としません。

const [browser] = await catalog.search("browser", { limit: 1 });
const read = await browser({
  action: "text",
  selector: "main",
  maxChars: 2000,
  targetId: "task",
});
return { url: read?.url, text: read?.text };

ラッピング前に、スナップショット query とテキスト selector/maxChars を使用して、ブラウザ所有者での読み取りを絞り込みます。ブロックされたダイアログには、報告されたリカバリ手順が引き続き必要です。ページテキストはスクリプトの評価を許可しません。

• 次のステップに必要なフィールドのみを返します。details オブジェクト全体を返さないでください。
• 完了したセルは状態を共有しません。前のセルが返した url/newElements を次のセルに再埋め込むか、比較を1つのセル内に保持します。waiting の実行のみが永続化され、wait によって再開されます。
• 各操作の後に、次の依存操作の前に URL またはタブチェックを挟みます。
• バッチが aborted を返した場合は、続行する前に新しいスナップショットを取得します。
• newElements が正の場合は、最初にそれらの要素を検査し、再埋め込み状態を更新します。
• ステップ間でナビゲーションが予想される場合は、個別の操作呼び出しを使用します。

タブの衛生管理

名前付きタスク用のタブを作成する前に、タブを一覧表示し、既存の一致するラベルまたは URL がまだ使用可能な場合はそれを再利用します。

例:

{ "action": "tabs" }

適切なタブが存在しない場合:

{ "action": "open", "url": "https://example.com", "label": "task" }

次に、ラベルでターゲットを指定:

{ "action": "snapshot", "targetId": "task", "refs": "aria" }

リトライで重複が作成された場合は、tabId で余分なタブを閉じます:

{ "action": "close", "targetId": "t3" }

targetId として "2" のような裸の数値を渡さないでください。数値タブ位置は CLI openclaw browser tab select 2 ヘルパー専用です。ブラウザツールの呼び出しには、suggestedTargetId、ラベル、tabId、または生のターゲット ID が必要です。

スタイル参照の復旧

アクションが見つからない、または古い参照で失敗した場合:

1. 同じ targetId で再度スナップショットを取得します。
2. 現在の可視コントロールを見つけます。
3. 新しい参照で一度再試行します。
4. UI がブロッカー状態に移動した場合は、ループせずにブロッカーを報告します。

既存ユーザーブラウザ

既存の Cookie やログインが重要な場合にのみ profile="user" を使用します。これにより、ユーザーの実行中の Chromium ベースのブラウザにアタッチします。

macOS では、action="importprofile" が代替手段であり、エージェントが実際の Chrome ファミリープロファイルからコピーされた Cookie を使用して分離された管理ブラウザを使用する必要がある場合に使用します。最初に action="profiles" を使用して systemProfiles を検査し、次に新しい管理プロファイル名にインポートします。インポートでは、1回の Keychain/Touch ID 同意プロンプトが必要です。Cookie をコピーしますが、ローカルストレージや IndexedDB はコピーしません。デバイスにバインドされたセッション資格情報（DBSC）により、一部の Google セッションでは再認証が必要になる場合があります。

profile="user" およびその他の既存セッションプロファイルでは、act:type、hover、scrollIntoView、drag、select、fill で timeoutMs を省略します。そのドライバーはこれらのアクションに対する呼び出しごとのタイムアウトオーバーライドを拒否します。act:evaluate は timeoutMs を受け入れます。

Google Meet のメモ

Meet を作成または参加する場合:

• カメラ/マイクの権限画面をログイン失敗ではなく進行状況として扱います。
• 人に聞こえるかどうかを尋ねられた場合は、音声が必要なときにマイクオプションをクリックします。
• Google がサインイン、2FA、アカウント選択の確認、またはユーザーの承認が必要な権限を要求した場合は、正確な手動操作を報告します。
• 会議フローごとに1つのラベル付きタブを使用します（例：label="meet"）。リトライ中はそれを再利用します。