瀏覽器（由 OpenClaw 管理）

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 可以把它想成一個獨立、僅供代理程式使用的瀏覽器。
• openclaw 設定檔不會碰觸你的個人瀏覽器設定檔。
• 代理程式可以在安全通道中開啟分頁、讀取頁面、點擊和輸入。
• 內建的 user 設定檔會透過 Chrome MCP 附加到你實際已登入的 Chrome 工作階段。

​

你會得到什麼

• 一個名為 openclaw 的獨立瀏覽器設定檔（預設為橘色強調色）。
• 確定性的分頁控制（列出/開啟/聚焦/關閉）。
• 代理程式動作（點擊/輸入/拖曳/選取）、快照、螢幕截圖、PDF。
• 隨附的 browser-automation skill，會在瀏覽器 Plugin 啟用時，教導代理程式快照、穩定分頁、過期參照，以及手動阻礙復原迴圈。
• 選用的多設定檔支援（openclaw、work、remote、…）。

​

快速開始

openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw doctor --deep
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

​

Plugin 控制

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

​

代理程式指引

{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

• browser 工具描述包含精簡且永遠啟用的契約：選擇 正確的設定檔、將參照維持在同一個分頁、使用 tabId/標籤進行分頁 目標指定，並在多步驟工作中載入瀏覽器 skill。
• 隨附的 browser-automation skill 包含較長的操作迴圈： 先檢查狀態/分頁、標記工作分頁、動作前擷取快照、UI 變更後重新擷取快照、 對過期參照復原一次，並將登入/2FA/captcha 或 攝影機/麥克風阻礙回報為需要手動動作，而不是猜測。

​

缺少瀏覽器命令或工具

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

​

設定檔：openclaw 與 user

• openclaw：受管理、隔離的瀏覽器（不需要擴充功能）。
• user：內建的 Chrome MCP 附加設定檔，用於你的實際已登入 Chrome 工作階段。

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

​

設定

{
  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)
    localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms)
    localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms)
    actionTimeoutMs: 60000, // default browser act timeout (ms)
    tabCleanup: {
      enabled: true, // default: true
      idleMinutes: 120, // set 0 to disable idle cleanup
      maxTabsPerSession: 8, // set 0 to disable the per-session cap
      sweepMinutes: 5,
    },
    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",
        headless: true,
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      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" },
    },
  },
}

​

使用 Brave 或其他 Chromium 系瀏覽器

openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
  },
}

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

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

​

本機與遠端控制

• 本機控制（預設）： Gateway 會啟動 loopback 控制服務，並且可以啟動本機瀏覽器。
• 遠端控制（Node 主機）： 在有瀏覽器的機器上執行 Node 主機；Gateway 會將瀏覽器操作代理給它。
• 遠端 CDP： 設定 browser.profiles.<name>.cdpUrl（或 browser.cdpUrl）以 附加到遠端 Chromium 系瀏覽器。在此情況下，OpenClaw 不會啟動本機瀏覽器。
• 對於 loopback 上由外部管理的 CDP 服務（例如在 Docker 中發布到 127.0.0.1 的 Browserless），也請設定 attachOnly: true。沒有 attachOnly 的 loopback CDP 會被視為本機 OpenClaw 管理的瀏覽器設定檔。
• headless 只會影響 OpenClaw 啟動的本機受管理設定檔。它不會重新啟動或變更現有工作階段或遠端 CDP 瀏覽器。
• executablePath 遵循相同的本機受管理設定檔規則。在 執行中的本機受管理設定檔上變更它，會將該設定檔標記為需要重新啟動/協調，使 下次啟動使用新的二進位檔。

• 本機受管理設定檔：openclaw browser stop 會停止 OpenClaw 啟動的瀏覽器程序
• 僅附加和遠端 CDP 設定檔：openclaw browser stop 會關閉作用中的 控制工作階段，並釋放 Playwright/CDP 模擬覆寫（viewport、 色彩配置、地區設定、時區、離線模式，以及類似狀態），即使 OpenClaw 並未啟動任何瀏覽器程序

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

​

Node 瀏覽器代理（零配置預設）

• Node 主機會透過代理命令公開其本機瀏覽器控制伺服器。
• 設定檔來自 Node 自己的 browser.profiles 配置（與本機相同）。
• nodeHost.browserProxy.allowProfiles 是選用的。將它留空可使用舊版/預設行為：所有已配置的設定檔都可透過代理存取，包括設定檔建立/刪除路由。
• 如果你設定 nodeHost.browserProxy.allowProfiles，OpenClaw 會將它視為最低權限邊界：只能以允許清單中的設定檔為目標，且代理介面上的持久設定檔建立/刪除路由會被封鎖。
• 如果你不想使用它，請停用：
  • 在 Node 上：nodeHost.browserProxy.enabled=false
  • 在 Gateway 上：gateway.nodes.browser.mode="off"

​

Browserless（託管遠端 CDP）

