English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Tools

瀏覽器控制 API

如需設定、組態與疑難排解，請參閱 Browser。 本頁是 local control HTTP API、openclaw browser CLI，以及腳本模式（快照、ref、等待、偵錯流程）的參考資料。

Control API（選用）

僅供本機整合使用，Gateway 會公開一個小型 local loopback HTTP API：

  • 狀態/啟動/停止：GET /、POST /start、POST /stop
  • 分頁：GET /tabs、POST /tabs/open、POST /tabs/focus、DELETE /tabs/:targetId
  • 快照/螢幕截圖：GET /snapshot、POST /screenshot
  • 動作：POST /navigate、POST /act
  • Hook：POST /hooks/file-chooser、POST /hooks/dialog
  • 下載：POST /download、POST /wait/download
  • 權限：POST /permissions/grant
  • 偵錯：GET /console、POST /pdf
  • 偵錯：GET /errors、GET /requests、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

所有端點都接受 ?profile=<name>。POST /start?headless=true 會為本機受管理設定檔請求一次性的 headless 啟動，且不變更持久化的瀏覽器組態；attach-only、遠端 CDP，以及 existing-session 設定檔會拒絕該覆寫，因為 OpenClaw 不會啟動那些瀏覽器程序。

如果已設定共享密鑰 Gateway 驗證，瀏覽器 HTTP 路由也需要驗證：

  • Authorization: Bearer <gateway token>
  • x-openclaw-password: <gateway password> 或使用該密碼的 HTTP Basic auth

注意事項：

  • 這個獨立的 local loopback 瀏覽器 API 不會使用 trusted-proxy 或 Tailscale Serve 身分標頭。
  • 如果 gateway.auth.mode 是 none 或 trusted-proxy，這些 local loopback 瀏覽器路由不會繼承那些帶有身分的模式；請讓它們僅限於 local loopback。

/act 錯誤契約

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

