浏览器（OpenClaw 管理）

• 可以把它看作一个独立的、仅供代理使用的浏览器。openclaw 配置文件绝不会触碰您的个人浏览器配置文件。
• 代理会在这个隔离通道中打开标签页、读取页面、点击和输入。
• 内置的user配置文件则通过 Chrome DevTools MCP 连接到您真实的已登录 Chrome 会话。

​

你将获得什么

• 一个名为 openclaw 的独立浏览器配置文件（默认橙色强调色）。
• 确定性的标签页控制（列表/打开/聚焦/关闭）。
• 代理操作（点击/输入/拖拽/选择）、快照、截图、PDF。
• 针对可读页面文本的问答，无需返回完整快照。
• 基于 Playwright 的配置文件会将直接附件导航保存在受管理的下载目录中，并在最终 URL 策略验证后返回 { url, suggestedFilename, path } 元数据。
• 基于 Playwright 的代理操作在该操作立即开始一个或多个下载时，会返回一个包含相同受管理元数据的 downloads 数组。
• 一个捆绑的 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 或摄像头/麦克风阻塞报告为手动操作，而不是猜测。

​

缺少浏览器命令或工具

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

​

配置文件：openclaw、user、chrome

• openclaw：受管理、隔离的浏览器（无需扩展）。
• user：内置的 Chrome DevTools MCP 附加配置文件，用于你的 真实已登录 Chrome 会话。Chrome 在 OpenClaw 首次附加时会显示一个阻塞性的“允许远程调试？”提示，因此此时必须有人在电脑前。
• chrome：内置的 Chrome 扩展 配置文件，用于你的 真实已登录 Chrome 会话。即使电脑前无人，只要通过手机也能使用，因为它是通过 OpenClaw 浏览器扩展而不是远程调试端口来驱动标签页，因此不会出现“允许远程调试？”提示。

• 默认：使用隔离的 openclaw 浏览器。
• 当现有登录会话很重要且用户 不在电脑前（Telegram、WhatsApp 等）时，优先使用 profile="chrome"（扩展）。
• 当现有登录会话很重要且用户 在电脑前 以批准附加提示时，优先使用 profile="user"（Chrome MCP）。
• profile 是你想要特定浏览器模式时的显式覆盖选项。

​

配置

{
  browser: {
    enabled: true, // 默认：true
    evaluateEnabled: true, // 默认：true；false 会禁用 act:evaluate（任意 JS）
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // 仅针对受信任的私有网络访问选择启用
      // allowedHostnames: ["localhost"],
      // allowRfc2544BenchmarkRange: true, // 受信任的伪 IP 代理范围
      // allowIpv6UniqueLocalRange: true, // 受信任的伪 IP 代理 IPv6 范围
    },
    // cdpUrl: "http://127.0.0.1:18792", // 旧版单配置文件覆盖
    tabCleanup: {
      enabled: true, // 默认：true
    },
    // snapshotDefaults: { mode: "efficient" }, // 当调用方未指定时的默认 snapshot 模式
    defaultProfile: "openclaw",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800 },
      work: {
        cdpPort: 18801,
        headless: true,
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      user: {
        driver: "existing-session",
        attachOnly: true,
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222" },
    },
  },
}

​

标签页清理所有权

​

截图视觉能力（仅文本模型支持）

{
  tools: {
    media: {
      models: [
        { provider: "bytedance", model: "doubao-seed-2.0-pro", capabilities: ["image"] },
        // Add fallback candidates; first success wins
        { provider: "openai", model: "gpt-4o", capabilities: ["image"] },
      ],
    },
  },
  agents: {
    defaults: {
      // 现有的图像模型默认值也会被接受。
      // imageModel: { primary: "openai/gpt-4o" },
    },
  },
}

1. Agent 调用 browser screenshot，并像往常一样将图像捕获到磁盘。
2. 浏览器工具会询问现有的图像理解运行时：它是否可以使用已配置的媒体图像模型、共享媒体模型、图像模型默认值或带认证的图像提供方来描述该截图。
3. 视觉模型返回文本描述，该描述会被 wrapExternalContent（提示注入防护）包装后，作为文本块返回给 agent，而不是图像块。
4. 如果图像理解不可用、被跳过或失败，浏览器会回退为返回原始图像块。

