openclaw browser
管理 OpenClaw 的瀏覽器控制介面並執行瀏覽器動作：生命週期、設定檔、分頁、快照、螢幕截圖、導覽、輸入、狀態模擬與除錯。
相關：瀏覽器工具
常用旗標
--url <gatewayWsUrl>：閘道 WebSocket URL（預設使用設定）。--token <token>：閘道權杖（如有需要）。--timeout <ms>：請求逾時，單位為 ms（預設：30000）。--expect-final：等待最終閘道回應。--browser-profile <name>：選擇瀏覽器設定檔（預設：openclaw，或browser.defaultProfile）。--json：機器可讀輸出（在支援處）。
快速開始（本機）
browser({ action: "doctor" }) 執行相同的就緒檢查。
快速疑難排解
如果start 失敗並顯示 not reachable after start，請先排查 CDP 就緒狀態。如果 start 和 tabs 成功，但 open 或 navigate 失敗，表示瀏覽器控制平面是正常的，而失敗通常是導覽 SSRF 政策封鎖。
最小序列：
生命週期
doctor --deep會加入即時快照探測：當基本 CDP 就緒狀態為綠燈，但你想證明目前分頁可被檢查時很有用。stop會關閉作用中的控制工作階段，並清除暫時的模擬覆寫；即使是attachOnly和遠端 CDP 設定檔，OpenClaw 未自行啟動瀏覽器程序時也一樣。對於本機受管理設定檔，stop也會停止產生的瀏覽器程序。start --headless只套用於該次啟動請求，且只在 OpenClaw 啟動本機受管理瀏覽器時生效。它不會改寫browser.headless或設定檔設定，對已在執行的瀏覽器也不會有作用。- 在沒有
DISPLAY或WAYLAND_DISPLAY的 Linux 主機上，本機受管理設定檔會自動以無頭模式執行，除非OPENCLAW_BROWSER_HEADLESS=0、browser.headless=false或browser.profiles.<name>.headless=false明確要求可見瀏覽器。
如果缺少命令
如果openclaw browser 是未知命令，請檢查 ~/.openclaw/openclaw.json 中的 plugins.allow。當存在 plugins.allow 時，除非設定已經有根層級 browser 區塊，否則請明確列出內建瀏覽器外掛：
browser 區塊（例如 browser.enabled=true 或 browser.profiles.<name>）也會在限制性外掛允許清單下啟用內建瀏覽器外掛。
相關：瀏覽器工具
設定檔
設定檔是具名的瀏覽器路由設定：openclaw（預設）：啟動或附加到專用的 OpenClaw 管理 Chrome 執行個體（隔離的使用者資料目錄）。user：透過 Chrome DevTools MCP 控制你現有已登入的 Chrome 工作階段。- 自訂 CDP 設定檔：指向本機或遠端 CDP 端點。
--browser-profile <name> 指定設定檔，例如 openclaw browser --browser-profile work tabs。
分頁
tabs 會先回傳 suggestedTargetId，接著是穩定的 tabId（例如 t1）、選用標籤，以及原始 targetId。將 suggestedTargetId 傳回 focus、close、快照與動作。使用 open --label、tab new --label 或 tab label 指派標籤；標籤、分頁 ID、原始目標 ID，以及唯一的目標 ID 前綴都可接受。為了相容性，請求欄位仍命名為 targetId，但它接受上述任一分頁參照。
原始目標 ID 是易變的診斷控制代碼，不是持久的代理程式記憶：當 Chromium 在導覽或表單提交期間替換底層原始目標時，只要 OpenClaw 能證明相符，就會將穩定的 tabId/標籤附加到替換後的分頁。請優先使用 suggestedTargetId。
快照 / 螢幕截圖 / 動作
快照：--full-page只適用於頁面擷取；不可與--ref或--element搭配使用。existing-session/user設定檔支援頁面螢幕截圖，以及來自快照輸出的--ref螢幕截圖，但不支援 CSS--element螢幕截圖。--labels會在螢幕截圖上疊加目前的快照參照。在 Playwright 支援的設定檔上，它可搭配--full-page（完整頁面疊加）、--ref（依 ARIA 參照的元素裁切疊加）和--element（依 CSS 選擇器的元素裁切疊加）使用；在元素裁切模式中，標籤會相對於該元素投影。回應也會包含annotations陣列（空值時省略），內含每個參照的邊界框：ref、number、role、選用的name，以及擷取影像座標空間（視窗 / 完整頁面 / 元素相對）中的box: {x, y, width, height}。existing-session設定檔會在頁面螢幕截圖上呈現 chrome-mcp 疊加，但不使用 Playwright 投影輔助工具，也不包含annotations；該處不支援 CSS--element螢幕截圖。沒有 Playwright 或 chrome-mcp 時，標記螢幕截圖不可用。snapshot --urls會將發現的連結目的地附加到 AI 快照，讓代理程式可選擇直接導覽目標，而不必只根據連結文字猜測。
evaluate --fn 接受函式原始碼、運算式或陳述式主體。陳述式主體會包裝為 async 函式，因此請使用 return 回傳你想要的值。當頁面端函式可能需要比預設 evaluate 逾時更長的時間時，請使用 --timeout-ms。browser.evaluateEnabled=false（預設：true）會停用 evaluate 和 wait --fn。
當 OpenClaw 能證明替換分頁時，動作回應會在動作觸發頁面替換後回傳目前的原始 targetId。指令碼仍應儲存並傳遞 suggestedTargetId/標籤，以用於長期工作流程。
檔案 + 對話方塊輔助工具：
/tmp/openclaw/downloads，或已設定的暫存根目錄）。當代理程式需要等待特定檔案並回傳其路徑時，請使用 waitfordownload 或 download；這些明確的等待器會擁有下一個下載。上傳接受來自 OpenClaw 暫存上傳根目錄與 OpenClaw 管理傳入媒體的檔案，包括 media://inbound/<id> 和沙箱相對 media/inbound/<id> 參照。巢狀媒體參照、路徑遍歷和任意本機路徑都會被拒絕。
當動作開啟模態對話方塊時，動作回應會回傳含有 browserState.dialogs.pending 的 blockedByDialog；傳入 --dialog-id 可直接回應。OpenClaw 外部處理的對話方塊會出現在 browserState.dialogs.recent 下。
狀態與儲存
視窗 + 模擬：除錯
透過 MCP 使用現有 Chrome
使用內建的user 設定檔，或建立你自己的 existing-session 設定檔：
--cdp-url，讓 Chrome MCP 改為附加到該端點。對於 Docker、Browserless 或其他不需要 Chrome MCP 語意的遠端設定，請改用 CDP 設定檔。
目前的現有工作階段限制：
- 由快照驅動的動作使用參照，而不是 CSS 選擇器。
- 當呼叫者省略
timeoutMs時，browser.actionTimeoutMs會將支援的act請求預設為 60000 ms；每次呼叫的timeoutMs仍會優先。 click僅支援左鍵點擊。type不支援slowly=true。press不支援delayMs。hover、scrollintoview、drag、select、fill和evaluate會拒絕每次呼叫的逾時覆寫。select僅支援一個值。- 不支援
wait --load networkidle（在受管理和原始/遠端 CDP 設定檔上可運作）。 - 檔案上傳需要
--ref/--input-ref，不支援 CSS--element，且一次只支援一個檔案。 - 對話方塊掛鉤不支援
--timeout。 - 螢幕截圖支援頁面擷取和
--ref，但不支援 CSS--element。 responsebody、下載攔截、PDF 匯出和批次動作仍需要受管理瀏覽器或原始 CDP 設定檔。
遠端瀏覽器控制（節點主機代理）
如果閘道和瀏覽器執行在不同機器上，請在有 Chrome/Brave/Edge/Chromium 的機器上執行一個節點主機。閘道會將瀏覽器操作代理到該節點；不需要另外的瀏覽器控制伺服器。 使用gateway.nodes.browser.mode 控制自動路由，並在連接多個節點時使用 gateway.nodes.browser.node 固定到特定節點。
安全性 + 遠端設定：瀏覽器工具、遠端存取、Tailscale、安全性