瀏覽器控制 API

若需設定、組態與疑難排解資訊，請參閱瀏覽器。 本頁是本機控制 HTTP API、openclaw browser 命令列介面，以及指令碼模式（快照、參照、等待、偵錯流程）的參考資料。

控制 API（選用）

閘道僅針對本機整合提供一組小型的迴路位址 HTTP API。 此獨立伺服器須選擇啟用——請在閘道服務環境中設定環境變數 OPENCLAW_EAGER_BROWSER_CONTROL_SERVER=1， 並重新啟動閘道，HTTP 端點才會可用。若未設定 此變數，瀏覽器控制執行階段仍可透過命令列介面和 代理程式工具運作，但不會有任何服務監聽迴路位址控制連接埠。

• 狀態／啟動／停止：GET /、GET /doctor、POST /start、POST /stop、POST /reset-profile
• 設定檔：GET /profiles、POST /profiles/create、DELETE /profiles/:name
• 分頁：GET /tabs、POST /tabs/open、POST /tabs/focus、DELETE /tabs/:targetId、POST /tabs/action
• 快照／螢幕截圖：GET /snapshot、POST /screenshot
• 動作：POST /navigate、POST /act
• 鉤子：POST /hooks/file-chooser、POST /hooks/dialog
• 下載：POST /download、POST /wait/download
• 權限：POST /permissions/grant
• 偵錯：GET /console、POST /pdf
• 偵錯：GET /errors、GET /requests、GET /dialogs、POST /trace/start、POST /trace/stop、POST /highlight
• 網路：POST /response/body
• 狀態：GET /cookies、POST /cookies/set、POST /cookies/clear
• 狀態：GET /storage/:kind、POST /storage/:kind/set、POST /storage/:kind/clear
• 設定：POST /set/offline、POST /set/headers、POST /set/credentials、POST /set/geolocation、POST /set/media、POST /set/timezone、POST /set/locale、POST /set/device

POST /tabs/action 是命令列介面內部用於 browser tab 子命令（{"action":"new"|"label"|"select"|"close"|"list", ...}）的批次形式； 直接撰寫指令碼時，建議優先使用上述用途單一的分頁路由。

所有端點都接受 ?profile=<name>。POST /start?headless=true 會為本機受管理的設定檔要求 一次性無頭啟動，而不變更持久化的 瀏覽器組態；僅附加、遠端 CDP 與既有工作階段設定檔會拒絕 此覆寫，因為 OpenClaw 不會啟動那些瀏覽器程序。

對於分頁端點，targetId 是相容性欄位名稱。建議傳入來自 GET /tabs 或 POST /tabs/open 的 suggestedTargetId；標籤與 tabId 控制代碼（例如 t1）也可接受。原始 CDP 目標 ID 與唯一的原始 目標 ID 前綴仍然有效，但它們是可能變動的診斷控制代碼。

若已設定共用密鑰閘道驗證，瀏覽器 HTTP 路由也需要驗證：

• Authorization: Bearer <gateway token>
• x-openclaw-password: <gateway password>，或使用該密碼進行 HTTP 基本驗證

注意事項：

• 此獨立的迴路位址瀏覽器 API 不會使用受信任 Proxy 或 Tailscale Serve 身分標頭。
• 若 gateway.auth.mode 是 none 或 trusted-proxy，這些迴路位址瀏覽器 路由不會繼承那些帶有身分資訊的模式；請將它們限制為僅能透過迴路位址存取。

/act 錯誤契約

POST /act 針對路由層級驗證與 政策失敗使用結構化錯誤回應：

{ "error": "<message>", "code": "ACT_*" }

目前的 code 值：

