跳到內容
OpenClaw

OpenClaw Managed Browser：建立 Agent 專屬隔離瀏覽環境

OpenClaw 可以執行一個由 Agent 控制的 專用 Chrome/Brave/Edge/Chromium 設定檔。它與你的個人瀏覽器隔離，並透過 Gateway 內部的一個小型本地控制服務（僅限 loopback）進行管理。

新手視角：

  • 把它想像成一個 Agent 專用的獨立瀏覽器。
  • openclaw 設定檔 不會 觸及你的個人瀏覽器設定。
  • Agent 可以在安全的環境中 開啟分頁、讀取頁面、點擊以及輸入。
  • 內建的 user 設定檔則會透過 Chrome MCP 連接到你真實登入的 Chrome 工作階段。

你能獲得什麼

Section titled “你能獲得什麼”
  • 一個名為 openclaw 的獨立瀏覽器設定檔（預設為橘色主題）。
  • 確定的分頁控制（列表、開啟、聚焦與關閉）。
  • Agent 動作（點擊、輸入、拖拽與選取）、快照、螢幕截圖以及 PDF 匯出。
  • 選配的多設定檔支援（例如 openclaw, work, remote 等）。

這個瀏覽器不是讓你日常使用的，而是一個安全、隔離的環境，專門給 Agent 進行自動化操作與驗證。

快速上手

Section titled “快速上手”
Terminal window
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

如果你看到「Browser disabled」，請在設定中啟用它（見下文）並重啟 Gateway。

如果完全找不到 openclaw browser 命令，或者 Agent 說瀏覽器工具無法使用，請跳轉到 找不到瀏覽器命令或工具。

插件控制

Section titled “插件控制”

預設的 browser 工具現在是一個內建插件，且預設為啟用。這代表你可以停用或替換它，而不需要移除 OpenClaw 的其他插件系統：

{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}

在安裝另一個提供相同 browser 工具名稱的插件之前，請先停用內建插件。預設的瀏覽器體驗需要同時滿足以下條件：

  • plugins.entries.browser.enabled 未被停用
  • browser.enabled=true

如果你只關閉插件，內建的瀏覽器 CLI (openclaw browser)、Gateway 方法 (browser.request)、Agent 工具以及預設的瀏覽器控制服務都會一起消失。你的 browser.* 設定會保留下來，供替換的插件重複使用。

內建的瀏覽器插件現在也負責瀏覽器 runtime 的實作。Core 僅保留共享的 Plugin SDK 輔助工具，以及針對舊版內部匯入路徑的相容性重新導出。實際上，移除或替換瀏覽器插件包會移除整個瀏覽器功能集，而不會在 Core 留下第二個 runtime。

瀏覽器設定的變更仍需要重啟 Gateway，這樣內建插件才能用新設定重新註冊其瀏覽器服務。

找不到瀏覽器命令或工具

Section titled “找不到瀏覽器命令或工具”

如果升級後 openclaw browser 突然變成未知命令，或者 Agent 回報找不到瀏覽器工具，最常見的原因是 plugins.allow 列表限制太嚴格，沒有包含 browser。

錯誤的設定範例：

{
  plugins: {
    allow: ["telegram"],
  },
}

將 browser 加入插件允許列表即可修復：

{
  plugins: {
    allow: ["telegram", "browser"],
  },
}

重要提示：

  • 當設定了 plugins.allow 時，光有 browser.enabled=true 是不夠的。
  • 當設定了 plugins.allow 時，光有 plugins.entries.browser.enabled=true 也是不夠的。
  • tools.alsoAllow: ["browser"] 不會載入內建的瀏覽器插件。它只會在插件載入後調整工具策略。
  • 如果你不需要嚴格的插件允許列表，移除 plugins.allow 也能恢復預設的內建瀏覽器行為。

典型症狀：

  • openclaw browser 是未知命令。
  • browser.request 遺失。
  • Agent 回報瀏覽器工具不可用。
  • 瀏覽器功能完全沒有出現在工具列表中。

設定檔：openclaw vs user

Section titled “設定檔：openclaw vs user”
  • openclaw：託管且隔離的瀏覽器（不需要擴充功能）。
  • user：內建的 Chrome MCP 附加設定檔，用於你實際登入的 Chrome 工作階段。

