瀏覽器自動化是做什麼的？

當你需要 browser 工具執行超出單一頁面檢查的任務時，請使用此技能。

操作循環

在採取行動前檢查瀏覽器狀態：
- 當瀏覽器/插件本身可能已損壞時，使用 openclaw browser doctor 或 action="status"。
- 檢查可用性時使用 action="status"。
- 當登入狀態或設定檔選擇很重要時，使用 action="profiles"。
- 如果重試/逾時可能留下多餘視窗，在開啟新分頁前使用 action="tabs"。
偏好穩定的分頁控制代碼：
- 使用 label 開啟重要的分頁，例如 label="meet"。
- 在執行 action="tabs" 或 action="open" 後，儲存 suggestedTargetId 並在後續呼叫中將其作為 targetId 傳遞。
- suggestedTargetId 是標籤（如果存在），否則就是像 t1 這樣的穩定 tabId 控制代碼。
- 除非是立即診斷，否則避免依賴原始的 DevTools targetId；它在 Chromium 目標替換時可能會改變。
先讀取再點擊：
- 對於「讀取頁面並回答 X」，使用帶有可選 selector 和 maxChars 的 action="text" 來獲取有界可見文字（優先選取第一個匹配的選擇器，否則選取 article/main/body）。在現有會話設定檔上，改用 snapshot。高效的快照會省略大部分散文。
- 對於虛擬化列表，逐段滾動，僅擷取相關行，然後合併結果。
- 在預期的 targetId 上使用 action="snapshot"。
- 為快照新增 query 來尋找包含所有查詢 token（不區分大小寫）的行；匹配行會保留它們的 ref。
- 對後續操作使用相同的 targetId，以便 ref 保持在同一個分頁上。
- 為了取得持久的 Playwright ref，請在支援時請求 refs="aria"。如果你從 snapshotFormat="aria" 收到 axN ref，請僅在該次快照呼叫後使用它們；過時或未綁定的 axN ref 會快速失敗，需要重新進行快照。
- 當連結文字不明確，或直接導航目標可以避免脆弱的點擊時，請使用 urls=true。
- 當視覺位置重要時，在快照或螢幕截圖上使用 labels=true。在 Playwright 支援的設定檔上，回應包含一個 annotations 陣列（{ref, number, role, name?, box}），其中包含每個 ref 在擷取影像座標空間中的邊界框，因此你可以在無需重新快照的情況下推理位置；螢幕截圖標籤也可以與 fullPage=true（CLI：--full-page）結合，以標記整個文件，或與 ref / element 結合，以裁剪到某個元素。profile="user" 和其他現有會話（chrome-mcp）設定檔會將疊加層渲染到頁面螢幕截圖中，但不會附加 annotations 或使用 Playwright 的整頁/ref/元素投影輔助功能，因此在這些設定檔上，請從標記的影像本身讀取位置。原始的 CDP 回退（無 Playwright）根本不支援標籤螢幕截圖，並會返回 501，因此僅在 Playwright 可用時才請求 labels。
精準行動：
- 偏好使用來自最新快照的 ref 來進行 action="act"。
- navigate 會內聯返回載入頁面的緊湊快照，而報告跨文件導航的批次 act 結果會包含新的頁面狀態；請直接使用這些 ref，而不是進行後續的快照呼叫。
- 在單一觸發導航的 act 之後，以及在模態框更改或表單提交之後，請在下一個操作前再次進行快照。
- 避免盲目等待。盡可能等待可見的 UI 狀態。
- 在測試這些設定時，使用帶有 device、colorScheme、timezoneId 或 locale 的 action="emulate"；之後再次進行快照。現有會話設定檔不支援模擬。
回報真正的阻礙：
- 使用 action="requests"、可選的 URL/類型 filter 和 limit（預設為最近的 50 個條目）來除錯網路故障。clear=true 在讀取後清除收集的日誌。使用受管理設定檔；現有會話設定檔不支援此日誌。
- 使用 action="errors" 和 limit（預設為最近的 50 個條目）來除錯頁面錯誤。clear=true 在讀取後清除收集的日誌。現有會話設定檔不支援此日誌。
- 如果頁面需要登入、權限、驗證碼、雙重驗證、攝影機/麥克風核准或其他手動步驟，請停止並準確告知使用者需要什麼。
- 不要僅僅因為目前頁面顯示權限或入門對話框，就聲稱瀏覽器未登入。請先檢查可見的 UI。

批次 CLI

openclaw browser batch 在一個 /act 呼叫中執行一個巢狀 /act 動作的陣列（與 agent 工具透過相同 kind="batch" 執行階段），因此 CLI 使用者和腳本可以將 wait、click、type 和 evaluate 等動作組合成一個單一的可重複執行計畫，而無需每次操作都進行往返。actions[] 中的每個條目都是一個 BrowserActRequest（即 /act 路由接受的封閉聯合類型），而非任意的 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；預設在遇到第一個錯誤時停止。
Ref 生命週期：ref 來自批次執行前的 snapshot（snapshot 不是巢狀動作）。一個改變頁面狀態的巢狀動作——例如觸發導航的 click，或修改 DOM 的 evaluate——可能會使批次中剩餘的早期 ref 失效；請將狀態更改的動作放在前面，或者在重新快照後拆分為後續的批次。導航和重新快照發生在批次外部，因為 open、navigate 和 snapshot 不是 /act 的 kind。
目標 ID：巢狀動作共用請求的分頁；一個解析到不同分頁的顯式巢狀 targetId 將被拒絕，並返回 ACT_TARGET_ID_MISMATCH。
回應：{ "results": [{ "ok": true } | { "ok": false, "error": "..." }, ...] } 按順序排列；使用預設的 stopOnError 時，陣列在第一個失敗處結束。任何失敗的條目都會以非零退出；使用 --json 以在腳本中保留完整的回應。