• ACT_KIND_REQUIRED（HTTP 400）：kind 遺失或無法辨識。
• ACT_INVALID_REQUEST（HTTP 400）：動作承載資料正規化或驗證失敗。
• ACT_SELECTOR_UNSUPPORTED（HTTP 400）：selector 與不支援的動作種類搭配使用。
• ACT_EVALUATE_DISABLED（HTTP 403）：evaluate（或 wait --fn）已被組態停用。
• ACT_TARGET_ID_MISMATCH（HTTP 403）：頂層或批次的 targetId 與要求目標衝突。
• ACT_EXISTING_SESSION_UNSUPPORTED（HTTP 501）：既有工作階段設定檔不支援此動作。

其他執行階段失敗仍可能傳回 { "error": "<message>" }，但不含 code 欄位。

Playwright 需求

部分功能（導覽／動作／AI 快照／角色快照、元素螢幕截圖、 PDF）需要 Playwright。若未安裝 Playwright，這些端點會傳回 明確的 501 錯誤。

沒有 Playwright 仍可使用的功能：

• ARIA 快照
• 當每個分頁的 CDP WebSocket 可用時，可使用角色樣式的無障礙快照（--interactive、--compact、 --depth、--efficient）。這是用於檢查與參照探索的 備援方案；Playwright 仍是主要的 動作引擎。
• 當每個分頁的 CDP WebSocket 可用時，可擷取受管理 openclaw 瀏覽器的頁面螢幕截圖
• 可擷取 existing-session／Chrome MCP 設定檔的頁面螢幕截圖
• 可從快照輸出擷取以 existing-session 參照為基礎的螢幕截圖（--ref）

仍需要 Playwright 的功能：

• navigate
• act
• 依賴 Playwright 原生 AI 快照格式的 AI 快照
• 使用 CSS 選取器的元素螢幕截圖（--element）
• 完整的瀏覽器 PDF 匯出

元素螢幕截圖也會拒絕 --full-page；該路由會傳回 fullPage is not supported for element screenshots。

若看到 Playwright is not available in this gateway build，表示封裝版 閘道缺少核心瀏覽器執行階段相依套件。請重新安裝或更新 OpenClaw，然後重新啟動閘道。若使用 Docker，還需要依照下方說明安裝 Chromium 瀏覽器二進位檔。

Docker Playwright 安裝

若你的閘道在 Docker 中執行，請避免使用 npx playwright（npm 覆寫衝突）。 對於自訂映像，請將 Chromium 直接建置至映像中：

OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh

對於既有映像，請改用隨附的命令列介面安裝：

docker compose run --rm openclaw-cli \  node /app/node_modules/playwright-core/cli.js install chromium

若要持久保存瀏覽器下載內容，請設定 PLAYWRIGHT_BROWSERS_PATH（例如 /home/node/.cache/ms-playwright），並確保 /home/node 已透過 OPENCLAW_HOME_VOLUME 或繫結掛載進行持久化。OpenClaw 會在 Linux 上自動偵測持久化的 Chromium。請參閱 Docker。

運作方式（內部）

一個小型迴路位址控制伺服器會接受 HTTP 要求，並透過 CDP 連線至 Chromium 系瀏覽器。進階動作（點擊／輸入／快照／PDF）會在 CDP 之上透過 Playwright 執行；若缺少 Playwright，則只能使用不依賴 Playwright 的操作。代理程式看到的是單一穩定介面，而其底層可自由切換本機／遠端瀏覽器與設定檔。

命令列介面快速參考

所有命令都接受 --browser-profile <name> 以指定特定設定檔，也接受 --json 以輸出機器可讀格式。

openclaw browser statusopenclaw browser doctoropenclaw browser doctor --deep    # 新增即時快照探查openclaw browser startopenclaw browser start --headless # 一次性啟動本機受管理的無頭瀏覽器openclaw browser stop            # 也會清除僅附加／遠端 CDP 的模擬設定openclaw browser reset-profile   # 將設定檔的瀏覽器資料移至垃圾桶openclaw browser tabsopenclaw browser tab             # 目前分頁的捷徑openclaw browser tab newopenclaw browser tab new --label researchopenclaw browser tab label abcd1234 researchopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://example.comopenclaw browser focus abcd1234openclaw browser close abcd1234