​

使用 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 启动回环控制服务，并且可以启动本地浏览器。
• 远程控制（节点主机）： 在拥有浏览器的机器上运行节点主机；Gateway 将浏览器操作代理到它。
• 远程 CDP： 设置 browser.profiles.<name>.cdpUrl（或 browser.cdpUrl）以 附加到远程基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
• 对于在回环上外部托管的 CDP 服务（例如在 Docker 中发布到 127.0.0.1 的 Browserless），也要设置 attachOnly: true。没有 attachOnly 的回环 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:[email protected]）

​

Node 浏览器代理（零配置默认）

• 节点主机通过一个 代理命令 暴露其本地浏览器控制服务器。
• 配置文件来自节点自身的 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",
    profiles: {
      browserless: {
        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
      },
    },
  },
}

• 将 <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,
      },
    },
  },
}

​

直接 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 发现（将 scheme 规范化为 http／https）； 如果发现返回了 webSocketDebuggerUrl，则使用它，否则 OpenClaw 会回退到在裸根路径上的直接 WebSocket 握手。如果广告的 WebSocket 端点拒绝了 CDP 握手，但配置的裸根路径 接受了它，OpenClaw 也会回退到该根路径。这使得指向本地 Chrome 的裸 ws:// 仍然可以连接，因为 Chrome 只接受来自 /json/version 的特定目标路径上的 WebSocket 升级，而托管提供商仍然可以在其发现端点广告一个不适合 Playwright CDP 的短期 URL 时， 使用其根 WebSocket 端点。

​

Browserbase

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
      },
    },
  },
}

• 注册并从 概览面板复制你的 API 密钥。
• 将 <BROWSERBASE_API_KEY> 替换为你真实的 Browserbase API 密钥。
• Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此无需手动创建会话步骤。
• 查看 定价 以了解当前免费套餐限制和付费方案。
• 查看 Browserbase 文档 获取完整的 API 参考、SDK 指南和集成示例。

​

Notte

{
  browser: {
    enabled: true,
    defaultProfile: "notte",
    profiles: {
      notte: {
        cdpUrl: "wss://us-prod.notte.cc/sessions/connect?token=<NOTTE_API_KEY>",
      },
    },
  },
}

• 注册并从 控制台设置页面复制你的 API 密钥。
• 将 <NOTTE_API_KEY> 替换为你真实的 Notte API 密钥。
• Notte 会在 WebSocket 连接时自动创建浏览器会话，因此无需手动 创建会话步骤。会话会在 WebSocket 断开时销毁。
• 查看 定价 以了解当前免费套餐限制和付费方案。
• 查看 Notte 文档 获取完整的 API 参考、SDK 指南和集成示例。

​

安全

• 浏览器控制仅限本地回环访问；访问通过 Gateway 的认证或节点配对来完成。
• 独立的回环浏览器 HTTP API 仅使用 共享密钥认证： Gateway token bearer auth、x-openclaw-password，或使用已配置的 Gateway 密码进行 HTTP Basic auth。
• Tailscale Serve 身份头和 gateway.auth.mode: "trusted-proxy" 不会对这个独立的回环浏览器 API 进行认证。
• 如果启用了浏览器控制且未配置共享密钥认证，OpenClaw 会在启动时自动生成并持久化一个浏览器控制凭据： 当 gateway.auth.mode 为 none 时生成 token；当其为 trusted-proxy 时生成密码（通过 gateway.auth.password 持久化，因此进程外的回环客户端可以解析到它）。如果该模式下已经显式配置了字符串凭据，或者 gateway.auth.mode 为 password，则会跳过自动生成。
• 如果你想使用自己控制的稳定密钥，而不是自动生成的密钥，请显式配置 gateway.auth.token、gateway.auth.password、OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD。

• 尽量优先使用加密端点（HTTPS 或 WSS）和短期令牌。
• 避免在配置文件中直接嵌入长期有效的令牌。
• 将 Gateway 和任何节点主机放在私有网络（Tailscale）中；避免公开暴露。
• 将远程 CDP URL／令牌视为机密；优先使用环境变量或密钥管理器。

