瀏覽器（OpenClaw 管理）

OpenClaw 管理的獨立瀏覽器環境，提供安全、隔離的代理自動化介面。

OpenClaw 可以運行一個專用的 Chrome/Brave/Edge/Chromium 配置檔，由代理控制。它與你的個人瀏覽器隔離，透過閘道內部的小型本地控制服務（僅限 loopback）管理。

初學者視角

將其視為一個獨立的、僅限代理的瀏覽器。
openclaw 配置檔不會觸及你的個人瀏覽器配置檔。
代理可以在安全的通道中開啟分頁、讀取頁面、點擊和輸入。
預設的 chrome 配置檔透過擴充功能中繼使用系統預設的 Chromium 瀏覽器；切換到 openclaw 以使用隔離的受管理瀏覽器。

提供的功能

名為 openclaw 的獨立瀏覽器配置檔（預設橘色主題）。
確定性的分頁控制（列出/開啟/聚焦/關閉）。
代理操作（click/type/drag/select）、快照、螢幕截圖、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”，請在設定中啟用（見下方）並重啟閘道。

配置檔：`openclaw` vs `chrome`

openclaw：受管理的隔離瀏覽器（不需要擴充功能）。
chrome：連接到你系統瀏覽器的擴充功能中繼（需要 OpenClaw 擴充功能附加到分頁）。

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

設定

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

{
  browser: {
    enabled: true, // 預設：true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // 預設信任網路模式
    },
    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" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

注意事項

瀏覽器控制服務在從 gateway.port 衍生的連接埠上綁定 loopback（預設：18791，即閘道 + 2）。中繼使用下一個連接埠（18792）。
若你覆寫閘道連接埠（gateway.port 或 OPENCLAW_GATEWAY_PORT），衍生的瀏覽器連接埠會跟著偏移以保持在同一「家族」。
cdpUrl 未設定時預設為中繼連接埠。
remoteCdpTimeoutMs 適用於遠端（非 loopback）CDP 可達性檢查。
瀏覽器導覽/開啟分頁在導覽前受 SSRF 保護，並在導覽後對最終 http(s) URL 進行盡力而為的重新檢查。
browser.ssrfPolicy.dangerouslyAllowPrivateNetwork 預設為 true（信任網路模型）。設為 false 以進行嚴格的僅公開網路瀏覽。
attachOnly: true 意味著「永不啟動本地瀏覽器；僅在已運行時附加」。
color + 每個配置檔的 color 為瀏覽器 UI 著色，讓你能看到哪個配置檔處於活動狀態。
預設配置檔為 chrome（擴充功能中繼）。使用 defaultProfile: "openclaw" 切換為受管理瀏覽器。
自動偵測順序：系統預設瀏覽器（若為 Chromium 系列）；否則 Chrome -> Brave -> Edge -> Chromium -> Chrome Canary。

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

本地 vs 遠端控制

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

遠端 CDP URL 可包含驗證：

查詢 token（例如 https://provider.example?token=<token>）
HTTP Basic auth（例如 https://user:pass@provider.example）

OpenClaw 在呼叫 /json/* 端點和連接到 CDP WebSocket 時保留驗證。建議使用環境變數或密鑰管理器取代直接將 token 寫入設定檔。

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

若你在有瀏覽器的機器上運行節點主機，OpenClaw 可以在不需要額外瀏覽器設定的情況下自動將瀏覽器工具呼叫路由到該節點。這是遠端閘道的預設路徑。

注意事項

節點主機透過代理命令公開其本地瀏覽器控制伺服器。
配置檔來自節點自己的 browser.profiles 設定（與本地相同）。
若不需要可停用：
- 在節點上：nodeHost.browserProxy.enabled=false
- 在閘道上：gateway.nodes.browser.mode="off"

Browserless（託管遠端 CDP）

Browserless 是一個託管的 Chromium 服務，透過 HTTPS 公開 CDP 端點。你可以將 OpenClaw 瀏覽器配置檔指向 Browserless 區域端點並使用 API 金鑰驗證。

範例

{
  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 帳戶匹配的區域端點。

安全性

關鍵概念

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

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

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

配置檔（多瀏覽器）

OpenClaw 支援多個具名配置檔（路由設定）。配置檔可以是：

openclaw 管理：具有自己使用者資料目錄 + CDP 連接埠的專用 Chromium 系列瀏覽器實例
遠端：明確的 CDP URL（在別處運行的 Chromium 系列瀏覽器）
擴充功能中繼：透過本地中繼 + Chrome 擴充功能使用你現有的 Chrome 分頁

預設值

若 openclaw 配置檔不存在會自動建立。
chrome 配置檔為 Chrome 擴充功能中繼的內建設定（預設指向 http://127.0.0.1:18792）。
本地 CDP 連接埠預設從 18800-18899 分配。
刪除配置檔會將其本地資料目錄移至垃圾桶。

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

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

OpenClaw 也可以透過本地 CDP 中繼 + Chrome 擴充功能驅動你現有的 Chrome 分頁（不需要單獨的 “openclaw” Chrome 實例）。

完整指南：Chrome 擴充功能

流程

閘道在本地運行（同一機器）或節點主機在瀏覽器機器上運行。
本地中繼伺服器在 loopback cdpUrl 上監聽（預設：http://127.0.0.1:18792）。
你點擊分頁上的 OpenClaw Browser Relay 擴充功能圖示來附加（不會自動附加）。
代理透過選擇正確的配置檔，使用正常的 browser 工具控制該分頁。

設定

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

openclaw browser extension install

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

使用它：

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

隔離保證

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

瀏覽器選擇

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

Chrome
Brave
Edge
Chromium
Chrome Canary

可透過 browser.executablePath 覆寫。

平台

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

快照和參考

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 標籤的視窗截圖。

參考行為

參考在導覽之間不穩定；若操作失敗，重新執行 snapshot 並使用新的參考。
若角色快照使用 --frame 拍攝，角色參考的範圍限定在該 iframe 內直到下次角色快照。

等待進階功能

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

等待 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>（互動模式中偏好角色參考）
若仍然失敗：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>）

安全性與隱私

openclaw 瀏覽器配置檔可能包含已登入的工作階段；應將其視為敏感資料。
browser act kind=evaluate / openclaw browser evaluate 和 wait --fn 在頁面上下文中執行任意 JavaScript。提示注入可能引導此操作。若不需要可透過 browser.evaluateEnabled=false 停用。
對於登入和反機器人注意事項（X/Twitter 等），請參閱瀏覽器登入 + X/Twitter 發文。
保持閘道/節點主機為私有（loopback 或僅限 tailnet）。
遠端 CDP 端點功能強大；請進行隧道傳輸和保護。

疑難排解

對於 Linux 特定問題（特別是 snap Chromium），請參閱瀏覽器疑難排解。

代理工具 + 控制方式

代理取得一個工具用於瀏覽器自動化：

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

對應方式

browser snapshot 回傳穩定的 UI 樹狀結構（AI 或 ARIA）。
browser act 使用快照 ref ID 來 click/type/drag/select。
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 系列瀏覽器）

CLI 範例

設定範例

本地 vs 遠端控制

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

注意事項

Browserless（託管遠端 CDP）

範例

注意事項

安全性

關鍵概念

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

配置檔（多瀏覽器）

預設值

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

流程

設定

隔離保證

瀏覽器選擇

平台

快照和參考

參考行為

等待進階功能

除錯工作流程

安全性與隱私

疑難排解

代理工具 + 控制方式

對應方式

目錄

配置檔：`openclaw` vs `chrome`