openclaw browser profilesopenclaw browser create-profile --name research --color "#0066CC"openclaw browser create-profile --name attach --driver existing-session --cdp-url http://127.0.0.1:9222openclaw browser delete-profile --name research

openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref 12        # 或使用 --ref e12openclaw browser screenshot --labelsopenclaw browser snapshotopenclaw browser snapshot --format aria --limit 200openclaw browser snapshot --interactive --compact --depth 6openclaw browser snapshot --efficientopenclaw browser snapshot --labelsopenclaw browser snapshot --urlsopenclaw browser snapshot --selector "#main" --interactiveopenclaw browser snapshot --frame "iframe#main" --interactiveopenclaw browser snapshot --out snapshot.txtopenclaw browser console --level erroropenclaw browser errors --clearopenclaw browser requests --filter api --clearopenclaw browser pdfopenclaw browser responsebody "**/api" --max-chars 5000

openclaw browser navigate https://example.comopenclaw browser resize 1280 720openclaw browser click 12 --double           # 或使用 e12 作為角色參照openclaw browser click-coords 120 340        # 檢視區座標openclaw browser type 23 "hello" --submitopenclaw browser press Enteropenclaw browser hover 44openclaw browser scrollintoview e12openclaw browser drag 10 11openclaw browser select 9 OptionA OptionBopenclaw browser download e12 report.pdfopenclaw browser waitfordownload report.pdfopenclaw browser upload /tmp/openclaw/uploads/file.pdfopenclaw browser upload /tmp/openclaw/uploads/file.pdf --ref e12openclaw browser upload media://inbound/file.pdfopenclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'openclaw browser dialog --acceptopenclaw browser dialog --dismiss --dialog-id d1openclaw browser wait --text "Done"openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"openclaw browser evaluate --fn '(el) => el.textContent' --ref 7openclaw browser evaluate --fn 'const title = document.title; return title;'openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'openclaw browser highlight e12openclaw browser trace startopenclaw browser trace stop

openclaw browser cookiesopenclaw browser cookies set session abc123 --url "https://example.com"openclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set theme darkopenclaw browser storage session clearopenclaw browser set offline onopenclaw browser set headers --headers-json '{"X-Debug":"1"}'openclaw browser set credentials user pass            # 使用 --clear 移除openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"openclaw browser set media darkopenclaw browser set timezone America/New_Yorkopenclaw browser set locale en-USopenclaw browser set device "iPhone 14"

注意事項：

• 面向代理程式的 browser 工具提供 action=download（必填的 ref 和 path）以及 action=waitfordownload（選填的 path）。兩者都會傳回已儲存的 下載 URL、建議的檔名，以及受防護的本機路徑。受管理的 Playwright 設定檔可使用明確的下載 攔截；現有工作階段設定檔則會傳回不支援操作的錯誤。
• 優先使用不可分割的選擇器上傳：上傳時一併傳入觸發器 --ref，讓 OpenClaw 在單一請求中完成準備和點擊。若刻意要稍後觸發，仍支援僅含路徑的 upload。使用 --input-ref 或 --element 可直接設定檔案輸入欄位。dialog 是準備呼叫；請在觸發對話方塊的點擊／按鍵操作之前執行。如果某項操作開啟強制回應視窗，操作回應會包含 blockedByDialog 和 browserState.dialogs.pending；請傳入該 dialogId 以直接回應。在 OpenClaw 外部處理的對話方塊會顯示於 browserState.dialogs.recent 下。
• click/type/等操作需要來自 snapshot 的 ref（數字 12、角色參照 e12，或可操作的 ARIA 參照 ax12）。操作刻意不支援 CSS 選擇器。當可見視窗位置是唯一可靠的目標時，請使用 click-coords。
• 下載和追蹤路徑僅限於 OpenClaw 暫存根目錄：/tmp/openclaw{,/downloads}（備援：${os.tmpdir()}/openclaw/...）。
• upload 接受來自 OpenClaw 暫存上傳根目錄和 OpenClaw 管理的傳入媒體檔案。受管理的傳入媒體可透過 media://inbound/<id>、相對於沙箱的 media/inbound/<id>，或受管理傳入媒體 目錄內的已解析路徑來參照。巢狀媒體參照、 路徑周遊、符號連結、硬式連結和任意本機路徑仍會遭到拒絕。
• upload 也可以透過 --input-ref 或 --element 直接設定檔案輸入欄位。