對於 Agent 的瀏覽器工具調用：

  • 預設：使用隔離的 openclaw 瀏覽器。
  • 當現有的登入工作階段很重要，且使用者在電腦前可以點擊或核准任何附加提示時，建議使用 profile="user"。
  • 當你想要特定的瀏覽器模式時，profile 是明確的覆寫選項。

如果你想要預設使用託管模式，請設定 browser.defaultProfile: "openclaw"。

配置

Section titled “配置”

瀏覽器設定儲存在 ~/.openclaw/openclaw.json。

{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    defaultProfile: "openclaw",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

注意：

  • 瀏覽器控制服務會綁定到 loopback，其連接埠由 gateway.port 衍生（預設：18791，即 gateway + 2）。
  • 如果你覆寫了 Gateway 連接埠（gateway.port 或 OPENCLAW_GATEWAY_PORT），衍生的瀏覽器連接埠也會隨之變動，以保持在同一個「家族」中。
  • 未設定時，cdpUrl 預設為託管的本地 CDP 連接埠。
  • remoteCdpTimeoutMs 適用於遠端（非 loopback）的 CDP 可達性檢查。
  • remoteCdpHandshakeTimeoutMs 適用於遠端 CDP WebSocket 握手逾時檢查。
  • 瀏覽器導覽或開啟分頁在導覽前會受到 SSRF 保護，並在導覽後的最終 http(s) URL 進行盡力而為的重新檢查。
  • 在嚴格的 SSRF 模式下，也會檢查遠端 CDP 端點發現與探測（cdpUrl，包括 /json/version 查找）。
  • browser.ssrfPolicy.dangerouslyAllowPrivateNetwork 預設為停用。只有當你刻意信任私有網路的瀏覽器存取時，才將其設為 true。
  • browser.ssrfPolicy.allowPrivateNetwork 仍作為舊版別名支援以保持相容性。
  • attachOnly: true 表示「絕不啟動本地瀏覽器；僅在瀏覽器已執行時附加」。
  • color 加上每個 profile 的 color 會為瀏覽器 UI 著色，讓你看到哪個 profile 正在運作。
  • 預設 profile 是 openclaw（OpenClaw 託管的獨立瀏覽器）。使用 defaultProfile: "user" 來選擇使用已登入的使用者瀏覽器。
  • 自動偵測順序：如果是基於 Chromium 的系統預設瀏覽器；否則依序為 Chrome → Brave → Edge → Chromium → Chrome Canary。
  • 本地 openclaw profiles 會自動分配 cdpPort/cdpUrl —— 僅針對遠端 CDP 設定這些項目。
  • driver: "existing-session" 使用 Chrome DevTools MCP 而非原始 CDP。不要為該 driver 設定 cdpUrl。
  • 當 existing-session profile 需要附加到非預設的 Chromium 使用者設定檔（如 Brave 或 Edge）時，請設定 browser.profiles.<name>.userDataDir。

使用 Brave (或其他基於 Chromium 的瀏覽器)

Section titled “使用 Brave (或其他基於 Chromium 的瀏覽器)”

如果你的系統預設瀏覽器是基於 Chromium 的（Chrome/Brave/Edge 等），OpenClaw 會自動使用它。設定 browser.executablePath 來覆寫自動偵測：

CLI 範例：

Terminal window
openclaw config set browser.executablePath "/usr/bin/google-chrome"
// macOS
{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
  }
}


// Windows
{
  browser: {
    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
  }
}


// Linux
{
  browser: {
    executablePath: "/usr/bin/brave-browser"
  }
}

本地與遠端控制

Section titled “本地與遠端控制”
  • 本地控制（預設）： Gateway 啟動 loopback 控制服務並可以啟動本地瀏覽器。
  • 遠端控制（node host）： 在擁有瀏覽器的機器上執行 node host；Gateway 會將瀏覽器操作代理給它。
  • 遠端 CDP： 設定 browser.profiles.<name>.cdpUrl（或 browser.cdpUrl）以附加到遠端基於 Chromium 的瀏覽器。在這種情況下，OpenClaw 不會啟動本地瀏覽器。

