浏览器（由 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，在启用浏览器 插件后，用于教智能体快照、 稳定标签页、失效引用和人工阻塞恢复循环。
• 可选的多配置文件支持（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/验证码或 摄像头/麦克风阻塞报告为需要人工操作，而不是猜测。

​

缺少浏览器命令或工具

{
  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 控制服务，并且可以启动本地浏览器。
• 远程控制（节点主机）： 在拥有浏览器的机器上运行节点主机；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）

​

节点浏览器代理（零配置默认值）

• 节点主机通过代理命令暴露其本地浏览器控制服务器。
• 配置文件来自节点自己的 browser.profiles 配置（与本地相同）。
• nodeHost.browserProxy.allowProfiles 是可选的。将它留空可使用旧版/默认行为：所有已配置的配置文件都可通过代理访问，包括配置文件创建/删除路由。
• 如果设置 nodeHost.browserProxy.allowProfiles，OpenClaw 会将其视为最小权限边界：只能指定允许列表中的配置文件，并且代理表面上的持久配置文件创建/删除路由会被阻止。
• 如果你不需要它，可以禁用：
  • 在节点上：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 根路径 - 没有 /devtools/... 路径的 ws://host[:port] 或 wss://host[:port]（例如 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",
    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 key。
• Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此无需 手动创建会话步骤。
• 免费层允许一个并发会话和每月一个浏览器小时。 付费计划限制请参见 定价。
• 完整 API 参考、SDK 指南和集成示例请参见 Browserbase 文档。

​

安全

• 浏览器控制仅限 local loopback；访问通过 Gateway 网关的身份验证或节点配对流程进行。
• 独立的 loopback 浏览器 HTTP API 仅使用共享密钥身份验证： Gateway 网关令牌 bearer 身份验证、x-openclaw-password，或使用已配置 Gateway 网关密码的 HTTP Basic 身份验证。
• Tailscale Serve 身份标头和 gateway.auth.mode: "trusted-proxy" 不会验证这个独立的 loopback 浏览器 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：具有自己的用户数据目录 + CDP 端口的专用 Chromium 系浏览器实例
• remote：显式 CDP URL（在其他位置运行的 Chromium 系浏览器）
• 现有会话：通过 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

• 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 返回来自所选实时标签页的引用

• 目标 Chromium 系浏览器版本为 144+
• 已在该浏览器的检查页面启用远程调试
• 浏览器已显示附加同意提示，并且你已接受
• openclaw doctor 会迁移旧的基于插件的浏览器配置，并检查默认自动连接配置文件所需的 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。 Agents 应复用 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 外部 CDP 服务但没有 attachOnly: true 时，出现 Port <port> is in use for profile "<name>" but not by openclaw
• 导航 SSRF 阻止：
  • 当 start 和 tabs 仍可工作时，open、navigate、快照或打开标签页流程因浏览器/网络策略错误而失败

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，浏览器配置也会默认为故障关闭的 SSRF 策略对象。
• 对于本地 loopback 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 捕获像素（整页、元素或带标签的引用）。
• 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"。

​

相关内容

• 工具概览 - 所有可用的智能体工具
• 沙箱隔离 - 沙箱隔离环境中的浏览器控制
• 安全 - 浏览器控制风险与加固