浏览器（OpenClaw 管理）

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

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

• 把它看作一个独立的、仅供代理使用的浏览器。
• openclaw 配置文件不会影响你的个人浏览器配置文件。
• 代理可以在安全通道中打开标签页、读取页面、点击和输入。
• 内置的 user 配置文件通过 Chrome MCP 附加到你真实已登录的 Chrome 会话。

​

你将获得什么

• 一个名为 openclaw 的独立浏览器配置文件（默认橙色强调色）。
• 确定性的标签页控制（列出/打开/聚焦/关闭）。
• 代理动作（点击/输入/拖拽/选择）、快照、截图、PDF。
• 一个随附的 browser-automation 技能，教导代理在启用浏览器插件时使用快照、 稳定标签页、失效引用和手动阻塞恢复循环。
• 可选的多配置文件支持（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/标签进行标签页定位，并为多步骤工作加载浏览器技能。
• 随附的 browser-automation 技能包含更长的操作循环： 先检查状态/标签页、为任务标签页加标签、操作前先快照、UI 更改后重新快照、失效引用仅恢复一次，并将登录/2FA/captcha 或摄像头/麦克风阻塞报告为手动操作，而不是猜测。

​

缺少 browser 命令或工具

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

​

配置文件：openclaw vs user

• openclaw：受管理、隔离的浏览器（无需扩展）。
• user：内置的 Chrome MCP 附加配置文件，用于你的真实已登录 Chrome 会话。

• 默认：使用隔离的 openclaw 浏览器。
• 当现有登录会话很重要，且用户在电脑前可以点击/批准任何附加提示时，优先使用 profile="user"。
• profile 是你想要特定浏览器模式时的显式覆盖项。

​

配置

{
  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 超时（ms）
    remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时（ms）
    localLaunchTimeoutMs: 15000, // 本地受管理 Chrome 发现超时（ms）
    localCdpReadyTimeoutMs: 8000, // 本地受管理启动后 CDP 就绪超时（ms）
    actionTimeoutMs: 60000, // 默认浏览器 act 超时（ms）
    tabCleanup: {
      enabled: true, // 默认：true
      idleMinutes: 120, // 设为 0 可禁用空闲清理
      maxTabsPerSession: 8, // 设为 0 可禁用每会话上限
      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",
  },
}

​

本地控制 vs 远程控制

• 本地控制（默认）： Gateway 启动回环控制服务，并且可以启动本地浏览器。
• 远程控制（node host）： 在拥有浏览器的机器上运行 node host；Gateway 将浏览器操作代理到它。
• 远程 CDP： 设置 browser.profiles.<name>.cdpUrl（或 browser.cdpUrl）以 附加到远程基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
• 对于在回环上外部托管的 CDP 服务（例如在 Docker 中发布到 127.0.0.1 的 Browserless），也要设置 attachOnly: true。没有 attachOnly 的回环 CDP 会被视为本地的、由 OpenClaw 管理的浏览器配置文件。
• headless 只影响 OpenClaw 启动的本地托管配置文件。它不会重启或更改 existing-session 或远程 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 host 通过 代理命令 暴露其本地浏览器控制服务器。
• 配置文件来自 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> 或 wss://...，并带有 /devtools/browser|page|worker|shared_worker|service_worker/<id> 路径。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 key。
• Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此无需 手动创建会话步骤。
• 免费层允许一个并发会话和每月一个浏览器小时。 付费计划限制请参见 定价。
• 请参阅 Browserbase 文档 获取完整的 API 参考、SDK 指南和集成示例。

​

安全性

• 浏览器控制仅限回环；访问通过 Gateway 的认证或 node 配对进行。
• 独立的回环浏览器 HTTP API 仅使用 共享密钥认证： gateway token bearer 认证、x-openclaw-password，或使用 已配置的 gateway 密码进行 HTTP Basic 认证。
• Tailscale Serve 身份标头和 gateway.auth.mode: "trusted-proxy" 不会对该独立回环浏览器 API 进行认证。
• 如果启用了浏览器控制但未配置共享密钥认证，OpenClaw 会在启动时自动生成 gateway.auth.token 并将其持久化到配置中。
• 当 gateway.auth.mode 已经是 password、none 或 trusted-proxy 时，OpenClaw 不会 自动生成该令牌。
• 将 Gateway 和任何 node host 保持在私有网络中（Tailscale）；避免公开暴露。
• 将远程 CDP URL/令牌视为密钥；优先使用环境变量或 secrets manager。