停止行為因 profile 模式而異：

  • 本地託管 profiles：openclaw browser stop 會停止 OpenClaw 啟動的瀏覽器程序。
  • attach-only 和遠端 CDP profiles：openclaw browser stop 會關閉活動的控制工作階段，並釋放 Playwright/CDP 模擬覆寫（viewport, 配色方案, 語系, 時區, 離線模式等狀態），即使 OpenClaw 並未啟動瀏覽器程序。

遠端 CDP URL 可以包含身份驗證：

  • 查詢權杖（例如 https://provider.example?token=<token>）
  • HTTP 基本驗證（例如 https://user:pass@provider.example）

OpenClaw 在調用 /json/* 端點以及連接到 CDP WebSocket 時會保留身份驗證。建議使用環境變數或秘密管理工具來處理權杖，而不是將它們寫入設定檔。

Node 瀏覽器代理 (零配置預設)

Section titled “Node 瀏覽器代理 (零配置預設)”

如果你在有瀏覽器的機器上執行 node host，OpenClaw 可以自動將瀏覽器工具調用路由到該節點，完全不需要額外的瀏覽器設定。這是遠端 Gateway 的預設路徑。

備註：

  • node host 透過 proxy command 暴露其本地瀏覽器控制伺服器。
  • Profile 來自節點自身的 browser.profiles 設定（與本地相同）。
  • nodeHost.browserProxy.allowProfiles 是選填的。留空則維持預設行為：所有設定好的 profile 都能透過 proxy 存取，包括 profile 的建立與刪除路由。
  • 如果你設定了 nodeHost.browserProxy.allowProfiles，OpenClaw 會將其視為最小權限邊界：只有在白名單內的 profile 才能被指定，且持久化的 profile 建立與刪除路由會在 proxy 層面被阻斷。
  • 如果你不需要這個功能，可以將其停用：
    • 在節點上：nodeHost.browserProxy.enabled=false
    • 在 Gateway 上：gateway.nodes.browser.mode="off"

Browserless (託管遠端 CDP)

Section titled “Browserless (託管遠端 CDP)”

Browserless 是一個託管的 Chromium 服務，透過 HTTPS 和 WebSocket 暴露 CDP 連線 URL。OpenClaw 支援這兩種形式，但對於遠端瀏覽器 profile 來說，最簡單的選項是直接使用 Browserless 連線文件中的 WebSocket URL。

範例：

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

備註：

  • 將 <BROWSERLESS_API_KEY> 替換成你真實的 Browserless token。
  • 選擇與你的 Browserless 帳號相符的區域端點（參考他們的文檔）。
  • 如果 Browserless 給你的是 HTTPS 基礎 URL，你可以將其轉換為 wss:// 進行直接 CDP 連線，或者保留 HTTPS URL 讓 OpenClaw 自動探索 /json/version。

直接 WebSocket CDP 提供商

Section titled “直接 WebSocket CDP 提供商”

有些託管瀏覽器服務提供 直接 WebSocket 端點，而不是標準的基於 HTTP 的 CDP 探索 (/json/version)。OpenClaw 同時支援這兩者：

  • HTTP(S) 端點 — OpenClaw 呼叫 /json/version 來探索 WebSocket 除錯 URL，然後進行連線。
  • WebSocket 端點 (ws:// / wss://) — OpenClaw 直接連線並跳過 /json/version。適用於 Browserless、Browserbase 或任何提供 WebSocket URL 的供應商。

Browserbase

Section titled “Browserbase”

Browserbase 是一個執行無頭瀏覽器的雲端平台，內建 CAPTCHA 破解、隱身模式以及住宅代理功能。

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

備註：

  • 註冊 並從 Overview 控制面板 複製你的 API Key。
  • 將 <BROWSERBASE_API_KEY> 替換成你真實的 Browserbase API key。
  • Browserbase 在 WebSocket 連線時會自動建立瀏覽器工作階段，因此不需要手動建立步驟。
  • 免費方案每月允許一個並行工作階段和一個瀏覽器小時。查看 定價 以了解付費方案限制。
  • 參考 Browserbase 文檔 取得完整的 API 參考、SDK 指南和整合範例。

安全性

Section titled “安全性”

核心概念：

  • 瀏覽器控制僅限 loopback；存取流經 Gateway 的認證或節點配對。
  • 獨立的 loopback 瀏覽器 HTTP API 僅使用共享金鑰認證：這包含 Gateway token bearer auth、x-openclaw-password，或是搭配已設定密碼的 HTTP Basic auth。
  • Tailscale Serve 身份標頭與 gateway.auth.mode: "trusted-proxy" 不會 對此獨立 loopback 瀏覽器 API 進行認證。
  • 如果啟用了瀏覽器控制且未設定共享金鑰認證，OpenClaw 會在啟動時自動產生 gateway.auth.token 並持久化到設定中。
  • 當 gateway.auth.mode 已經是 password、none 或 trusted-proxy 時，OpenClaw 不會 自動產生該 token。
  • 將 Gateway 和任何 node host 放在私有網路（如 Tailscale）中，避免暴露在公網。
  • 將遠端 CDP URL 或 token 視為機密，優先使用環境變數或機密管理工具。

遠端 CDP 提示：

  • 盡可能優先選擇加密端點（HTTPS 或 WSS）以及短期 token。
  • 避免將長效 token 直接嵌入設定檔中。

設定檔 (多瀏覽器)

Section titled “設定檔 (多瀏覽器)”

OpenClaw 支援多個具名的設定檔 (routing configs)。設定檔可以是：

  • openclaw-managed：一個專用的 Chromium 瀏覽器執行個體，擁有自己的使用者資料目錄與 CDP port。
  • remote：明確的 CDP URL（在其他地方執行的 Chromium 瀏覽器）。
  • existing session：透過 Chrome DevTools MCP 自動連接你現有的 Chrome 設定檔。

預設值：

  • 如果缺少 openclaw 設定檔，系統會自動建立。
  • user 設定檔是內建的，用於附加到 Chrome MCP 的現有工作階段。
  • 除了 user 之外，現有工作階段的設定檔需要手動啟用；請使用 --driver existing-session 來建立。
  • 本地 CDP port 預設從 18800–18899 範圍中分配。
  • 刪除設定檔會將其本地資料目錄移至垃圾桶。

所有控制端點都接受 ?profile=<name>；CLI 則使用 --browser-profile。

透過 Chrome DevTools MCP 使用現有工作階段

Section titled “透過 Chrome DevTools MCP 使用現有工作階段”

OpenClaw 也可以透過官方的 Chrome DevTools MCP 伺服器，附加到正在執行的 Chromium 瀏覽器設定檔。這會重用該瀏覽器設定檔中已經開啟的分頁和登入狀態。

官方背景與設定參考：

內建設定檔：

  • user

選填：如果你想要不同的名稱、顏色或瀏覽器資料目錄，可以建立你自己的自定義現有工作階段設定檔。

預設行為：

  • 內建的 user 設定檔使用 Chrome MCP 自動連接，目標是預設的本地 Google Chrome 設定檔。

若要針對 Brave, Edge, Chromium 或非預設的 Chrome 設定檔，請使用 userDataDir：

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}

接著在對應的瀏覽器中：

  1. 開啟該瀏覽器的 inspect 頁面進行遠端偵錯。
  2. 啟用遠端偵錯 (remote debugging)。
  3. 保持瀏覽器執行，並在 OpenClaw 附加時核准連線提示。

常見的 inspect 頁面：

  • Chrome: chrome://inspect/#remote-debugging
  • Brave: brave://inspect/#remote-debugging
  • Edge: edge://inspect/#remote-debugging

即時附加冒煙測試 (smoke test)：

Terminal window
openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai

成功時的樣子：

  • status 顯示 driver: existing-session
  • status 顯示 transport: chrome-mcp
  • status 顯示 running: true
  • tabs 列出你已經開啟的瀏覽器分頁
  • snapshot 從選定的即時分頁回傳 refs

如果附加失敗，請檢查：

  • 目標 Chromium 瀏覽器版本為 144+
  • 該瀏覽器的 inspect 頁面已啟用遠端偵錯
  • 瀏覽器顯示了附加同意提示且你已接受
  • openclaw doctor 會遷移舊的擴充功能瀏覽器配置，並檢查本地是否安裝了 Chrome 以供預設自動連接設定檔使用，但它無法幫你啟用瀏覽器端的遠端偵錯

Agent 使用：

  • 當你需要使用者已登入的瀏覽器狀態時，請使用 profile="user"。
  • 如果你使用自定義的現有工作階段設定檔，請傳遞該明確的設定檔名稱。
  • 僅在使用者在電腦前可以核准附加提示時，才選擇此模式。
  • Gateway 或 node 主機可以啟動 npx chrome-devtools-mcp@latest --autoConnect

筆記：

  • 此路徑比隔離的 openclaw 設定檔風險更高，因為它可以在你已登入的瀏覽器工作階段中操作。
  • OpenClaw 不會為此 driver 啟動瀏覽器；它僅附加到現有工作階段。
  • OpenClaw 在此處使用官方的 Chrome DevTools MCP --autoConnect 流程。如果設定了 userDataDir，OpenClaw 會將其傳遞以指定該明確的 Chromium 使用者資料目錄。
  • 現有工作階段的螢幕截圖支援頁面擷取以及來自 snapshot 的 --ref 元素擷取，但不支援 CSS --element 選擇器。
  • 現有工作階段的頁面螢幕截圖可以在沒有 Playwright 的情況下透過 Chrome MCP 運作。基於 ref 的元素截圖 (--ref) 也可以運作，但 --full-page 不能與 --ref 或 --element 同時使用。
  • 現有工作階段的操作限制仍然比受控瀏覽器路徑更多：
    • click, type, hover, scrollIntoView, drag, 和 select 需要 snapshot refs 而非 CSS 選擇器
    • click 僅限左鍵（不支援按鍵覆蓋或修飾鍵）
    • type 不支援 slowly=true；請使用 fill 或 press
    • press 不支援 delayMs
    • hover, scrollIntoView, drag, select, fill, 和 evaluate 不支援單次呼叫的 timeout 覆蓋
    • select 目前僅支援單一數值
  • 現有工作階段的 wait --url 支援精確匹配、子字串和 glob 模式，與其他瀏覽器 driver 相同。目前尚不支援 wait --load networkidle。
  • 現有工作階段的上傳 hook 需要 ref 或 inputRef ，一次支援一個檔案，且不支援 CSS element 定位。
  • 現有工作階段的對話框 hook 不支援 timeout 覆蓋。
  • 某些功能仍需要受控瀏覽器路徑，包括批次操作、PDF 匯出、下載攔截和 responsebody。
  • 現有工作階段僅限於本地主機。如果 Chrome 位於不同的機器或不同的網路命名空間，請改用 remote CDP 或 node 主機。

隔離保證

Section titled “隔離保證”
  • 專用的使用者資料目錄：絕不碰觸你的個人瀏覽器設定檔。
  • 專用連接埠：避開 9222 以防止與開發工作流程衝突。
  • 確定性的分頁控制：透過 targetId 指定分頁，而非「最後一個分頁」。

瀏覽器選擇

Section titled “瀏覽器選擇”

在本地啟動時，OpenClaw 會依序挑選第一個可用的瀏覽器：

  1. Chrome
  2. Brave
  3. Edge
  4. Chromium
  5. Chrome Canary

你可以透過 browser.executablePath 進行覆蓋。

平台：

  • macOS：檢查 /Applications 和 ~/Applications。
  • Linux：尋找 google-chrome, brave, microsoft-edge, chromium 等。
  • Windows：檢查常見的安裝位置。

Control API (選填)

Section titled “Control API (選填)”

對於僅限本地整合的情況，Gateway 提供了一個小型的 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
  • Hooks：POST /hooks/file-chooser、POST /hooks/dialog
  • 下載：POST /download、POST /wait/download
  • 除錯：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>。

如果配置了 shared-secret gateway auth，瀏覽器的 HTTP 路由也需要驗證：

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

注意：

  • 這個獨立的 loopback 瀏覽器 API 不會 採用 trusted-proxy 或 Tailscale Serve 的身份標頭。
  • 如果 gateway.auth.mode 為 none 或 trusted-proxy，這些 loopback 瀏覽器路由不會繼承這些身份驗證模式；請保持它們僅限於 loopback 存取。

/act 錯誤協定

Section titled “/act 錯誤協定”

POST /act 使用結構化的錯誤回應來處理路由層級的驗證和策略失敗：

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

目前的 code 值：

  • ACT_KIND_REQUIRED (HTTP 400)：缺少 kind 或無法識別。
  • ACT_INVALID_REQUEST (HTTP 400)：動作 payload 正規化或驗證失敗。
  • 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 設定檔。

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

Playwright 需求

Section titled “Playwright 需求”

部分功能（navigate/act/AI snapshot/role snapshot、元素截圖、PDF）需要 Playwright。如果沒有安裝 Playwright，這些端點會回傳明確的 501 錯誤。

沒有 Playwright 時仍可運作的功能：

  • ARIA snapshots
  • 當每分頁的 CDP WebSocket 可用時，受管理 openclaw 瀏覽器的頁面截圖
  • existing-session / Chrome MCP 設定檔的頁面截圖
  • 來自 snapshot 輸出的 existing-session 基於引用的截圖 (--ref)

仍需要 Playwright 的功能：

  • navigate
  • act
  • AI snapshots / role snapshots
  • CSS-selector 元素截圖 (--element)
  • 完整的瀏覽器 PDF 匯出

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

如果你看到 Playwright is not available in this gateway build，請安裝完整的 Playwright 套件（不是 playwright-core）並重啟 gateway，或者重新安裝支援瀏覽器的 OpenClaw。

Docker Playwright 安裝

Section titled “Docker Playwright 安裝”

如果你的 Gateway 在 Docker 中執行，請避免使用 npx playwright（npm override 會產生衝突）。請改用內建的 CLI：

Terminal window
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 進行持久化。請參考 Docker。

運作原理 (內部機制)

Section titled “運作原理 (內部機制)”

高層級流程：

  • 一個小型的 control server 接收 HTTP 請求。
  • 它透過 CDP 連接到基於 Chromium 的瀏覽器 (Chrome/Brave/Edge/Chromium)。
  • 對於進階動作 (click/type/snapshot/PDF)，它在 CDP 之上使用 Playwright。
  • 當缺少 Playwright 時，僅提供非 Playwright 的操作。

這種設計讓 agent 保持在穩定且確定的介面上，同時讓你可以自由切換本地或遠端瀏覽器與設定檔。

CLI 快速參考

Section titled “CLI 快速參考”

所有指令都支援 --browser-profile <name> 來指定特定的設定檔。 所有指令也支援 --json 參數，方便輸出機器可讀的格式（穩定的 payload）。

基礎指令：

Terminal window
- openclaw browser status
- openclaw browser start
- openclaw browser stop
- openclaw browser tabs
- openclaw browser tab
- openclaw browser tab new
- openclaw browser tab select 2
- openclaw browser tab close 2
- openclaw browser open https://example.com
- openclaw browser focus abcd1234
- openclaw browser close abcd1234

檢查指令：

Terminal window
- openclaw browser screenshot
- openclaw browser screenshot --full-page
- openclaw browser screenshot --ref 12
- openclaw browser screenshot --ref e12
- openclaw browser snapshot
- openclaw browser snapshot --format aria --limit 200
- openclaw browser snapshot --interactive --compact --depth 6
- openclaw browser snapshot --efficient
- openclaw browser snapshot --labels
- openclaw browser snapshot --selector "#main" --interactive
- openclaw browser snapshot --frame "iframe#main" --interactive
- openclaw browser console --level error

生命週期說明：

  • 對於 attach-only 和遠端 CDP 設定檔，openclaw browser stop 仍然是測試後正確的清理指令。它會關閉目前的控制工作階段並清除暫時的模擬覆蓋 (emulation overrides)，而不是直接殺掉底層的瀏覽器。
Terminal window
- openclaw browser errors --clear
- openclaw browser requests --filter api --clear
- openclaw browser pdf
- openclaw browser responsebody "**/api" --max-chars 5000

