瀏覽器（由 OpenClaw 管理）

• 可以把它想成一個獨立、僅供代理程式使用的瀏覽器。openclaw 設定檔絕不會碰到你的個人瀏覽器設定檔。
• 代理程式會在這個隔離通道中開啟分頁、讀取頁面、點擊和輸入文字。
• 內建的 user 設定檔則會改用 Chrome DevTools MCP 連接到你真實已登入的 Chrome 工作階段。

​

你會得到什麼

• 名為 openclaw 的獨立瀏覽器設定檔（預設為橘色強調色）。
• 可預期的分頁控制（列出/開啟/聚焦/關閉）。
• 代理程式動作（點擊/輸入/拖曳/選取）、快照、螢幕截圖、PDF。
• 由 Playwright 支援的設定檔會將直接附件導覽儲存在受管理的下載目錄下，並在最終 URL 政策驗證後回傳 { url, suggestedFilename, path } 中繼資料。
• 由 Playwright 支援的代理程式動作若立即啟動一個或多個下載，會回傳包含相同受管理中繼資料的 downloads 陣列。
• 內建的 browser-automation skill，會在啟用瀏覽器外掛時教導代理程式快照、 穩定分頁、過期參照，以及手動阻擋復原迴圈。
• 選用的多設定檔支援（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

​

外掛控制

{
  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、chrome

• openclaw：受管理、隔離的瀏覽器（不需要擴充功能）。
• user：內建 Chrome DevTools MCP 連接設定檔，用於你的真實已登入 Chrome 工作階段。Chrome 會在 OpenClaw 第一次連接時顯示阻擋式「Allow remote debugging?」提示，因此必須有人在電腦前。
• chrome：內建 Chrome 擴充功能設定檔，用於你的真實已登入 Chrome 工作階段。即使桌前沒有人，也可從手機操作，因為它是透過 OpenClaw 瀏覽器擴充功能驅動分頁，而不是遠端除錯連接埠，所以不會出現「Allow remote debugging?」提示。

• 預設：使用隔離的 openclaw 瀏覽器。
• 當既有登入工作階段很重要，且使用者不在電腦前（Telegram、WhatsApp 等）時，優先使用 profile="chrome"（擴充功能）。
• 當既有登入工作階段很重要，且使用者在電腦前可核准連接提示時，優先使用 profile="user"（Chrome MCP）。
• 當你想要特定瀏覽器模式時，profile 是明確覆寫。

​

設定

{
  browser: {
    enabled: true, // default: true
    evaluateEnabled: true, // default: true; false disables act:evaluate (arbitrary JS)
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // 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,
    },
    // snapshotDefaults: { mode: "efficient" }, // default snapshot mode when the caller omits one
    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" },
    },
  },
}

​

螢幕截圖視覺（純文字模型支援）

{
  tools: {
    media: {
      image: {
        models: [
          { provider: "bytedance", model: "doubao-seed-2.0-pro" },
          // Add fallback candidates; first success wins
          { provider: "openai", model: "gpt-4o" },
        ],
      },
      // Shared media models also work when tagged for image support.
      // models: [{ provider: "openai", model: "gpt-4o", capabilities: ["image"] }],
    },
  },
  agents: {
    defaults: {
      // Existing image-model defaults are also honored.
      // imageModel: { primary: "openai/gpt-4o" },
    },
  },
}

1. 代理程式呼叫 browser screenshot，圖片會照常擷取到磁碟。
2. 瀏覽器工具會詢問既有的圖片理解執行階段，是否能使用已設定的媒體圖片模型、共享媒體模型、圖片模型預設值，或由驗證支援的圖片供應商來描述螢幕截圖。
3. 視覺模型會回傳文字描述，並以 wrapExternalContent（提示注入防護）包裝後，作為文字區塊而不是圖片區塊回傳給代理程式。
4. 如果圖片理解不可用、被略過或失敗，瀏覽器會退回回傳原始圖片區塊。

​

使用 Brave 或其他 Chromium-based 瀏覽器

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

​

本機與遠端控制

• **本機控制（預設）：**閘道會啟動 loopback 控制服務，並可以啟動本機瀏覽器。
• **遠端控制（節點主機）：**在擁有瀏覽器的機器上執行節點主機；閘道會將瀏覽器動作代理到它。
• **遠端 CDP：**設定 browser.profiles.<name>.cdpUrl（或 browser.cdpUrl）以 附加到遠端 Chromium-based 瀏覽器。在此情況下，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）

​

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

• 節點主機會透過代理命令公開其本機瀏覽器控制伺服器。
• 設定檔來自節點自己的 browser.profiles 組態（與本機相同）。
• 無論 allowProfiles 為何，代理命令永遠不允許持久的設定檔變更（create-profile、delete-profile、reset-profile）；請直接在節點上進行這些變更。
• nodeHost.browserProxy.allowProfiles 是選用的。留空以使用舊版/預設行為：所有已設定的設定檔仍可透過代理存取。
• 如果設定 nodeHost.browserProxy.allowProfiles，OpenClaw 會將其視為最小權限邊界，限制代理會鎖定哪些設定檔名稱。
• 如果你不想要它，請停用：
  • 在節點上：nodeHost.browserProxy.enabled=false
  • 在閘道上：gateway.nodes.browser.mode="off"（也接受 "auto" 以選取單一已連線瀏覽器節點，或 "manual" 以要求明確的節點參數）

​

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

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

​

Notte

