瀏覽器控制 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；也接受標籤與 t1 等 tabId 控制代碼。原始 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），並確保透過 OPENCLAW_HOME_VOLUME 或繫結掛載持久保存 /home/node。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           # 或對角色參照使用 e12openclaw 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 能證明替代分頁的對應關係時，例如同一 URL 具有唯一的舊／新配對， 或提交表單後單一舊分頁變成單一新分頁，穩定的分頁 ID 與標籤可在 Chromium 原始目標替換後繼續保留。 具有相同 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 選擇器。發生此情況時，請在同一分頁上 擷取新的快照。

強化等待功能

除了時間／文字之外，你還能等待更多條件：

• 等待 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 疑難排解