操作指令：

Terminal window
- openclaw browser navigate https://example.com
- openclaw browser resize 1280 720
- openclaw browser click 12 --double
- openclaw browser click e12 --double
- openclaw browser type 23 "hello" --submit
- openclaw browser press Enter
- openclaw browser hover 44
- openclaw browser scrollintoview e12
- openclaw browser drag 10 11
- openclaw browser select 9 OptionA OptionB
- openclaw browser download e12 report.pdf
- openclaw browser waitfordownload report.pdf
- openclaw browser upload /tmp/openclaw/uploads/file.pdf
- openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
- openclaw browser dialog --accept
- openclaw browser wait --text "Done"
- openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
- openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
- openclaw browser highlight e12
- openclaw browser trace start
- openclaw browser trace stop

狀態指令：

Terminal window
- openclaw browser cookies
- openclaw browser cookies set session abc123 --url "https://example.com"
- openclaw browser cookies clear
- openclaw browser storage local get
- openclaw browser storage local set theme dark
- openclaw browser storage session clear
- openclaw browser set offline on
- openclaw browser set headers --headers-json '{"X-Debug":"1"}'
- openclaw browser set credentials user pass
- openclaw browser set credentials --clear
- openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
- openclaw browser set geo --clear
- openclaw browser set media dark
- openclaw browser set timezone America/New_York
- openclaw browser set locale en-US
- openclaw browser set device "iPhone 14"

