瀏覽器（由 OpenClaw 管理）

Documentation Index

Fetch the complete documentation index at: https://docs.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 模擬覆寫（視窗大小、色彩配置、地區設定、時區、離線模式，以及類似狀態），即使 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] 或沒有 /devtools/... 路徑的 wss://host[:port]（例如 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",
      },
    },
  },
}

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

​

安全性

• 瀏覽器控制僅限 loopback；存取流程會經由 Gateway 的驗證或 Node 配對。
• 獨立的 loopback 瀏覽器 HTTP API 僅使用共享密鑰驗證： Gateway token bearer auth、x-openclaw-password，或使用已設定 Gateway 密碼的 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 主機保留在私人網路（Tailscale）上；避免公開暴露。
• 將遠端 CDP URL/token 視為祕密；優先使用環境變數或祕密管理器。

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

​

設定檔（多瀏覽器）

• openclaw-managed：專用的 Chromium-based browser 執行個體，具有自己的使用者資料目錄 + CDP 連接埠
• remote：明確的 CDP URL（在其他地方執行的 Chromium-based browser）
• 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-based browser 版本是 144+
• 已在該瀏覽器的檢查頁面中啟用遠端偵錯
• 瀏覽器已顯示附加同意提示，而且你已接受
• openclaw doctor 會遷移舊的 extension-based browser 設定，並檢查預設自動連線設定檔所需的 Chrome 是否已在本機安裝，但它無法替你啟用瀏覽器端遠端偵錯

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

• 此路徑比隔離的 openclaw 設定檔風險更高，因為它可以在你的已登入瀏覽器工作階段內操作。
• OpenClaw 不會為此 driver 啟動瀏覽器；它只會附加。
• OpenClaw 在此使用官方 Chrome DevTools MCP --autoConnect 流程。如果設定了 userDataDir，它會被傳遞以鎖定該使用者資料目錄。
• 既有工作階段可以附加在所選主機上，或透過已連線的瀏覽器 Node 附加。如果 Chrome 位於其他地方且沒有瀏覽器 Node 已連線，請改用遠端 CDP 或 Node 主機。

​

自訂 Chrome MCP 啟動

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

​

隔離保證

• 專用使用者資料目錄：絕不觸碰你的個人瀏覽器設定檔。
• 專用連接埠：避免 9222，以防與開發工作流程衝突。
• 確定性的分頁控制：tabs 會先回傳 suggestedTargetId，接著是穩定的 tabId 控制代碼，例如 t1、選用標籤，以及原始 targetId。 Agent 應重用 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 位置。
• 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>
  • 當設定 loopback 外部 CDP 服務但未設定 attachOnly: true 時，Port <port> is in use for profile "<name>" but not by openclaw
• 導覽 SSRF 封鎖：
  • 當 start 和 tabs 仍可運作時，open、navigate、snapshot 或開啟分頁流程因瀏覽器/網路政策錯誤而失敗

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 政策物件。
• 對於 local loopback openclaw 受管理設定檔，CDP 健康檢查會刻意略過 OpenClaw 自有本機控制平面的瀏覽器 SSRF 可達性強制檢查。
• 導覽保護是分開的。成功的 start 或 tabs 結果不代表後續的 open 或 navigate 目標被允許。

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

​

Agent 工具 + 控制如何運作

• 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。
  • 如果已連線具備瀏覽器能力的節點，工具可能會自動路由到該節點，除非你固定指定 target="host" 或 target="node"。

​

相關

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