{
  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 權杖。
• 選擇與你的 Browserless 帳戶相符的區域端點（請參閱其文件）。
• 如果 Browserless 提供 HTTPS 基底 URL，你可以將它轉換為 wss:// 以進行直接 CDP 連線，或保留 HTTPS URL，讓 OpenClaw 探索 /json/version。

​

同一主機上的 Browserless Docker

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    profiles: {
      browserless: {
        cdpUrl: "ws://127.0.0.1:3000",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}

​

直接 WebSocket CDP 提供者

• HTTP(S) 探索 - http://host[:port] 或 https://host[:port]。 OpenClaw 會呼叫 /json/version 來探索 WebSocket 偵錯工具 URL，然後 連線。沒有 WebSocket 後援。
• 直接 WebSocket 端點 - ws://host[:port]/devtools/<kind>/<id> 或 帶有 /devtools/browser|page|worker|shared_worker|service_worker/<id> 路徑的 wss://...。OpenClaw 會直接透過 WebSocket 交握連線，並完全略過 /json/version。
• 裸 WebSocket 根目錄 - ws://host[:port] 或 wss://host[:port]，且沒有 /devtools/... 路徑（例如 Browserless、 Browserbase）。OpenClaw 會先嘗試 HTTP /json/version 探索（將配置正規化為 http/https）； 如果探索傳回 webSocketDebuggerUrl，就會使用它，否則 OpenClaw 會後援到裸根目錄上的直接 WebSocket 交握。如果宣告的 WebSocket 端點拒絕 CDP 交握，但已配置的裸根目錄 接受它，OpenClaw 也會後援到該根目錄。這讓指向本機 Chrome 的裸 ws:// 仍可連線，因為 Chrome 只接受 /json/version 中特定每目標路徑上的 WebSocket 升級；同時託管提供者在其探索 端點宣告不適合 Playwright CDP 的短效 URL 時，仍可使用其根 WebSocket 端點。

​

Browserbase

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

• 註冊，並從 Overview dashboard 複製你的 API Key。
• 將 <BROWSERBASE_API_KEY> 替換為你真正的 Browserbase API 金鑰。
• Browserbase 會在 WebSocket 連線時自動建立瀏覽器工作階段，因此不需要 手動建立工作階段。
• 免費方案允許一個並行工作階段，以及每月一個瀏覽器小時。 付費方案限制請參閱定價。
• 完整 API 參考、SDK 指南和整合範例請參閱 Browserbase 文件。

​

安全性

• 瀏覽器控制僅限迴路；存取流程會經過 Gateway 的驗證或節點配對。
• 獨立的迴路瀏覽器 HTTP API 僅使用共享密鑰驗證： gateway 權杖 bearer 驗證、x-openclaw-password，或使用已設定 gateway 密碼的 HTTP Basic 驗證。
• Tailscale Serve 身分標頭和 gateway.auth.mode: "trusted-proxy" 不會驗證這個獨立迴路瀏覽器 API。
• 如果已啟用瀏覽器控制，但未設定共享密鑰驗證，OpenClaw 會為該次啟動產生僅限執行階段的 gateway 權杖。如果用戶端需要跨重新啟動保持穩定的密鑰，請明確設定 gateway.auth.token、gateway.auth.password、OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD。
• 當 gateway.auth.mode 已經是 password、none 或 trusted-proxy 時，OpenClaw 不會自動產生該權杖。
• 將 Gateway 和任何節點主機保留在私人網路（Tailscale）上；避免公開暴露。
• 將遠端 CDP URL/權杖視為機密；優先使用環境變數或機密管理工具。

• 盡可能優先使用加密端點（HTTPS 或 WSS）和短效權杖。
• 避免直接在設定檔中嵌入長效權杖。

​

設定檔（多瀏覽器）

• openclaw-managed：專用的 Chromium 系瀏覽器執行個體，具有自己的使用者資料目錄 + CDP 連接埠
• remote：明確的 CDP URL（在其他位置執行的 Chromium 系瀏覽器）
• existing session：透過 Chrome DevTools MCP 自動連線使用你現有的 Chrome 設定檔

• 如果缺少，會自動建立 openclaw 設定檔。
• user 設定檔是內建的，用於 Chrome MCP 現有工作階段附加。
• 除了 user 之外，現有工作階段設定檔需要選擇啟用；請使用 --driver existing-session 建立。
• 本機 CDP 連接埠預設從 18800-18899 分配。
• 刪除設定檔會將其本機資料目錄移到垃圾桶。

​

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

• Chrome for Developers: Use Chrome DevTools MCP with your browser session
• Chrome DevTools MCP README

• user

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

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

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

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

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+
• 已在該瀏覽器的檢查頁面啟用遠端偵錯
• 瀏覽器已顯示附加同意提示，且你已接受
• openclaw doctor 會遷移舊的 extension-based 瀏覽器設定，並檢查預設自動連線設定檔所需的 Chrome 是否已安裝在本機，但它無法替你啟用瀏覽器端遠端偵錯

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

• 這條路徑的風險高於隔離的 openclaw 設定檔，因為它可以在你已登入的瀏覽器工作階段中操作。
• OpenClaw 不會為這個驅動程式啟動瀏覽器；它只會附加。
• OpenClaw 在此使用官方 Chrome DevTools MCP --autoConnect 流程。如果已設定 userDataDir，它會被傳遞以鎖定該使用者資料目錄。
• 現有工作階段可以在選取的主機上附加，或透過已連線的瀏覽器節點附加。如果 Chrome 位於其他位置且未連線任何瀏覽器節點，請改用遠端 CDP 或節點主機。

​

自訂 Chrome MCP 啟動

• http(s)://... → --browserUrl <url>（DevTools HTTP 探索端點）。
• ws(s)://... → --wsEndpoint <url>（直接 CDP WebSocket）。

​

隔離保證

• 專用使用者資料目錄：絕不觸碰你的個人瀏覽器設定檔。
• 專用連接埠：避免使用 9222，以防與開發工作流程衝突。
• 確定性的分頁控制：tabs 會先傳回 suggestedTargetId，接著是穩定的 tabId 控制代碼，例如 t1、可選標籤，以及原始 targetId。代理程式應重複使用 suggestedTargetId；原始 ID 仍可用於偵錯和相容性。

​

瀏覽器選擇

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

• macOS：檢查 /Applications 和 ~/Applications。
• Linux：檢查 /usr/bin、/snap/bin、/opt/google、/opt/brave.com、/usr/lib/chromium 和 /usr/lib/chromium-browser 底下常見的 Chrome/Brave/Edge/Chromium 位置，另加 PLAYWRIGHT_BROWSERS_PATH 或 ~/.cache/ms-playwright 底下由 Playwright 管理的 Chromium。
• Windows：檢查常見安裝位置。

​

控制 API（可選）

​

疑難排解

​

CDP 啟動失敗與導覽 SSRF 封鎖

• CDP 啟動或就緒失敗表示 OpenClaw 無法確認瀏覽器控制平面正常。
• 導覽 SSRF 封鎖表示瀏覽器控制平面正常，但頁面導覽目標被政策拒絕。

• CDP 啟動或就緒失敗：
  • Chrome CDP websocket for profile "openclaw" is not reachable after start
  • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
  • 當已設定迴路外部 CDP 服務但未設定 attachOnly: true 時，Port <port> is in use for profile "<name>" but not by openclaw
• 導覽 SSRF 封鎖：
  • open、navigate、快照或分頁開啟流程在 start 和 tabs 仍可運作時，因瀏覽器/網路政策錯誤而失敗

openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com

• 如果 start 失敗並顯示 not reachable after start，請先疑難排解 CDP 就緒狀態。
• 如果 start 成功但 tabs 失敗，控制平面仍然不正常。請將其視為 CDP 可達性問題，而不是頁面導覽問題。
• 如果 start 和 tabs 成功但 open 或 navigate 失敗，瀏覽器控制平面已啟動，失敗位於導覽政策或目標頁面。
• 如果 start、tabs 和 open 全部成功，基本受管理瀏覽器控制路徑正常。

• 即使你沒有設定 browser.ssrfPolicy，瀏覽器設定也會預設為 fail-closed SSRF 政策物件。
• 對於本機迴路 openclaw 受管理設定檔，CDP 健康檢查會刻意略過 OpenClaw 自己本機控制平面的瀏覽器 SSRF 可達性強制執行。
• 導覽保護是分開的。成功的 start 或 tabs 結果不代表之後的 open 或 navigate 目標被允許。

• 預設不要放寬瀏覽器 SSRF 政策。
• 優先使用狹義主機例外，例如 hostnameAllowlist 或 allowedHostnames，而不是廣泛的私有網路存取。
• 只有在刻意受信任、需要且已審查私有網路瀏覽器存取的環境中，才使用 dangerouslyAllowPrivateNetwork: true。

​

代理工具 + 控制的運作方式

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

• browser snapshot 會傳回穩定的 UI 樹（AI 或 ARIA）。
• browser act 會使用快照 ref ID 來點擊/輸入/拖曳/選取。
• browser screenshot 會擷取像素（整頁、元素或已標記的 refs）。
• browser doctor 會檢查 Gateway、Plugin、設定檔、瀏覽器與分頁是否就緒。
• browser 接受：
  • profile 用於選擇具名瀏覽器設定檔（openclaw、chrome 或遠端 CDP）。
  • target（sandbox | host | node）用於選擇瀏覽器所在位置。
  • 在沙箱化工作階段中，target: "host" 需要 agents.defaults.sandbox.browser.allowHostControl=true。
  • 如果省略 target：沙箱化工作階段預設為 sandbox，非沙箱工作階段預設為 host。
  • 如果已連線支援瀏覽器的 Node，除非你固定使用 target="host" 或 target="node"，否則工具可能會自動路由到該 Node。

​

相關內容

• 工具概覽 - 所有可用的代理工具
• 沙箱化 - 沙箱化環境中的瀏覽器控制
• 安全性 - 瀏覽器控制風險與強化處理