注意事項：

  • upload 和 dialog 是預備型 (arming) 呼叫；你必須在觸發檔案選擇器或對話框的點擊/按鍵動作「之前」執行它們。
  • 下載和 trace 的輸出路徑被限制在 OpenClaw 的暫存根目錄：
    • traces: /tmp/openclaw（備用路徑：${os.tmpdir()}/openclaw）
    • downloads: /tmp/openclaw/downloads（備用路徑：${os.tmpdir()}/openclaw/downloads）
  • 上傳路徑被限制在 OpenClaw 的暫存上傳根目錄：
    • uploads: /tmp/openclaw/uploads（備用路徑：${os.tmpdir()}/openclaw/uploads）
  • upload 也可以透過 --input-ref 或 --element 直接設定檔案輸入。
  • snapshot：
    • --format ai（安裝 Playwright 後的預設值）：回傳帶有數字 Ref (aria-ref="<n>") 的 AI snapshot。
    • --format aria：回傳無障礙樹 (accessibility tree)，沒有 Ref，僅供檢查使用。
    • --efficient（或 --mode efficient）：精簡的角色 snapshot 預設組合（包含 interactive + compact + depth + 較低的 maxChars）。
    • 設定預設值（僅限 tool/CLI）：設定 browser.snapshotDefaults.mode: "efficient" 可以在呼叫者未傳遞模式時使用高效模式（參考 Gateway configuration）。
    • 角色 snapshot 選項（--interactive, --compact, --depth, --selector）會強制執行基於角色的 snapshot，並帶有像 ref=e12 這樣的 Ref。
    • --frame "<iframe selector>" 將角色 snapshot 的範圍限制在特定的 iframe 內（與 e12 這種角色 Ref 搭配使用）。
    • --interactive 會輸出一個扁平、易於選取的互動元素列表（最適合用來驅動操作）。
    • --labels 會增加一張僅限視口的螢幕截圖，並疊加 Ref 標籤（會印出 MEDIA:<path>）。
  • click/type 等指令需要從 snapshot 取得 ref（數字 12 或角色 Ref e12 皆可）。我們刻意不在操作指令中支援 CSS selector。

