瀏覽器（OpenClaw 受管理模式）

OpenClaw 可以執行一個專屬的 Chrome/Brave/Edge/Chromium 設定檔，由代理進行控制。它與你的個人瀏覽器隔離，透過 Gateway 內部的本地控制服務進行管理（僅限回環連線）。

入門概念：

把它想成一個獨立的、代理專用的瀏覽器。
openclaw 設定檔不會碰到你個人的瀏覽器設定檔。
代理可以在安全的軌道上開啟分頁、讀取頁面、點擊和輸入。
預設的 chrome 設定檔會透過擴充功能中繼使用系統預設的 Chromium 瀏覽器；切換到 openclaw 即可使用隔離的受管理瀏覽器。

提供的功能

一個獨立的瀏覽器設定檔，命名為 openclaw（預設橘色色調）。
確定性的分頁控制（列出 / 開啟 / 聚焦 / 關閉）。
代理操作（點擊 / 輸入 / 拖曳 / 選取）、快照、截圖、PDF。
可選的多設定檔支援（openclaw、work、remote 等）。

這個瀏覽器不是你的日常瀏覽器，而是一個安全、隔離的環境，供代理自動化和驗證之用。

快速上手

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` vs `chrome`

openclaw：受管理的隔離瀏覽器（不需要擴充功能）。
chrome：連接你系統瀏覽器的擴充功能中繼（需要安裝 OpenClaw 擴充功能並附掛到分頁）。
existing-session：官方的 Chrome MCP 附掛流程，連線到執行中的 Chrome 設定檔。

如果想預設使用受管理模式，設定 browser.defaultProfile: "openclaw"。

設定

瀏覽器設定位於 ~/.openclaw/openclaw.json。

{
  browser: {
    enabled: true, // 預設：true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // 預設信任網路模式
      // allowPrivateNetwork: true, // 舊版別名
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // 舊版單一設定檔覆寫
    remoteCdpTimeoutMs: 1500, // 遠端 CDP HTTP 逾時（毫秒）
    remoteCdpHandshakeTimeoutMs: 3000, // 遠端 CDP WebSocket 交握逾時（毫秒）
    defaultProfile: "chrome",
    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" },
      chromeLive: {
        cdpPort: 18802,
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

注意事項：

瀏覽器控制服務繫結在從 gateway.port 衍生的回環連接埠上（預設：18791，即 gateway + 2）。中繼使用下一個連接埠（18792）。
如果你覆寫了 Gateway 連接埠（gateway.port 或 OPENCLAW_GATEWAY_PORT），衍生的瀏覽器連接埠會跟著調整以保持在同一「家族」中。
未設定時，cdpUrl 預設為中繼連接埠。
remoteCdpTimeoutMs 適用於遠端（非回環）CDP 可達性檢查。
remoteCdpHandshakeTimeoutMs 適用於遠端 CDP WebSocket 可達性檢查。
瀏覽器導航 / 開啟分頁在導航前會經過 SSRF 防護，並在導航到最終 http(s) URL 後盡力重新檢查。
browser.ssrfPolicy.dangerouslyAllowPrivateNetwork 預設為 true（信任網路模式）。設為 false 可限制為僅公開網站。
browser.ssrfPolicy.allowPrivateNetwork 作為舊版別名仍然支援。
attachOnly: true 表示「不啟動本地瀏覽器；僅在已有執行中的瀏覽器時附掛」。
color 和每個設定檔的 color 會為瀏覽器 UI 上色，讓你分辨正在使用哪個設定檔。
預設設定檔為 openclaw（OpenClaw 受管理的獨立瀏覽器）。使用 defaultProfile: "chrome" 可切換到 Chrome 擴充功能中繼。
自動偵測順序：如果系統預設瀏覽器是 Chromium 系列則優先使用；否則依序 Chrome → Brave → Edge → Chromium → Chrome Canary。
本地 openclaw 設定檔會自動指派 cdpPort/cdpUrl —— 只有遠端 CDP 才需要手動設定。
driver: "existing-session" 使用 Chrome DevTools MCP 而非原始 CDP。該驅動不要設定 cdpUrl。

使用 Brave（或其他 Chromium 系列瀏覽器）

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

CLI 範例：

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"
  }
}

本地與遠端控制

本地控制（預設）： Gateway 啟動回環控制服務，可啟動本地瀏覽器。
遠端控制（節點主機）： 在有瀏覽器的機器上執行節點主機；Gateway 會將瀏覽器操作代理到該節點。
遠端 CDP： 設定 browser.profiles.<name>.cdpUrl（或 browser.cdpUrl）以附掛到遠端的 Chromium 系列瀏覽器。此時 OpenClaw 不會啟動本地瀏覽器。

遠端 CDP URL 可包含驗證資訊：

查詢參數 token（例如 https://provider.example?token=<token>）
HTTP Basic 驗證（例如 https://user:[email protected]）

OpenClaw 在呼叫 /json/* 端點和連線 CDP WebSocket 時會保留驗證資訊。建議使用環境變數或密鑰管理工具來存放 token，而非寫死在設定檔中。

節點瀏覽器代理（零設定預設）

如果你在有瀏覽器的機器上執行節點主機，OpenClaw 可以自動將瀏覽器工具呼叫導向該節點，不需要額外的瀏覽器設定。這是遠端 Gateway 的預設路徑。

注意事項：

節點主機透過代理指令公開其本地瀏覽器控制服務。
設定檔來自節點自身的 browser.profiles 設定（與本地相同）。
不需要時可停用：
- 節點端：nodeHost.browserProxy.enabled=false
- Gateway 端：gateway.nodes.browser.mode="off"

Browserless（託管遠端 CDP）

Browserless 是一個託管的 Chromium 服務，透過 HTTPS 公開 CDP 端點。你可以將 OpenClaw 瀏覽器設定檔指向 Browserless 的區域端點，並以 API key 進行驗證。

範例：

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

注意事項：

將 <BROWSERLESS_API_KEY> 替換為你的真實 Browserless token。
選擇與你的 Browserless 帳號對應的區域端點（詳見其文件）。

直接 WebSocket CDP 供應商

有些託管瀏覽器服務公開的是直接 WebSocket 端點，而非標準的 HTTP CDP 探索（/json/version）。OpenClaw 兩種都支援：

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

Browserbase

Browserbase 是一個雲端平台，提供內建驗證碼解決、隱匿模式和住宅代理的無頭瀏覽器。

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

注意事項：

註冊帳號，從總覽儀表板複製你的 API Key。
將 <BROWSERBASE_API_KEY> 替換為你的真實 Browserbase API key。
Browserbase 在 WebSocket 連線時自動建立瀏覽器工作階段，不需要手動建立。
免費方案允許一個並行工作階段和每月一小時的瀏覽器使用時間。付費方案的限制請參閱定價。
完整的 API 參考、SDK 指南和整合範例請參閱 Browserbase 文件。

安全性

核心概念：

瀏覽器控制僅限回環連線；存取透過 Gateway 的驗證或節點配對進行。
如果啟用了瀏覽器控制但未設定驗證，OpenClaw 會在啟動時自動產生 gateway.auth.token 並持久化到設定中。
Gateway 和任何節點主機請保持在私有網路上（Tailscale）；避免公開暴露。
遠端 CDP URL/token 視為機密資料；建議使用環境變數或密鑰管理工具。

遠端 CDP 建議：

盡可能使用加密端點（HTTPS 或 WSS）和短期 token。
避免將長期 token 直接嵌入設定檔。

設定檔（多瀏覽器）

OpenClaw 支援多個命名設定檔（路由設定）。設定檔類型：

openclaw 受管理：專屬的 Chromium 系列瀏覽器實例，有獨立的使用者資料目錄 + CDP 連接埠
遠端：明確的 CDP URL（在其他地方執行的 Chromium 系列瀏覽器）
擴充功能中繼：透過本地中繼 + Chrome 擴充功能控制你既有的 Chrome 分頁
既有工作階段：透過 Chrome DevTools MCP 自動連線到你既有的 Chrome 設定檔

預設值：

如果 openclaw 設定檔不存在會自動建立。
chrome 設定檔為 Chrome 擴充功能中繼內建（預設指向 http://127.0.0.1:18792）。
既有工作階段設定檔為可選，需用 --driver existing-session 建立。
本地 CDP 連接埠預設從 18800–18899 分配。
刪除設定檔會將其本地資料目錄移至垃圾桶。

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

Chrome 擴充功能中繼（使用你既有的 Chrome）

OpenClaw 也可以透過本地 CDP 中繼 + Chrome 擴充功能來驅動你既有的 Chrome 分頁（不需要另外開一個「openclaw」Chrome 實例）。

完整指南：Chrome 擴充功能

流程：

Gateway 在本地執行（同一台機器），或在瀏覽器所在的機器上執行節點主機。
本地中繼伺服器在回環 cdpUrl 上監聽（預設：http://127.0.0.1:18792）。
你點擊 OpenClaw Browser Relay 擴充功能圖示來附掛分頁（不會自動附掛）。
代理透過一般的 browser 工具控制該分頁，只要選擇正確的設定檔即可。

如果 Gateway 在其他地方執行，請在瀏覽器所在的機器上執行節點主機，Gateway 會代理瀏覽器操作。

沙箱化工作階段

如果代理工作階段已沙箱化，browser 工具可能預設使用 target="sandbox"（沙箱瀏覽器）。Chrome 擴充功能中繼接管需要主機端瀏覽器控制，因此請選擇：

以非沙箱化的工作階段執行，或
設定 agents.defaults.sandbox.browser.allowHostControl: true 並在呼叫工具時使用 target="host"。

設定步驟

載入擴充功能（開發者 / 未封裝模式）：

openclaw browser extension install

Chrome → chrome://extensions → 啟用「開發人員模式」
「載入未封裝項目」→ 選擇 openclaw browser extension path 輸出的目錄
釘選擴充功能，然後在你想控制的分頁上點擊它（徽章顯示 ON）。

使用：

CLI：openclaw browser --browser-profile chrome tabs
代理工具：browser 搭配 profile="chrome"

選擇性步驟：如果想用不同的名稱或中繼連接埠，可建立自訂設定檔：

openclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

注意事項：

此模式的大部分操作依賴 Playwright-on-CDP（截圖 / 快照 / 動作）。
再次點擊擴充功能圖示即可解除附掛。

透過 MCP 的 Chrome 既有工作階段

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

官方背景和設定參考：

建立設定檔：

openclaw browser create-profile \
  --name chrome-live \
  --driver existing-session \
  --color "#00AA00"

然後在 Chrome 中：

開啟 chrome://inspect/#remote-debugging
啟用遠端偵錯
保持 Chrome 執行，當 OpenClaw 附掛時核准連線提示

即時附掛測試：

openclaw browser --browser-profile chrome-live start
openclaw browser --browser-profile chrome-live status
openclaw browser --browser-profile chrome-live tabs
openclaw browser --browser-profile chrome-live snapshot --format ai

成功的樣子：

status 顯示 driver: existing-session
status 顯示 running: true
tabs 列出你已開啟的 Chrome 分頁
snapshot 從選定的即時分頁回傳 refs

附掛不成功時的檢查項目：

Chrome 版本為 144+
已在 chrome://inspect/#remote-debugging 啟用遠端偵錯
Chrome 顯示的附掛同意提示已接受
Gateway 或節點主機能夠啟動 npx chrome-devtools-mcp@latest --autoConnect

注意事項：

此路徑的風險高於隔離的 openclaw 設定檔，因為它可以在你已登入的瀏覽器工作階段中操作。
OpenClaw 不會為此驅動啟動 Chrome；它僅附掛到既有的工作階段。
OpenClaw 在此使用官方的 Chrome DevTools MCP --autoConnect 流程，而非舊版的預設設定檔遠端偵錯連接埠工作流程。
既有工作階段截圖支援頁面擷取和快照中的 --ref 元素擷取，但不支援 CSS --element 選擇器。
既有工作階段的 wait --url 支援精確、子字串和萬用字元模式，與其他瀏覽器驅動相同。wait --load networkidle 目前尚未支援。
部分功能仍需要擴充功能中繼或受管理瀏覽器路徑，例如 PDF 匯出和下載攔截。
中繼預設僅繫結回環。如果中繼需要從不同的網路命名空間存取（例如 Gateway 在 WSL2，Chrome 在 Windows），可將 browser.relayBindHost 設為明確的繫結位址如 0.0.0.0，同時保持周圍的網路私密且經過驗證。

WSL2 / 跨命名空間範例：

{
  browser: {
    enabled: true,
    relayBindHost: "0.0.0.0",
    defaultProfile: "chrome",
  },
}

隔離保證

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

瀏覽器選擇

本地啟動時，OpenClaw 依序選擇第一個可用的：

Chrome
Brave
Edge
Chromium
Chrome Canary

可透過 browser.executablePath 覆寫。

各平台：

macOS：檢查 /Applications 和 ~/Applications。
Linux：尋找 google-chrome、brave、microsoft-edge、chromium 等。
Windows：檢查常見安裝路徑。

控制 API（選用）

僅供本地整合使用，Gateway 公開一個小型回環 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
鉤子：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>。

如果設定了 Gateway 驗證，瀏覽器 HTTP 路由也需要驗證：

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

Playwright 需求

部分功能（navigate/act/AI 快照 / role 快照、元素截圖、PDF）需要 Playwright。如果未安裝 Playwright，這些端點會回傳清楚的 501 錯誤。ARIA 快照和基本截圖在 openclaw 受管理的 Chrome 上仍可使用。Chrome 擴充功能中繼驅動的 ARIA 快照和截圖則需要 Playwright。

如果出現 Playwright is not available in this gateway build，請安裝完整的 Playwright 套件（非 playwright-core）並重新啟動 Gateway，或重新安裝帶有瀏覽器支援的 OpenClaw。

Docker Playwright 安裝

如果你的 Gateway 在 Docker 中執行，避免使用 npx playwright（npm 覆寫衝突）。改用隨附的 CLI：

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。

運作原理（內部）

高層級流程：

一個小型控制伺服器接受 HTTP 請求。
它透過 CDP 連線到 Chromium 系列瀏覽器（Chrome/Brave/Edge/Chromium）。
進階操作（點擊 / 輸入 / 快照 / PDF）使用建立在 CDP 之上的 Playwright。
未安裝 Playwright 時，僅提供不需要 Playwright 的操作。

這種設計讓代理使用穩定、確定性的介面，同時允許你切換本地 / 遠端瀏覽器和設定檔。

CLI 快速參考

所有指令接受 --browser-profile <name> 來指定設定檔。所有指令也接受 --json 以取得機器可讀的輸出（穩定的 payload）。

基本操作：

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

檢視：

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
openclaw browser errors --clear
openclaw browser requests --filter api --clear
openclaw browser pdf
openclaw browser responsebody "**/api" --max-chars 5000

操作：

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

狀態：

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 是預備呼叫；請在觸發檔案選擇器 / 對話框的點擊 / 按鍵之前執行。
下載和追蹤的輸出路徑限制在 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 後的預設）：回傳帶有數字 refs 的 AI 快照（aria-ref="<n>"）。
- --format aria：回傳無障礙樹（無 refs；僅供檢視）。
- --efficient（或 --mode efficient）：精簡角色快照預設（interactive + compact + depth + 較低的 maxChars）。
- 設定預設值（僅限工具 / CLI）：設定 browser.snapshotDefaults.mode: "efficient" 可在呼叫者未傳入 mode 時使用精簡快照（請參閱 Gateway 設定）。
- 角色快照選項（--interactive、--compact、--depth、--selector）會強制產生帶有 ref=e12 類 refs 的角色快照。
- --frame "<iframe selector>" 將角色快照範圍限制在 iframe 中（搭配 e12 類角色 refs）。
- --interactive 輸出扁平、容易挑選的互動元素列表（最適合驅動操作）。
- --labels 在視窗範圍截圖上疊加 ref 標籤（輸出 MEDIA:<path>）。
click/type 等需要來自 snapshot 的 ref（數字 12 或角色 ref e12）。刻意不支援 CSS 選擇器進行操作。

快照和 refs

OpenClaw 支援兩種「快照」風格：

AI 快照（數字 refs）：openclaw browser snapshot（預設；--format ai）
- 輸出：包含數字 refs 的文字快照。
- 操作：openclaw browser click 12、openclaw browser type 23 "hello"。
- 內部透過 Playwright 的 aria-ref 解析 ref。
角色快照（角色 refs 如 e12）：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 標籤疊加的視窗截圖。

Ref 行為：

Refs 不會在頁面導航間保持穩定；如果操作失敗，請重新執行 snapshot 並使用新的 ref。
如果角色快照使用了 --frame，角色 refs 的範圍會限制在該 iframe 中，直到下一次角色快照為止。

Wait 進階功能

你可以等待的不僅是時間 / 文字：

等待 URL（Playwright 支援萬用字元）：
- openclaw browser wait --url "**/dash"
等待載入狀態：
- openclaw browser wait --load networkidle
等待 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

除錯工作流程

操作失敗時（例如「not visible」、「strict mode violation」、「covered」）：

openclaw browser snapshot --interactive
使用 click <ref> / type <ref>（interactive 模式下建議用角色 refs）
仍然失敗：openclaw browser highlight <ref> 查看 Playwright 指向的目標
頁面行為異常時：
- openclaw browser errors --clear
- openclaw browser requests --filter api --clear
深度除錯：錄製追蹤：
- openclaw browser trace start
- 重現問題
- openclaw browser trace stop（輸出 TRACE:<path>）

JSON 輸出

--json 用於腳本和結構化工具整合。

範例：

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

角色快照的 JSON 輸出包含 refs 和一個小型 stats 區塊（lines/chars/refs/interactive），讓工具可以評估 payload 的大小和密度。

狀態和環境控制

這些在「讓網站表現得像 X」的工作流程中很實用：

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 basic 驗證：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 / 節點主機請保持私密（回環或僅限 tailnet）。
遠端 CDP 端點很強大；請用隧道保護。

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

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // 可選的精確允許
    },
  },
}

疑難排解

Linux 特有的問題（特別是 snap Chromium）請參閱瀏覽器疑難排解。

WSL2 Gateway + Windows Chrome 跨主機架構請參閱 WSL2 + Windows + 遠端 Chrome CDP 疑難排解。

代理工具 + 控制方式

代理取得一個工具來進行瀏覽器自動化：

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

對應方式：

browser snapshot 回傳穩定的 UI 樹（AI 或 ARIA）。
browser act 使用快照的 ref ID 來點擊 / 輸入 / 拖曳 / 選取。
browser screenshot 擷取像素（整頁或元素）。
browser 接受：
- profile 選擇命名的瀏覽器設定檔（openclaw、chrome 或遠端 CDP）。
- target（sandbox | host | node）選擇瀏覽器在哪裡。
- 沙箱化工作階段中，target: "host" 需要 agents.defaults.sandbox.browser.allowHostControl=true。
- 省略 target 時：沙箱化工作階段預設為 sandbox，非沙箱化工作階段預設為 host。
- 如果有已連線的具瀏覽器功能的節點，工具可能自動導向該節點，除非你明確指定 target="host" 或 target="node"。

這讓代理保持確定性，避免使用脆弱的選擇器。

瀏覽器（OpenClaw 受管理模式）

提供的功能

快速上手

設定檔：openclaw vs chrome

設定

使用 Brave（或其他 Chromium 系列瀏覽器）

本地與遠端控制

節點瀏覽器代理（零設定預設）

Browserless（託管遠端 CDP）

直接 WebSocket CDP 供應商

Browserbase

安全性

設定檔（多瀏覽器）

Chrome 擴充功能中繼（使用你既有的 Chrome）

沙箱化工作階段

設定步驟

透過 MCP 的 Chrome 既有工作階段

隔離保證

瀏覽器選擇

控制 API（選用）

Playwright 需求

Docker Playwright 安裝

運作原理（內部）

CLI 快速參考

快照和 refs

Wait 進階功能

除錯工作流程

JSON 輸出

狀態和環境控制

安全性和隱私

疑難排解

代理工具 + 控制方式

設定檔：`openclaw` vs `chrome`