當 OpenClaw 能夠確認替換分頁時，穩定的分頁 ID 和標籤會在 Chromium 原始目標替換後保留， 例如同一 URL 存在唯一的舊／新配對，或提交表單後單一舊分頁變成單一新分頁。具有相同 URL 且無法明確判定的替換項目會取得新的控制代碼。原始目標 ID 仍不穩定； 指令碼中請優先使用來自 tabs 的 suggestedTargetId。

快覽快照旗標：

• --format ai（使用 Playwright 時的預設值）：包含數字參照（aria-ref="<n>"）的 AI 快照。
• --format aria：包含 axN 參照的無障礙樹狀結構。Playwright 可用時，OpenClaw 會使用後端 DOM ID 將參照繫結至即時頁面，讓後續操作能使用這些參照；否則，請將輸出視為僅供檢查。
• --efficient（或 --mode efficient）：精簡角色快照預設。設定 browser.snapshotDefaults.mode: "efficient" 可將其設為預設值（請參閱閘道設定）。
• --interactive、--compact、--depth、--selector 會強制產生包含 ref=e12 參照的角色快照。--frame "<iframe>" 會將角色快照範圍限制在 iframe 內。
• 使用 Playwright 時，--labels 會新增一張疊加參照標籤的螢幕擷取畫面 （輸出 MEDIA:<path>），以及包含每個參照邊界方框的 annotations 陣列。 在 screenshot 上，由 Playwright 支援的標籤可搭配 --full-page、 --ref 和 --element 使用；在 snapshot 上，隨附的螢幕擷取畫面仍 僅限可見視窗。現有工作階段／chrome-mcp 設定檔會在頁面螢幕擷取畫面上呈現疊加標籤， 但不會傳回 annotations，也不會使用 Playwright 的完整頁面／參照／元素投影輔助程式。若沒有 Playwright 或 chrome-mcp， 則無法使用帶標籤的螢幕擷取畫面。
• --urls 會將探索到的連結目的地附加至 AI 快照。

快照與參照

OpenClaw 支援兩種「快照」樣式：

• AI 快照（數字參照）：openclaw browser snapshot（預設；--format ai）

  • 輸出：包含數字參照的文字快照。
  • 操作：openclaw browser click 12、openclaw browser type 23 "hello"。
  • 內部會透過 Playwright 的 aria-ref 解析參照。

• 角色快照（如 e12 的角色參照）：openclaw browser snapshot --interactive（或 --compact、--depth、--selector、--frame）

  • 輸出：包含 [ref=e12]（以及選用的 [nth=1]）且以角色為基礎的清單／樹狀結構。
  • 操作：openclaw browser click e12、openclaw browser highlight e12。
  • 內部會透過 getByRole(...)（重複項目另搭配 nth()）解析參照。
  • 新增 --labels，即可包含一張疊加 e12 標籤的螢幕擷取畫面。在 由 Playwright 支援的設定檔中，這也會傳回每個參照的邊界方框中繼資料 （annotations[]）。
  • 當連結文字語意不明，且代理程式需要明確的 導覽目標時，請新增 --urls。