Snapshot 與 Ref 參考

Section titled “Snapshot 與 Ref 參考”

OpenClaw 支援兩種「Snapshot」風格：

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

    • 輸出：包含數字 Ref 的文字 snapshot。
    • 操作範例：openclaw browser click 12, openclaw browser type 23 "hello"。
    • 內部機制：Ref 是透過 Playwright 的 aria-ref 解析的。

  • Role snapshot（像是 e12 的角色 Ref）：openclaw browser snapshot --interactive（或使用 --compact, --depth, --selector, --frame）

    • 輸出：帶有 [ref=e12]（以及可選的 [nth=1]）的基於角色的列表或樹狀結構。
    • 操作範例：openclaw browser click e12, openclaw browser highlight e12。
    • 內部機制：Ref 是透過 getByRole(...) 解析的（重複時會加上 nth()）。
    • 加上 --labels 可以取得一張疊加了 e12 標籤的視口截圖。

Ref 的行為特性：

  • Ref 在頁面導航後會失效；如果操作失敗，請重新執行 snapshot 並使用新的 Ref。
  • 如果角色 snapshot 是帶著 --frame 執行的，那麼在下一次角色 snapshot 之前，所有的角色 Ref 都會被限制在該 iframe 的範圍內。

Wait 進階功能

Section titled “Wait 進階功能”