程式碼模式循環

當啟用 tools.codeMode 時，Browser 工具沒有正常回合——它被歸類在 exec/wait 之後。從 exec 單元中以非同步全域變數的方式呼叫它，使用 exec 快速索引為 Browser 工具公告的可呼叫名稱（通常是 browser；衝突的名稱會加上後綴，且用戶端工具可能會贏得一個完全相同的名稱）。精確的 catalog.search("browser") 會回傳一個已綁定到有效可呼叫名稱的控制代碼，因此請在每個單元中解析該控制代碼並呼叫它，而不是硬編碼文字全域變數；空的結果表示 Browser 工具在此次執行中未被編入目錄。

在整個循環中保持使用相同的標籤分頁，並在讀取與動作之間交替。每個 exec 單元都會啟動一個新的 VM——已完成單元的綁定在下一個單元中消失，只有保持 waiting 的執行才能保留其狀態，直到 wait 恢復它們——因此請透過回傳比較狀態，並在下一個單元中重新嵌入回傳的值來跨單元傳遞它：

// 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,
  changed,
};

程式碼模式呼叫會直接回傳工具的結構化 details（targetId、url、newElements、stats、blockedByDialog）；渲染的頁面文字不會回傳給程式碼單元。
要在程式碼模式內讀取文字，請執行一個目標明確的 act evaluate（需要 evaluate 能力；browser.evaluateEnabled 可以停用它），並保持回傳值有界，因為頁面腳本輸出是不可信的：

const [browser] = await catalog.search("browser", { limit: 1 });
const read = await browser({
  action: "act",
  kind: "evaluate",
  fn: "() => document.body.innerText.slice(0, 2000)",
  targetId: "task",
});
return { url: read?.url, text: read?.result };

當 evaluate 不可用時，將循環保持在僅結構化狀態。

僅回傳下一步需要的欄位；絕對不要回傳整個 details 物件。
已完成的單元不共用狀態：在下一個單元中重新嵌入前一個單元回傳的 url/newElements，或將比較保持在一個單元內。只有 waiting 執行會持續存在，並由 wait 恢復。
在每個依賴的 act 之前，交錯執行 URL 或分頁檢查。
如果批次回傳 aborted，請在繼續前進行一次新的快照。
如果 newElements 為正數，請先檢查這些元素，然後更新重新嵌入的狀態。
當步驟之間預期有導航時，請使用單獨的 act 呼叫。

分頁衛生

在為命名任務建立分頁之前，請列出分頁，並在仍可使用時重複使用現有的匹配標籤或 URL。

範例：

{ "action": "tabs" }

如果沒有合適的分頁：

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

然後透過標籤定位它：

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

如果重試產生了重複項，請透過 tabId 關閉多餘的：

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

不要將像 "2" 這樣的裸數字作為 targetId 傳遞。數字分頁位置僅供 CLI openclaw browser tab select 2 輔助工具使用；瀏覽器工具呼叫需要一個 suggestedTargetId、標籤、tabId 或原始 target id。

過時 Ref 恢復

如果一個動作因缺少或過時的 ref 而失敗：

再次對相同的 targetId 進行快照。
尋找目前可見的控制項。
使用新的 ref 重試一次。
如果 UI 進入阻塞狀態，請報告阻塞項目而非循環。

現有使用者瀏覽器

僅在現有 cookies/登入狀態重要時使用 profile="user"。這會附加到使用者正在執行的 Chromium 瀏覽器。

在 macOS 上，當 agent 應該使用一個從真實 Chrome 系列設定檔複製 cookies 的隔離受管理瀏覽器時，action="importprofile" 是替代方案。首先使用 action="profiles" 並檢查 systemProfiles，然後匯入到一個新的受管理設定檔名稱。匯入會要求一次 Keychain/Touch ID 同意提示。它會複製 cookies，但不會複製 local storage 或 IndexedDB；裝置綁定的會話憑證（DBSC）意味著某些 Google 會話可能仍需要重新驗證。

對於 profile="user" 和其他現有會話設定檔，請在 act:type、hover、scrollIntoView、drag、select 和 fill 上省略 timeoutMs；該驅動程式會拒絕這些動作的每次呼叫超時覆蓋。act:evaluate 接受 timeoutMs。

Google Meet 筆記

當建立或加入 Meet 時：

將攝影機/麥克風權限畫面視為進展，而非登入失敗。
如果被問及人們是否可以聽到你，請在需要語音時點擊麥克風選項。
如果 Google 要求登入、雙重驗證、帳戶選擇器確認或需要使用者核准的權限，請回報確切的手動操作。
每個會議流程使用一個標籤分頁，例如 label="meet"，並在重試期間重複使用它。

瀏覽器自動化