• 尽可能优先使用加密端点（HTTPS 或 WSS）和短期令牌。
• 避免将长期有效的令牌直接嵌入配置文件。

​

配置文件（多浏览器）

• openclaw-managed：一个专用的基于 Chromium 的浏览器实例，拥有自己的用户数据目录 + CDP 端口
• remote：一个显式的 CDP URL（在其他地方运行的基于 Chromium 的浏览器）
• existing session：通过 Chrome DevTools MCP 自动连接使用你现有的 Chrome 配置文件

• 如果缺少 openclaw 配置文件，会自动创建。
• user 配置文件是内置的，用于 Chrome MCP existing-session 附加。
• existing-session 配置文件除了 user 之外都需要显式启用；使用 --driver existing-session 创建它们。
• 本地 CDP 端口默认从 18800–18899 分配。
• 删除配置文件会把其本地数据目录移动到废纸篓。

​

通过 Chrome DevTools MCP 使用现有会话

• Chrome for Developers：在浏览器会话中使用 Chrome DevTools MCP
• 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. 打开该浏览器用于远程调试的 inspect 页面。
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+
• 该浏览器的 inspect 页面中已启用远程调试
• 浏览器已显示连接同意提示，并且你已接受
• openclaw doctor 会迁移旧的基于扩展的浏览器配置，并检查默认自动连接配置文件的本地 Chrome 是否已安装，但它无法替你启用浏览器端的远程调试

• 当你需要用户已登录的浏览器状态时，请使用 profile="user"。
• 如果你使用自定义的现有会话配置文件，请传入那个明确的配置文件名。
• 只有在用户在电脑前可以批准连接提示时，才应选择此模式。
• Gateway 或节点主机可以启动 npx chrome-devtools-mcp@latest --autoConnect

• 这条路径比隔离的 openclaw 配置文件风险更高，因为它可以在你已登录的浏览器会话内执行操作。
• OpenClaw 不会为此驱动启动浏览器；它只会附加连接。
• OpenClaw 在这里使用官方 Chrome DevTools MCP 的 --autoConnect 流程。如果设置了 userDataDir，则会原样传递，以指向该用户数据目录。
• existing-session 可以在所选主机上连接，也可以通过已连接的浏览器节点连接。如果 Chrome 位于其他地方且没有连接浏览器节点，请改用远程 CDP 或节点主机。

​

自定义 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 启动失败 vs 导航 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>
  • 在未配置 attachOnly: true 的情况下，若配置了 loopback 外部 CDP 服务，则会出现 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 都成功，则基本的受管理浏览器控制路径是健康的。

• 即使你没有配置 browser.ssrfPolicy，浏览器配置默认也会使用 fail-closed 的 SSRF 策略对象。
• 对于本地 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 使用 snapshot 的 ref ID 来点击/输入/拖拽/选择。
• browser screenshot 捕获像素（整页、元素或带标签的 refs）。
• browser doctor 检查 Gateway、插件、配置文件、浏览器和标签页的就绪状态。
• browser 接受：
  • profile 用于选择命名的浏览器配置文件（openclaw、chrome，或远程 CDP）。
  • target（sandbox | host | node）用于选择浏览器所在位置。
  • 在沙箱会话中，target: "host" 需要 agents.defaults.sandbox.browser.allowHostControl=true。
  • 如果省略 target：沙箱会话默认为 sandbox，非沙箱会话默认为 host。
  • 如果连接了支持浏览器的节点，除非你固定 target="host" 或 target="node"，否则该工具可能会自动路由到该节点。

​

相关

• 工具概览 — 所有可用的代理工具
• 沙盒 — 沙盒环境中的浏览器控制
• 安全性 — 浏览器控制风险与加固