除了時間或文字，你還可以等待更多不同的條件：

  • 等待 URL（支援 Playwright 的 glob 語法）：
    • openclaw browser wait --url "**/dash"
  • 等待載入狀態：
    • openclaw browser wait --load networkidle
  • 等待 JS 斷言 (predicate)：
    • openclaw browser wait --fn "window.ready===true"
  • 等待特定 selector 變為可見：
    • openclaw browser wait "#main"

這些條件可以組合使用：

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

除錯流程

Section titled “除錯流程”

當動作失敗時（例如出現 「not visible」、「strict mode violation」或 「covered」等錯誤）：

  1. openclaw browser snapshot --interactive
  2. 使用 click <ref> / type <ref>（在互動模式下建議優先使用 role refs）
  3. 如果還是失敗：執行 openclaw browser highlight <ref> 來查看 Playwright 到底選中了什麼
  4. 如果頁面行為怪異：
    • openclaw browser errors --clear
    • openclaw browser requests --filter api --clear
  5. 需要深度除錯時，可以錄製 trace：
    • openclaw browser trace start
    • 重現問題
    • openclaw browser trace stop（會印出 TRACE:<path>）

JSON 輸出

Section titled “JSON 輸出”

--json 是為了腳本編寫和結構化工具設計的。

範例：

