浏览器（OpenClaw 管理）

• 把它看作一个独立的、仅供代理使用的浏览器。
• 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" },
    },
  },
}

​

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

{
  tools: {
    media: {
      image: {
        models: [
          { provider: "bytedance", model: "doubao-seed-2.0-pro" },
          // 添加回退候选；首个成功者生效
          { provider: "openai", model: "gpt-4o" },
        ],
      },
      // 当共享媒体模型带有图像支持标记时也可使用。
      // models: [{ provider: "openai", model: "gpt-4o", capabilities: ["image"] }],
    },
  },
  agents: {
    defaults: {
      // 现有的图像模型默认值也会被接受。
      // imageModel: { primary: "openai/gpt-4o" },
    },
  },
}

1. 代理调用 browser screenshot → 像往常一样将图像捕获到磁盘。
2. 浏览器工具询问现有的图像理解运行时，它是否可以使用已配置的媒体图像模型、共享媒体模型、图像模型默认值或带认证的图像提供方来描述该截图。
3. 视觉模型返回文本描述，该描述会被 wrapExternalContent（提示注入防护）包装后，以文本块而非图像块的形式返回给代理。
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",
  },
}

​

本地控制 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:[email protected]）

​

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 发现（将 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",
      },
    },
  },
}

• 注册并从 概览仪表板 中复制你的 API Key。
• 将 <BROWSERBASE_API_KEY> 替换为你真实的 Browserbase API key。
• Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此无需 手动创建会话步骤。
• 免费层允许一个并发会话和每月一个浏览器小时。 付费计划限制请参见 定价。
• 请参阅 Browserbase 文档 获取完整的 API 参考、SDK 指南和集成示例。

​

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 key。
• Notte 会在 WebSocket 连接时自动创建浏览器会话，因此不需要手动创建会话步骤。WebSocket 断开连接时，会话会被销毁。
• 免费层允许五个并发会话和 100 个浏览器小时。付费计划限制请参见 定价。
• 请参阅 Notte 文档 获取完整的 API 参考、SDK 指南和集成示例。

​

Security

• 浏览器控制仅限回环；访问通过 Gateway 的认证或节点配对进行。
• 独立的回环浏览器 HTTP API 仅使用 共享密钥认证： gateway token bearer auth、x-openclaw-password，或使用 配置的 gateway 密码进行 HTTP Basic auth。
• Tailscale Serve 身份头和 gateway.auth.mode: "trusted-proxy" 不会对 这个独立的回环浏览器 API 进行认证。
• 如果已启用浏览器控制但未配置共享密钥认证，OpenClaw 会为该次启动生成一个仅运行时可用的 gateway token。如果客户端需要在 重启之间保持稳定的密钥，请显式配置 gateway.auth.token、gateway.auth.password、OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD。
• 当 gateway.auth.mode 已经是 password、none 或 trusted-proxy 时， OpenClaw 不会自动生成该 token。
• 将 Gateway 和任何节点主机放在私有网络（Tailscale）上；避免公开暴露。
• 将远程 CDP URL/令牌视为密钥；优先使用环境变量或密钥管理器。

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

​

配置文件（多浏览器）

• 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

• 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）。

​

Isolation Guarantees

• Dedicated user data directory: Never touches your personal browser profile.
• Dedicated port: Avoids using 9222 to prevent conflicts with development workflows.
• Deterministic tab control: tabs first returns suggestedTargetId, then a stable tabId handle such as t1, optional tags, and the original targetId. The Agent should reuse suggestedTargetId; the original ID remains available for debugging and compatibility.

​

Browser Selection

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

• macOS: checks /Applications and ~/Applications.
• Linux: checks common Chrome/Brave/Edge/Chromium locations under /usr/bin, /snap/bin, /opt/google, /opt/brave.com, /usr/lib/chromium, and /usr/lib/chromium-browser, as well as Playwright-managed Chromium under PLAYWRIGHT_BROWSERS_PATH or ~/.cache/ms-playwright.
• Windows: checks common installation locations.

​

Control API (Optional)

​

Troubleshooting

​

CDP Startup Failure vs Navigation SSRF Blocking

• CDP startup or readiness failure means OpenClaw cannot confirm whether the browser control plane is healthy.
• Navigation SSRF blocking means the browser control plane is healthy, but a page navigation target was denied by policy.

• CDP startup or readiness failure:
  • Chrome CDP websocket for profile "openclaw" is not reachable after start
  • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
  • When attachOnly: true is not configured, if an external loopback CDP service is configured, Port <port> is in use for profile "<name>" but not by openclaw will appear
• Navigation SSRF blocking:
  • Flows such as open, navigate, snapshot, or opening tabs fail due to browser/network policy errors, but start and tabs still work

openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com

• If start fails with not reachable after start, investigate CDP readiness first.
• If start succeeds but tabs fails, the control plane is still unhealthy. Treat it as a CDP reachability issue, not a page navigation issue.
• If start and tabs succeed, but open or navigate fails, the browser control plane is healthy and the failure happened in navigation policy or the target page.
• If start, tabs, and open all succeed, the basic managed browser control path is healthy.

• Even if you do not configure browser.ssrfPolicy, the browser configuration uses a fail-closed SSRF policy object by default.
• For the local loopback openclaw managed profile, CDP health checks intentionally skip browser-SSRF reachability enforcement for OpenClaw’s own local control plane.
• Navigation protection is separate. A successful start or tabs does not mean later open or navigate targets are necessarily allowed.

• Do not relax browser SSRF policy by default.
• Prefer narrower host exceptions such as hostnameAllowlist or allowedHostnames over broader private-network access.
• Use dangerouslyAllowPrivateNetwork: true only in environments that are explicitly trusted, genuinely require it, and have had private-network browser access reviewed.

​

Agent Tools + Control Modes

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

• browser snapshot returns a stable UI tree (AI or ARIA).
• browser act uses snapshot ref IDs to click/type/drag/select.
• browser screenshot captures pixels (full page, elements, or tagged refs).
• browser doctor checks Gateway, plugins, profiles, browser, and tab readiness.
• browser accepts:
  • profile to select a named browser profile (openclaw, chrome, or remote CDP).
  • target (sandbox | host | node) to select where the browser runs.
  • In sandbox sessions, target: "host" requires agents.defaults.sandbox.browser.allowHostControl=true.
  • If target is omitted: sandbox sessions default to sandbox, and non-sandbox sessions default to host.
  • If a browser-capable node is connected, the tool may automatically route to that node unless you pin target="host" or target="node".

​

Related

• Tools Overview - All available agent tools
• Sandboxing - Browser control in sandboxed environments
• Security - Browser control risks and hardening