json
{ "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）：existing-session 設定檔不支援該動作。

其他執行階段失敗仍可能回傳沒有 code 欄位的 { "error": "<message>" }。

Playwright 需求

部分功能（導覽/動作/AI 快照/角色快照、元素螢幕截圖、PDF）需要 Playwright。如果未安裝 Playwright，那些端點會回傳清楚的 501 錯誤。

沒有 Playwright 時仍可運作的項目：

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

仍需要 Playwright 的項目：

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

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

如果你看到 Playwright is not available in this gateway build，表示封裝的 Gateway 缺少核心瀏覽器執行階段相依項。請重新安裝或更新 OpenClaw，然後重新啟動 Gateway。若使用 Docker，也請依下方所示安裝 Chromium 瀏覽器二進位檔。

Docker Playwright 安裝

如果你的 Gateway 在 Docker 中執行，請避免使用 npx playwright（npm 覆寫衝突）。 若使用自訂映像檔，請將 Chromium 烘焙進映像檔：

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

若使用既有映像檔，請改透過隨附的 CLI 安裝：

bash
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 或 bind mount 持久化。OpenClaw 會在 Linux 上自動偵測持久化的 Chromium。請參閱 Docker。

運作方式（內部）

小型 local loopback 控制伺服器會接受 HTTP 請求，並透過 CDP 連線到 Chromium 型瀏覽器。進階動作（點擊/輸入/快照/PDF）會在 CDP 之上透過 Playwright 執行；當缺少 Playwright 時，只有非 Playwright 操作可用。代理會看到一個穩定介面，而本機/遠端瀏覽器與設定檔可在底層自由替換。

CLI 快速參考

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

基礎：狀態、分頁、開啟/聚焦/關閉
bash
openclaw browser statusopenclaw browser startopenclaw browser start --headless # one-shot local managed headless launchopenclaw browser stop            # also clears emulation on attach-only/remote CDPopenclaw browser tabsopenclaw browser tab             # shortcut for current tabopenclaw browser tab newopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://example.comopenclaw browser focus abcd1234openclaw browser close abcd1234
檢查：螢幕截圖、快照、主控台、錯誤、請求
bash
openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref 12        # or --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 console --level erroropenclaw browser errors --clearopenclaw browser requests --filter api --clearopenclaw browser pdfopenclaw browser responsebody "**/api" --max-chars 5000
動作：導覽、點擊、輸入、拖曳、等待、求值
bash
openclaw browser navigate https://example.comopenclaw browser resize 1280 720openclaw browser click 12 --double           # or e12 for role refsopenclaw browser click-coords 120 340        # viewport coordinatesopenclaw 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 fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'openclaw browser dialog --acceptopenclaw 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 highlight e12openclaw browser trace startopenclaw browser trace stop
狀態：Cookie、儲存空間、離線、標頭、地理位置、裝置
bash
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 to removeopenclaw 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"

注意事項：

  • upload 與 dialog 是預先武裝呼叫；請在觸發選擇器/對話方塊的點擊/按鍵之前執行它們。
  • click/type/等需要來自 snapshot 的 ref（數字 12、角色 ref e12，或可動作 ARIA ref ax12）。動作刻意不支援 CSS selector。當可見視窗位置是唯一可靠目標時，請使用 click-coords。
  • 下載、追蹤與上傳路徑會受限於 OpenClaw 暫存根目錄：/tmp/openclaw{,/downloads,/uploads}（備援：${os.tmpdir()}/openclaw/...）。
  • upload 也可以透過 --input-ref 或 --element 直接設定檔案輸入。

當 OpenClaw 能證明替換後的分頁時，例如相同 URL，或表單提交後單一舊分頁變成單一新分頁，穩定的分頁 ID 與標籤會在 Chromium 原始目標替換後保留下來。原始目標 ID 仍然易變；在腳本中請偏好使用 tabs 的 suggestedTargetId。

快照旗標一覽：

  • --format ai（搭配 Playwright 時的預設）：含數字 ref（aria-ref="<n>"）的 AI 快照。
  • --format aria：含 axN ref 的無障礙樹。當 Playwright 可用時，OpenClaw 會將 ref 以後端 DOM ID 綁定到即時頁面，讓後續動作可以使用它們；否則請將輸出視為僅供檢查。
  • --efficient（或 --mode efficient）：精簡角色快照預設。設定 browser.snapshotDefaults.mode: "efficient" 可讓它成為預設（請參閱 Gateway 組態）。
  • --interactive、--compact、--depth、--selector 會強制使用含 ref=e12 ref 的角色快照。--frame "<iframe>" 會將角色快照限制在 iframe 範圍內。
  • --labels 會加入僅限 viewport 的螢幕截圖，並覆疊 ref 標籤（列印 MEDIA:<path>）。
  • --urls 會將發現的連結目的地附加到 AI 快照。

快照與 ref

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

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

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

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

    • 輸出：含 [ref=e12]（以及選用 [nth=1]）的角色型清單/樹。
    • 動作：openclaw browser click e12、openclaw browser highlight e12。
    • 內部會透過 getByRole(...) 解析 ref（重複項則加上 nth()）。
    • 加上 --labels 可包含覆疊 e12 標籤的 viewport 螢幕截圖。
    • 當連結文字有歧義且代理需要具體導覽目標時，請加上 --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
  • 等待 JS 述詞：
    • openclaw browser wait --fn "window.ready===true"
  • 等待選擇器變為可見：
    • openclaw browser wait "#main"

這些可以合併使用：

bash
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 用於腳本和結構化工具。

範例：

bash
openclaw browser status --jsonopenclaw browser snapshot --interactive --jsonopenclaw browser requests --filter api --jsonopenclaw browser cookies --json

JSON 中的角色快照包含 refs，以及一小段 stats 區塊（lines/chars/refs/interactive），讓工具能推論酬載大小和密度。

狀態與環境旋鈕

這些對「讓網站表現得像 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 --json '{"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 停用。
  • 如需登入和反機器人注意事項（X/Twitter 等），請參閱瀏覽器登入 + X/Twitter 發文。
  • 保持 Gateway/Node 主機私有（loopback 或僅限 tailnet）。
  • 遠端 CDP 端點權限很強；請建立通道並保護它們。

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

json5
{  browser: {    ssrfPolicy: {      dangerouslyAllowPrivateNetwork: false,      hostnameAllowlist: ["*.example.com", "example.com"],      allowedHostnames: ["localhost"], // optional exact allow    },  },}

相關

Was this useful?