• ARIA 快照（如 ax12 的 ARIA 參照）：openclaw browser snapshot --format aria

  • 輸出：以結構化節點呈現的無障礙樹狀結構。
  • 操作：當快照路徑能透過 Playwright 和 Chrome 後端 DOM ID 繫結 參照時，openclaw browser click ax12 可正常運作。

• 如果 Playwright 無法使用，ARIA 快照仍可用於 檢查，但參照可能無法操作。需要操作參照時，請使用 --format ai 或 --interactive 重新擷取快照。

• 原始 CDP 備援路徑的 Docker 驗證：pnpm test:docker:browser-cdp-snapshot 會使用 CDP 啟動 Chromium、執行 browser doctor --deep，並驗證角色 快照包含連結 URL、由游標提升為可點擊的項目，以及 iframe 中繼資料。

參照行為：

• 參照不會跨導覽保持穩定；如果發生失敗，請重新執行 snapshot 並使用新的參照。
• 若能確認替換分頁，/act 會在操作觸發替換後傳回目前的原始 targetId。 後續命令請繼續使用穩定的分頁 ID／標籤。
• 如果角色快照是使用 --frame 擷取，則角色參照的範圍會限定於該 iframe，直到下一次角色快照為止。
• 未知或過期的 axN 參照會快速失敗，而不會改由 Playwright 的 aria-ref 選擇器處理。發生此情況時， 請在同一分頁上擷取新的快照。

瀏覽器批次命令列介面

openclaw browser batch 會在一次 /act 呼叫中執行一組巢狀 /act 操作（與透過代理程式工具存取的 kind="batch" 執行階段相同），因此命令列介面 使用者和指令碼能將 wait、click、type 和 evaluate 等操作合併為單一可重播的計畫，無須為每個操作往返呼叫。 actions[] 中的每個項目都是 BrowserActRequest，也就是 /act 路由接受的封閉聯集（click、clickCoords、type、press、hover、 scrollIntoView、drag、select、fill、resize、wait、evaluate、 close、batch），而不是任意的 openclaw browser 子命令。batch 不支援 profile="user" 和其他現有工作階段（chrome-mcp） 設定檔；請在這些設定檔中個別傳送操作。

• 命令列介面：openclaw browser batch --actions '<json>'、openclaw browser batch --actions-file plan.json，或使用 openclaw browser batch --actions-file - 從標準輸入讀取 JSON 陣列。--continue 會設定 stopOnError=false； 預設會在第一個錯誤時停止。--target-id 會將整個批次限制在 一個分頁中。
• 參照生命週期：參照來自批次前執行的 snapshot（快照 不是巢狀操作）。會變更頁面狀態的巢狀操作，例如觸發導覽的 click，或變更 DOM 的 evaluate，可能會使先前的參照 在批次剩餘部分失效。請將變更狀態的操作放在前面，或在重新擷取快照後 拆分成後續批次。導覽與重新擷取快照會在批次外進行（openclaw browser navigate / snapshot），因為 open、navigate 和 snapshot 並不是 /act 類型。
• 目標 ID 衝突：巢狀操作可以省略 targetId，或重複請求層級的 targetId；如果明確指定的巢狀 targetId 解析為不同分頁， 系統會在執行任何操作前以 ACT_TARGET_ID_MISMATCH 拒絕。 依設計，批次操作共用請求的分頁。
• 錯誤摘要：回應為 { "results": [{ "ok": true }, { "ok": false, "error": "<message>" }, ...] }，依序對應每個操作各一個項目。當 stopOnError 為預設值時，陣列會在第一次失敗時結束；使用 --continue 時則會涵蓋每個操作。任何失敗項目都會使命令列介面以 非零狀態結束；傳入 --json 可為指令碼保留完整的有序回應。

等待功能強化

等待條件不僅限於時間／文字：

• 等待 URL（支援 Playwright glob）：
  • openclaw browser wait --url "**/dash"
