浏览器（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 第一次附加时显示阻塞式 “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 的浏览器

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 auth（例如 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 网关上：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 fallback。
• 直接 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 发现（将 scheme 规范化为 http/https）；如果发现返回 webSocketDebuggerUrl，就使用它，否则 OpenClaw fallback 到裸根地址上的直接 WebSocket 握手。如果通告的 WebSocket 端点拒绝 CDP 握手，但配置的裸根地址接受它，OpenClaw 也会 fallback 到该根地址。这样，指向本地 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 断开连接时，会销毁该会话。
• 查看价格，了解当前免费层限制和付费套餐。
• 查看 Notte 文档，获取完整 API 参考、SDK 指南和集成示例。

​

安全

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

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

​

配置（多浏览器）

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

• 如果缺失，会自动创建 openclaw 配置。
• user 配置是内置的，用于 Chrome MCP existing-session 附加。
• 除 user 之外，existing-session 配置需要显式启用；使用 --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",
        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 页面中已启用远程调试
• 浏览器已显示附加同意提示，并且你已接受
• 如果 Chrome 是用显式 --remote-debugging-port 启动的，请将 browser.profiles.<name>.cdpUrl 设置为该 DevTools 端点，而不是依赖 Chrome MCP 自动连接
• openclaw doctor 会迁移旧的基于扩展的浏览器配置，并检查默认自动连接配置是否在本地安装了 Chrome，但它不能替你启用浏览器侧远程调试

• 当你需要用户已登录的浏览器状态时，使用 profile="user"。
• 如果使用自定义 existing-session 配置，请传入该显式配置名称。
• 仅在用户位于电脑前可以批准附加提示时选择此模式。
• 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 位置，以及 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>
  • 当配置了不带 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，浏览器配置也默认使用失败关闭的 SSRF 策略对象。
• 对于 local 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 使用快照 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"。

​

相关

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