​

配置文件（多浏览器）

• 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：在浏览器会话中使用 Chrome DevTools MCP
• Chrome DevTools MCP README

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

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 页面中是否已启用远程调试
• 浏览器是否已显示并且你是否接受了附加连接提示
• 如果 Chrome 是通过显式的 --remote-debugging-port 启动的，请将 browser.profiles.<name>.cdpUrl 设置为该 DevTools 端点，而不要依赖 Chrome MCP 自动连接
• openclaw doctor 会迁移旧的基于扩展的浏览器配置，并检查默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它无法替你在浏览器侧启用远程调试

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

• 这条路径比隔离的 openclaw 配置文件风险更高，因为它可以 在你已登录的浏览器会话内执行操作。
• OpenClaw 不会为这个驱动启动浏览器；它只会进行附加。
• OpenClaw 在这里使用官方的 Chrome DevTools MCP --autoConnect 流程。如果 设置了 userDataDir，它会被传递过去，用于定位该用户数据目录。
• existing-session 可以在所选主机上附加，也可以通过已连接的 browser node 附加。如果 Chrome 在别处运行且没有连接 browser node， 请改用 remote CDP 或 node 主机。
• Chrome MCP 的目标和 snapshot refs 仅作用于一个 MCP 子进程。该进程 重启后，请再次运行 browser tabs，在进行特定目标工作前显式选择新的目标， 并在使用 refs 前获取新的 snapshot。每个 ref 只对其对应的目标和最新快照有效。 即使 URL 相同，旧别名也不会转移到替换后的标签页。
• Chrome DevTools MCP 目前通过进程本地的数字页面 ID 路由页面工具。 进程作用域的句柄可防止跨子进程替换复用，但在相邻工具调用之间， 进程内的 browser-context 替换仍可能重新定向某个动作。要实现完全原子化的路由， 需要上游页面工具支持稳定的目标 ID。

​

自定义 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 位置，以及 PLAYWRIGHT_BROWSERS_PATH 或 ~/.cache/ms-playwright 下由 Playwright 管理的 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 时，如果配置了外部回环 CDP 服务，将会出现 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 自身本地控制平面的 browser-SSRF 可达性强制检查。
• 导航保护是独立的。start 或 tabs 成功并不意味着后续的 open 或 navigate 目标一定被允许。

• 默认不要放宽浏览器 SSRF 策略。
• 优先使用范围狭窄且支持通配符的 allowedHostnames 例外，而不是广泛的私有网络访问。
• 仅在确实需要私有网络浏览器访问且经过审查的、明确受信任的环境中，使用 dangerouslyAllowPrivateNetwork: true。

​

Agent 工具 + 控制模式

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

• browser snapshot 返回一个稳定的 UI 树（AI 或 ARIA）。
• browser navigate 也会返回已加载页面的内联快照（高效 交互层，因此有效载荷保持紧凑且有界），所以 agent 不需要后续再调用 snapshot。批量 act 结果中，如果报告了 跨文档导航，也会包含同样的新鲜页面状态。解析为下载的导航则会跳过它。
• browser act 使用快照的 ref ID 来点击／输入／拖拽／选择。
• browser screenshot 捕获像素（整页、元素或带标签的 refs）。
• browser doctor 检查 Gateway、插件、配置文件、浏览器和标签页是否就绪。
• browser 接受：
  • profile 用于选择一个命名的浏览器配置文件（openclaw、chrome 或 remote CDP）。
  • target（sandbox | host | node）用于选择浏览器所在位置。
  • 在沙箱会话中，target: "host" 需要 agents.defaults.sandbox.browser.allowHostControl=true。
  • 如果省略 target：沙箱会话默认使用 sandbox，非沙箱会话默认使用 host。
  • 如果已连接一个支持浏览器的节点，除非你将 target="host" 或 target="node" 固定指定，否则该工具可能会自动路由到它。

​

相关内容

• 工具概览 - 所有可用的 agent 工具
• 沙箱环境 - 沙箱环境中的浏览器控制
• 安全性 - 浏览器控制风险与加固。