• 等待載入狀態：
  • openclaw browser wait --load networkidle
  • 受管理的 openclaw 和原始／遠端 CDP 設定檔均支援此功能。使用 existing-session 驅動程式的設定檔（包括預設的 user 設定檔）會拒絕 networkidle；在這些設定檔中，請改用 --url、--text、選擇器或 --fn 等待條件。
• 等待 JS 述詞：
  • openclaw browser wait --fn "window.ready===true"
• 等待選擇器變為可見：
  • openclaw browser wait "#main"

這些條件可以合併使用：

openclaw browser wait "#main" \  --url "**/dash" \  --load networkidle \  --fn "window.ready===true" \  --timeout-ms 15000

偵錯工作流程

操作失敗時（例如「不可見」、「嚴格模式違規」、「遭遮蔽」）：

1. openclaw browser snapshot --interactive
2. 使用 click <ref> / type <ref>（互動模式中優先使用角色參照）
3. 如果仍然失敗：使用 openclaw browser highlight <ref> 查看 Playwright 的目標
4. 如果頁面行為異常：
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. 若要深入偵錯，請記錄追蹤：
   • openclaw browser trace start
   • 重現問題
   • openclaw browser trace stop（輸出 TRACE:<path>）

JSON 輸出

--json 適用於指令碼和結構化工具。

範例：

openclaw browser --json statusopenclaw browser --json snapshot --interactiveopenclaw browser --json requests --filter apiopenclaw browser --json cookies

JSON 中的角色快照包含 refs，以及一個小型 stats 區塊（行數／字元數／參照數／互動項目數），讓工具能判斷承載資料大小和密度。

狀態與環境調整選項

這些選項適用於「讓網站表現得像 X」的工作流程：

• Cookie：cookies、cookies set、cookies clear
• 儲存空間：storage local|session get|set|clear
• 離線：set offline on|off
• 標頭：set headers --headers-json '{"X-Debug":"1"}'（或位置參數形式 set headers '{"X-Debug":"1"}'）
• HTTP 基本驗證：set credentials user pass（或 --clear）
• 地理位置：set geo <lat> <lon> --origin "https://example.com"（或 --clear）
• 媒體：set media dark|light|no-preference|none
• 時區／語系：set timezone ...、set locale ...
• 裝置／可見視窗：
  • set device "iPhone 14"（Playwright 裝置預設）
  • set viewport 1280 720

安全性與隱私權

• openclaw 瀏覽器設定檔可能包含已登入的工作階段；請將其視為敏感資訊。
• browser act kind=evaluate / openclaw browser evaluate 和 wait --fn 會在頁面內容中執行任意 JavaScript。提示詞注入可能會操控此行為。 如果你不需要此功能，請使用 browser.evaluateEnabled=false 停用。
• openclaw browser evaluate --fn 接受函式原始碼、運算式或 陳述式主體。陳述式主體會包裝為非同步函式，因此請使用 return 指定你想取得的傳回值。當頁面端函式可能需要比預設求值逾時 更長的時間時，請使用 --timeout-ms <ms>。
• 如需登入與反機器人相關注意事項（X/Twitter 等），請參閱瀏覽器登入與 X/Twitter 發文。
• 請將閘道／節點主機維持為私有（僅限回送介面或 tailnet）。
• 遠端 CDP 端點具備強大權限；請透過隧道連線並加以保護。

嚴格模式範例（預設封鎖私人／內部目的地）：

{  browser: {    ssrfPolicy: {      dangerouslyAllowPrivateNetwork: false,      hostnameAllowlist: ["*.example.com", "example.com"],      allowedHostnames: ["localhost"], // 可選的完全相符允許項目    },  },}

相關內容

• 瀏覽器 - 概觀、設定、設定檔、安全性
• 瀏覽器登入 - 登入網站
• 瀏覽器 Linux 疑難排解
• 瀏覽器 WSL2 疑難排解