{
  browser: {
    enabled: true,
    defaultProfile: "notte",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      notte: {
        cdpUrl: "wss://us-prod.notte.cc/sessions/connect?token=<NOTTE_API_KEY>",
        color: "#7C3AED",
      },
    },
  },
}

• 註冊並從主控台設定頁面複製你的 API Key。
• 將 <NOTTE_API_KEY> 替換為你的實際 Notte API 金鑰。
• Notte 會在 WebSocket 連線時自動建立瀏覽器工作階段，因此不需要手動建立工作階段。工作階段會在 WebSocket 中斷連線時銷毀。
• 如需目前免費層級限制與付費方案，請參閱定價。
• 如需完整 API 參考、SDK 指南與整合範例，請參閱 Notte 文件。

​

安全性

• 瀏覽器控制僅限回環；存取會透過閘道的驗證或節點配對流動。
• 獨立回環瀏覽器 HTTP API 僅使用共享密鑰驗證： 閘道權杖承載驗證、x-openclaw-password，或使用已設定閘道密碼的 HTTP Basic 驗證。
• Tailscale Serve 身分標頭與 gateway.auth.mode: "trusted-proxy" 不會驗證這個獨立回環瀏覽器 API。
• 如果已啟用瀏覽器控制且未設定共享密鑰驗證，OpenClaw 會在啟動時自動產生並保存瀏覽器控制憑證： 當 gateway.auth.mode 為 none 時是權杖，或當其為 trusted-proxy 時是密碼（透過 gateway.auth.password 保存，使程序外回環用戶端可解析）。當該模式已明確設定字串憑證，或當 gateway.auth.mode 為 password 時，會略過自動產生。
• 如果你想要由自己控制的穩定密鑰，而不是產生的密鑰，請明確設定 gateway.auth.token、gateway.auth.password、OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD。

• 盡可能偏好加密端點（HTTPS 或 WSS）與短效權杖。
• 避免將長效權杖直接嵌入設定檔。
• 將閘道與任何節點主機保留在私人網路（Tailscale）上；避免公開暴露。
• 將遠端 CDP URL/權杖視為密鑰；偏好使用環境變數或密鑰管理工具。

​

設定檔（多瀏覽器）

• openclaw-managed：具有專屬使用者資料目錄 + CDP 連接埠的專用 Chromium 型瀏覽器執行個體
• 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

{
  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+
• 該瀏覽器的檢查頁面已啟用遠端偵錯
• 瀏覽器已顯示附加同意提示，且你已接受
• 如果 Chrome 是使用明確的 --remote-debugging-port 啟動，請將 browser.profiles.<name>.cdpUrl 設為該 DevTools 端點，而不是依賴 Chrome MCP 自動連線
• openclaw doctor 會遷移舊的外掛型瀏覽器設定，並檢查預設自動連線設定檔是否已在本機安裝 Chrome，但它無法替你啟用瀏覽器端遠端偵錯

• 當你需要使用者已登入的瀏覽器狀態時，使用 profile="user"。
• 如果你使用自訂現有工作階段設定檔，請傳入該明確設定檔名稱。
• 只有在使用者位於電腦前可核准附加提示時，才選擇此模式。
• 閘道或節點主機可以產生 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）。

​

隔離保證

• 專用使用者資料目錄：絕不觸碰你的個人瀏覽器 profile。
• 專用連接埠：避免使用 9222，防止與開發工作流程衝突。
• 確定性的分頁控制：tabs 會先回傳 suggestedTargetId，接著回傳 穩定的 tabId handle（例如 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 位置，以及 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>
  • 當設定 loopback external CDP service 且未使用 attachOnly: true 時，Port <port> is in use for profile "<name>" but not by openclaw
• 導覽 SSRF 封鎖：
  • open、navigate、snapshot 或開啟分頁流程在 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 全部成功，基本的 managed-browser 控制路徑是健康的。

• 即使你未設定 browser.ssrfPolicy，瀏覽器設定也會預設為 fail-closed SSRF policy object。
• 對於本機 local loopback openclaw managed profile，CDP 健康檢查會刻意略過 OpenClaw 自己本機控制平面的瀏覽器 SSRF 可達性強制檢查。
• 導覽保護是分開的。成功的 start 或 tabs 結果不代表之後的 open 或 navigate 目標會被允許。

• 預設不要放寬瀏覽器 SSRF 政策。
• 優先使用範圍狹窄的 host 例外，例如 hostnameAllowlist 或 allowedHostnames，而不是廣泛的 private-network access。
• 只有在有意信任、需要並已審查 private-network browser access 的環境中，才使用 dangerouslyAllowPrivateNetwork: true。

​

Agent 工具 + 控制如何運作

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

• browser snapshot 會回傳穩定的 UI tree（AI 或 ARIA）。
• browser act 使用 snapshot ref ID 來 click/type/drag/select。
• browser screenshot 擷取像素（整頁、元素或有標籤的 refs）。
• browser doctor 檢查 Gateway、外掛、profile、瀏覽器和分頁就緒狀態。
• browser 接受：
  • profile 用來選擇具名瀏覽器 profile（openclaw、chrome 或 remote CDP）。
  • target (sandbox | host | node) 用來選擇瀏覽器所在位置。
  • 在 sandboxed sessions 中，target: "host" 需要 agents.defaults.sandbox.browser.allowHostControl=true。
  • 如果省略 target：sandboxed sessions 預設為 sandbox，non-sandbox sessions 預設為 host。
  • 如果已連線具備瀏覽器能力的節點，工具可能會自動路由到該節點，除非你指定 target="host" 或 target="node"。

​

相關

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