Terminal window
openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json

JSON 格式的 Role snapshots 包含 refs 以及一個小型的 stats 區塊（包含 lines/chars/refs/interactive），方便工具判斷 payload 的大小和密度。

狀態與環境調整

Section titled “狀態與環境調整”

如果你需要「讓網站表現得像某種特定狀態」，這些功能會非常有用：

  • Cookies：cookies, cookies set, cookies clear
  • Storage：storage local|session get|set|clear
  • 離線模式：set offline on|off
  • Headers：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

安全與隱私

Section titled “安全與隱私”
  • openclaw 的 browser profile 可能包含已登入的 session，請將其視為敏感資料。
  • browser act kind=evaluate / openclaw browser evaluate 和 wait --fn 會在頁面環境中執行任意 JavaScript。Prompt injection 可能會操控這些行為。如果你不需要這項功能，可以透過 browser.evaluateEnabled=false 將其停用。
  • 關於登入和防機器人偵測的注意事項（如 X/Twitter 等），請參考 Browser login + X/Twitter posting。
  • 確保 Gateway/node host 保持私有（僅限 loopback 或 tailnet 使用）。
  • 遠端的 CDP endpoint 權限非常強大，請務必使用 tunnel 並做好保護。

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

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

疑難排解

Section titled “疑難排解”

針對 Linux 特有的問題（特別是 snap 版的 Chromium），請參考 Browser troubleshooting。

針對 WSL2 Gateway + Windows Chrome 的跨主機設定，請參考 WSL2 + Windows + remote Chrome CDP troubleshooting。

Agent 工具與控制運作方式

Section titled “Agent 工具與控制運作方式”

Agent 只有一個工具可以用來處理瀏覽器自動化：

  • browser — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

具體運作方式如下：

  • browser snapshot 會回傳穩定的 UI 樹（AI 或 ARIA）。
  • browser act 使用 snapshot 的 ref ID 來進行點擊、輸入、拖曳或選擇。
  • browser screenshot 擷取像素（整頁或特定元素）。
  • browser 接受以下參數：
    • profile：選擇具名的瀏覽器設定檔（openclaw, chrome 或遠端 CDP）。
    • target (sandbox | host | node)：選擇瀏覽器運行的位置。
    • 在沙盒（sandboxed）工作階段中，target: "host" 需要設定 agents.defaults.sandbox.browser.allowHostControl=true。
    • 如果省略 target：沙盒工作階段預設為 sandbox，非沙盒工作階段預設為 host。
    • 如果連接著具備瀏覽器能力的節點，除非你固定使用 target="host" 或 target="node"，否則工具可能會自動路由到該節點。

這樣可以確保 Agent 的行為是確定性的，並避免使用脆弱的選擇器（selectors）。

相關文件

Section titled “相關文件”
OpenClaw

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。