OpenClaw 可以运行一个与个人浏览器完全隔离的专用 Chrome/Brave/Edge 实例，通过 CDP 和 Playwright 实现浏览器自动化。默认使用 openclaw profile，无需额外配置即可让 agent 控制浏览器；需要复用登录态时使用 user profile（Chrome MCP 附接）。支持 Browserless、Browserbase 等远程无头服务，以及多 profile 和节点宿主机代理。浏览器配置修改后需重启 Gateway。

OpenClaw 浏览器控制配置：隔离 Profile、远程 CDP 与 Chrome 附接

OpenClaw 可以运行一个专用的 Chrome/Brave/Edge/Chromium Profile，由 agent 控制。它与你的个人浏览器完全隔离，通过 Gateway 内部的小型本地控制服务（仅 loopback）管理。

如果你搜索的是“OpenClaw 怎么控制浏览器”，先看结论：默认用隔离的 openclaw Profile，只有需要复用真实登录态时才用 user Profile；远程服务器没有浏览器时，用节点宿主机或远端 CDP，而不是把个人 Chrome 调试端口暴露到公网。

快速开始

bash

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

如果提示"Browser disabled"，在配置中启用（见下文）并重启 Gateway。

如果 openclaw browser 命令完全不存在，跳至缺少 browser 命令或工具。

插件控制

默认的 browser 工具是一个内置插件，默认启用。禁用它会同时移除 openclaw browser CLI、browser.request gateway 方法、agent 工具和控制服务。如果你要替换为另一个插件，按以下方式禁用内置插件：

json5

{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}

默认浏览器体验需要同时满足：plugins.entries.browser.enabled 未禁用且 browser.enabled=true。只禁用插件不会删除 browser.* 配置，后续可被替换插件使用。浏览器配置变更后需重启 Gateway。

Agent 指导

工具 profile 说明：tools.profile: "coding" 包含 web_search 和 web_fetch，但不包含完整的 browser 工具。如果 agent 或子 agent 应使用浏览器自动化，需在 profile 中额外添加：

json5

{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

对单个 agent，使用 agents.list[].tools.alsoAllow: ["browser"]。tools.subagents.tools.allow: ["browser"] 单独设置是不够的，因为子 agent 策略在 profile 过滤之后才应用。

内置浏览器插件附带两层 agent 指导：

browser 工具描述包含紧凑的始终有效合约：选择正确 profile、在同一标签页内维护引用、使用 tabId/标签定位标签页、加载 browser skill 处理多步骤任务。
绑定的 browser-automation skill 包含更长的工作循环：先检查状态/标签页、标记任务标签页、操作前快照、UI 变化后重新快照、对失效引用尝试恢复一次、遇到登录/2FA/captcha 或摄像头/麦克风拦截器时报告需要人工干预而不是猜测。

插件绑定的 skill 在插件启用后出现在 agent 可用 skill 列表中。完整的 skill 指令按需加载，日常对话不会消耗完整 token。

缺少 browser 命令或工具

若升级后 openclaw browser 变为未知命令，或 browser.request 缺失，或 agent 报告 browser 工具不可用，最常见原因是 plugins.allow 列表中未包含 browser 且根配置中没有 browser 配置块。修正方法：

json5

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

存在显式的根 browser 配置块（如 browser.enabled=true 或 browser.profiles.<name>），即使 plugins.allow 受限也会激活内置浏览器插件，这与渠道配置的行为一致。注意：plugins.entries.browser.enabled=true 和 tools.alsoAllow: ["browser"] 不能替代 allowlist 成员身份。完全删除 plugins.allow 也能恢复默认状态。

Profile 选择：隔离 openclaw vs 现有用户浏览器

openclaw：托管的隔离浏览器（无需扩展）。
user：内置 Chrome MCP 附接 Profile，用于你真实的已登录 Chrome 会话。

Agent 浏览器工具调用时：

默认：使用隔离的 openclaw 浏览器。
当已有登录会话很重要且用户在电脑前能点击/批准附提示时，优先使用 profile="user"。
profile 是显式覆盖参数，用于指定具体浏览器模式。

设置 browser.defaultProfile: "openclaw" 可以让托管模式成为默认。

配置详解

浏览器设置位于 ~/.openclaw/openclaw.json。

json5

{
  browser: {
    enabled: true, // 默认 true
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // 仅在信任私有网络访问时启用
      // allowPrivateNetwork: true, // 旧别名
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // 旧版本单 profile 覆盖
    remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时 (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时 (ms)
    localLaunchTimeoutMs: 15000, // 本地托管 Chrome 发现超时 (ms)
    localCdpReadyTimeoutMs: 8000, // 本地托管启动后 CDP 就绪超时 (ms)
    actionTimeoutMs: 60000, // 默认 browser act 超时 (ms)
    tabCleanup: {
      enabled: true, // 默认 true
      idleMinutes: 120, // 设为 0 禁用空闲清理
      maxTabsPerSession: 8, // 设为 0 禁用 per-session 上限
      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" },
    },
  },
}

端口与可达性

控制服务绑定到 loopback 端口，默认 18791（gateway.port + 2）。覆盖 gateway.port 或 OPENCLAW_GATEWAY_PORT 会同步偏移派生端口。
本地 openclaw profile 自动分配 cdpPort/cdpUrl；仅对远程 CDP 设置这些字段。cdpUrl 未设置时默认指向托管本地 CDP 端口。
remoteCdpTimeoutMs 应用于远程和 attachOnly 的 CDP HTTP 可达性检查及打开标签的 HTTP 请求；remoteCdpHandshakeTimeoutMs 应用于它们的 CDP WebSocket 握手。
localLaunchTimeoutMs 是本地启动的托管 Chrome 进程暴露其 CDP HTTP 端点的预算。localCdpReadyTimeoutMs 是进程发现后 CDP websocket 就绪的后续预算。树莓派、低配 VPS 或老旧硬件上 Chromium 启动慢时需提高这两个值。值必须为正整数且不超过 120000 ms，非法配置值会被拒绝。
重复的托管 Chrome 启动/就绪失败会触发按 profile 的断路器。连续几次失败后，OpenClaw 会暂停新的启动尝试，而不是在每次 browser 工具调用时都生成 Chromium。修复启动问题后可禁用不需要的浏览器或重启 Gateway。
actionTimeoutMs 是浏览器 act 请求的默认预算，在调用者未传递 timeoutMs 时使用。客户端传输会增加一个小的浮动窗口，让长时间等待能完成而不是在 HTTP 边界超时。
tabCleanup 是对主 agent 浏览器会话打开的标签页的最佳努力清理。子 agent、cron 和 ACP 生命周期清理仍会在会话结束时关闭其显式跟踪的标签页；主会话保持活动标签页可复用，然后在后台关闭空闲或超额的跟踪标签页。

SSRF 策略

浏览器导航和打开标签页在导航前受 SSRF 保护，并在最终 http(s) URL 上做最佳努力重新检查。
在严格 SSRF 模式下，远程 CDP 端点发现和 /json/version 探测（cdpUrl）也会被检查。
Gateway/provider 的 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY 环境变量不会自动代理 OpenClaw 管理的浏览器。托管 Chrome 默认直连，以防止 provider 代理设置削弱浏览器 SSRF 检查。
要代理托管浏览器本身，请通过 browser.extraArgs 传递显式的 Chrome 代理标志，如 --proxy-server=... 或 --proxy-pac-url=...。严格 SSRF 模式会阻止显式浏览器代理路由，除非已启用私有网络浏览器访问。
browser.ssrfPolicy.dangerouslyAllowPrivateNetwork 默认关闭；仅在信任私有网络浏览器访问时启用。
browser.ssrfPolicy.allowPrivateNetwork 仍作为旧版本别名受支持。

Profile 行为说明

attachOnly: true 表示绝不启动本地浏览器；只附接到已运行的浏览器。
headless 可以在全局或每个本地托管 profile 中设置。Per-profile 值覆盖 browser.headless，这样同一个配置文件中的本地 profile 可以保持 headless 而另一个可见。
POST /start?headless=true 和 openclaw browser start --headless 请求一次性的 headless 启动（对本地托管 profile），不会改写 browser.headless 或 profile 配置。existing-session、attach-only 和远程 CDP profile 拒绝此覆盖，因为 OpenClaw 不启动这些浏览器进程。
在 Linux 主机上，如果没有 DISPLAY 或 WAYLAND_DISPLAY，且环境、profile 或全局配置未显式选择 headed 模式，本地托管 profile 会自动默认 headless。openclaw browser status --json 会报告 headlessSource 为 env、profile、config、request、linux-display-fallback 或 default。
OPENCLAW_BROWSER_HEADLESS=1 强制当前进程的本地托管启动为 headless。OPENCLAW_BROWSER_HEADLESS=0 强制 headed 模式，在 Linux 主机没有显示服务器时返回可操作的错误；但显式的 start --headless 请求对该次启动仍有效。
executablePath 可以在全局或每个本地托管 profile 中设置。Per-profile 值覆盖 browser.executablePath，这样不同的 profile 可以启动不同的 Chromium 浏览器。两种形式都接受 ~ 表示用户主目录。
color（顶层和 per-profile）会着色浏览器 UI，让你看到哪个 profile 活跃。
默认 profile 是 openclaw（托管独立）。使用 defaultProfile: "user" 可切换到已登录用户浏览器。
自动检测顺序：如果系统默认浏览器是 Chromium 系列，则使用它；否则按顺序查 Chrome → Brave → Edge → Chromium → Chrome Canary。
driver: "existing-session" 使用 Chrome DevTools MCP 而非原始 CDP。不要为该驱动设置 cdpUrl。
当 existing-session profile 需要附接到非默认 Chromium 用户数据目录（Brave、Edge 等）时，设置 browser.profiles.<name>.userDataDir。此路径也接受 ~。

使用 Brave 或其他 Chromium 浏览器

如果系统默认浏览器是 Chromium 系列（Chrome/Brave/Edge 等），OpenClaw 会自动使用它。设置 browser.executablePath 覆盖自动检测。顶层和 per-profile 的 executablePath 都接受 ~：

bash

openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

或在配置中按平台设置：

macOS

json5

{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
  },
}

Windows

json5

{
  browser: {
    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
  },
}

Linux

json5

{
  browser: {
    executablePath: "/usr/bin/brave-browser",
  },
}

Per-profile executablePath 仅影响 OpenClaw 启动的本地托管 profile。existing-session profile 附接到已运行的浏览器，远程 CDP profile 使用 cdpUrl 背后的浏览器。

本地控制 vs 远程控制

本地控制（默认）： 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 会被视为本地托管浏览器 profile。
headless 仅影响 OpenClaw 启动的本地托管 profile，不会重启或改变 existing-session 或远程 CDP 浏览器。
executablePath 遵循相同规则。在运行中的本地托管 profile 上更改它会标记该 profile 为需要重启/调和，以便下次启动使用新二进制。

停止行为因 profile 模式而异：

本地托管 profile：openclaw browser stop 停止 OpenClaw 启动的浏览器进程。
attach-only 和远程 CDP profile：openclaw browser stop 关闭活跃控制会话并释放 Playwright/CDP 模拟覆盖（视口、配色方案、区域设置、时区、离线模式等），即使 OpenClaw 未启动浏览器进程。

远程 CDP URL 可以包含认证：

查询 token（如 https://provider.example?token=<token>）
HTTP Basic auth（如 https://user:pass@provider.example）

OpenClaw 在调用 /json/* 端点和连接 CDP WebSocket 时会保留认证信息。优先使用环境变量或 secrets 管理器存储 token，而不是直接写入配置文件。

节点宿主机浏览器代理（零配置默认）

如果你在装有浏览器的机器上运行节点宿主机，OpenClaw 可以自动将浏览器工具调用路由到该节点，无需额外浏览器配置。这是远程 Gateway 的默认路径。

注意：

节点宿主机通过代理命令暴露其本地浏览器控制服务器。
Profile 来自节点自身的 browser.profiles 配置（与本地相同）。
nodeHost.browserProxy.allowProfiles 可选。留空则为旧版/默认行为：所有已配置的 profile 都可通过代理访问，包括 profile 创建/删除路由。
如果设置了 nodeHost.browserProxy.allowProfiles，OpenClaw 将其视为最小权限边界：只允许白名单中的 profile 被访问，且 proxy 表面会阻止持久性 profile 创建/删除路由。
禁用方式：
- 在节点上：nodeHost.browserProxy.enabled=false
- 在 Gateway 上：gateway.nodes.browser.mode="off"

Browserless（托管远程 CDP）

Browserless 是一个托管 Chromium 服务，通过 HTTPS 和 WebSocket 暴露 CDP 连接 URL。OpenClaw 可使用任一形式，但最简单的是从 Browserless 文档获取直接 WebSocket URL。

示例配置：

json5

{
  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> 替换为真实 token。
选择与账号匹配的区域端点。
如果 Browserless 给出的是 HTTPS 基础 URL，你可以转为 wss:// 直接 CDP 连接，或保留 HTTPS URL 让 OpenClaw 通过 /json/version 发现。

同主机 Docker 中的 Browserless

当 Browserless 自托管在 Docker 中，且 OpenClaw 运行在宿主机上时，将 Browserless 视为外部管理的 CDP 服务：

json5

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    profiles: {
      browserless: {
        cdpUrl: "ws://127.0.0.1:3000",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}

browser.profiles.browserless.cdpUrl 的地址必须对 OpenClaw 进程可达。Browserless 也必须广播一个匹配的可达端点；设置 Browserless EXTERNAL 为相同的对 OpenClaw 的 WebSocket 基础地址，如 ws://127.0.0.1:3000、ws://browserless:3000 或稳定的私有 Docker 网络地址。如果 /json/version 返回的 webSocketDebuggerUrl 指向 OpenClaw 无法到达的地址，CDP HTTP 可能看似健康但 WebSocket 附件实际上会失败。

不要对 loopback Browserless profile 不设置 attachOnly。没有 attachOnly，OpenClaw 会将 loopback 端口视为本地托管浏览器 profile，并可能报告端口已被占用但不属于 OpenClaw。

直接 WebSocket CDP 提供商

一些托管浏览器服务暴露的是直接 WebSocket 端点而非标准 HTTP 发现（/json/version）。OpenClaw 接受三种 CDP URL 格式，并自动选择连接策略：

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 中特定 per-target 路径的 WebSocket 升级，而托管提供商仍可在发现端点广告的 URL 不适用于 Playwright CDP 时使用其根 WebSocket 端点。

Browserbase

Browserbase 是一个云平台，用于运行无头浏览器，内置 CAPTCHA 解决、隐身模式和住宅代理。

json5

{
  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> 替换为真实 API key。
Browserbase 会在 WebSocket 连接时自动创建浏览器会话，无需手动创建。
免费版每月一个并发会话、一小时浏览器时间。请参阅定价页了解付费计划限制。

安全配置

关键点：

浏览器控制仅限 loopback；访问通过 Gateway 认证或节点配对流动。
独立的 loopback 浏览器 HTTP API 使用共享密钥认证：gateway token bearer auth、x-openclaw-password 或 HTTP Basic auth（使用已配置的 gateway 密码）。
Tailscale Serve 身份头部和 gateway.auth.mode: "trusted-proxy" 不认证这个独立的 loopback 浏览器 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/token 请视为机密；优先使用环境变量或 secrets 管理器。

远程 CDP 提示：

优先使用加密端点（HTTPS 或 WSS）和短生命周期的 token。
避免将长生命周期 token 直接嵌入配置文件。

通过 Chrome DevTools MCP 附接现有会话

OpenClaw 可以通过官方 Chrome DevTools MCP 服务器附接到运行中的 Chromium profile。这会复用该浏览器 profile 中已打开的标签页和登录状态。

官方参考资料：

内置 profile：

user

可选：如果你需要不同的名称、颜色或浏览器数据目录，可以创建自定义 existing-session profile。

默认行为：

内置的 user profile 使用 Chrome MCP 自动连接，目标是默认的本地 Google Chrome profile。

使用 userDataDir 指向 Brave、Edge、Chromium 或非默认 Chrome profile。~ 会展开为用户主目录：

json5

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

然后在对应浏览器中：

打开该浏览器的 inspect 页面进行远程调试。
启用远程调试。
保持浏览器运行，并在 OpenClaw 附接时批准连接提示。

常见 inspect 页面：

Chrome: chrome://inspect/#remote-debugging
Brave: brave://inspect/#remote-debugging
Edge: edge://inspect/#remote-debugging

实机附接冒烟测试：

bash

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+
该浏览器的 inspect 页面已启用远程调试
浏览器显示并要求你批准附接同意提示（你需要同意）
openclaw doctor 会迁移旧的基于扩展的浏览器配置并检查 Chrome 是否在本地安装，但它不能为你启用浏览器端的远程调试

Agent 使用：

当你需要用户的已登录浏览器状态时，使用 profile="user"。
如果使用自定义 existing-session profile，传递显式的 profile 名称。
仅当用户在电脑前能批准附接提示时才选择此模式。
Gateway 或节点宿主机可以执行 npx chrome-devtools-mcp@latest --autoConnect

注意：

此路径比隔离的 openclaw profile 风险更高，因为它可以在你已登录的浏览器会话内操作。
OpenClaw 不会为此驱动启动浏览器；它只附接。
OpenClaw 使用官方 Chrome DevTools MCP --autoConnect 流程。如果设置了 userDataDir，它会被传递以定位该用户数据目录。
Existing-session 可以附接到选定主机或通过已连接的浏览器节点附接。如果 Chrome 在其他地方且没有浏览器节点连接，请使用远程 CDP 或节点宿主机。

自定义 Chrome MCP 启动

当默认的 npx chrome-devtools-mcp@latest 流程不是你想要的（离线主机、固定版本、供应商二进制文件），可以按 profile 覆盖：

字段	作用
`mcpCommand`	要启动的可执行文件，替代 `npx`。按原样解析；绝对路径受支持。
`mcpArgs`	逐字传递给 `mcpCommand` 的参数数组。替换默认的 `chrome-devtools-mcp@latest --autoConnect` 参数。

当 existing-session profile 上设置了 cdpUrl 时，OpenClaw 跳过 --autoConnect 并自动将端点转发给 Chrome MCP：

http(s)://... → --browserUrl <url>（DevTools HTTP 发现端点）
ws(s)://... → --wsEndpoint <url>（直接 CDP WebSocket）

端点标志和 userDataDir 不能组合：当设置了 cdpUrl 时，userDataDir 会被 Chrome MCP 启动忽略，因为 Chrome MCP 是附接到端点背后的运行浏览器，而不是打开 profile 目录。

Existing-session 功能限制

与管理的 openclaw profile 相比，existing-session 驱动有更多限制：

截图 - 页面截图和 --ref 元素截图支持；CSS --element 选择器不支持。--full-page 不能与 --ref 或 --element 组合。Playwright 对页面或基于 ref 的元素截图不是必需的。
操作 - click、type、hover、scrollIntoView、drag、select 需要快照 ref（不支持 CSS 选择器）。click-coords 点击可见视口坐标，不需要快照 ref。click 仅左键。type 不支持 slowly=true；用 fill 或 press。press 不支持 delayMs。type、hover、scrollIntoView、drag、select、fill、evaluate 不支持 per-call 超时。select 接受单个值。
等待/上传/对话框 - wait --url 支持精确、子串和 glob 模式；wait --load networkidle 不支持。上传挂钩需要 ref 或 inputRef，一次一个文件，不支持 CSS element。对话框挂钩不支持超时覆盖或 dialogId。
对话框可见性 - 托管浏览器操作响应中包含 blockedByDialog 和 browserState.dialogs.pending；快照中也包含挂起的对话框状态。在对话框挂起时用 browser dialog --accept/--dismiss --dialog-id <id> 响应。在 OpenClaw 外部处理的对话框出现在 browserState.dialogs.recent。
托管专用功能 - batch actions、PDF 导出、下载拦截、responsebody 仍需要托管浏览器路径。

隔离保证

专用 User Data Dir：绝不触及个人浏览器 profile。
专用端口：避开 9222，防止与开发工作流冲突。
确定性标签页控制：tabs 返回 suggestedTargetId，然后是稳定的 tabId 句柄（如 t1）、可选标签、原始 targetId。Agent 应优先复用 suggestedTargetId；原始 id 保留用于调试和兼容性。

浏览器自动选择

当本地启动时，OpenClaw 按顺序选择第一个可用的：

Chrome
Brave
Edge
Chromium
Chrome Canary

可用 browser.executablePath 覆盖。

平台：

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（可选）

Gateway 暴露一个仅 loopback 的 HTTP 控制 API 以及对应的 openclaw browser CLI（支持快照、引用、等待增强、JSON 输出、调试工作流）。详情参见 Browser control API（若文档存在）。

故障排查

Linux 特定问题（snap Chromium）参见浏览器故障排查。

WSL2 + Windows Chrome 跨主机设置参见 WSL2 + Windows + 远程 Chrome CDP 故障排查。

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>
- Port <port> is in use for profile "<name>" but not by openclaw（当 loopback 外部 CDP 服务未设置 attachOnly: true 时出现）
导航 SSRF 拦截：
- open、navigate、snapshot 或打开标签页流程失败，出现浏览器/网络策略错误，而 start 和 tabs 仍然工作

用这个最小序列区分两者：

bash

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 托管 profile，CDP 健康检查会故意跳过对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性执行。
导航保护是独立的。成功的 start 或 tabs 结果并不意味着后续的 open 或 navigate 目标被允许。

安全指导：

不要默认放宽浏览器 SSRF 策略。
优先使用窄域名例外（如 hostnameAllowlist 或 allowedHostnames）而不是宽泛的私有网络访问。
仅在必要且已审查的受信任环境中使用 dangerouslyAllowPrivateNetwork: true。

Agent 工具与控制机制

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 捕获像素（全页、元素、已标记的 ref）。
browser doctor 检查 Gateway、插件、profile、浏览器和标签页就绪状态。
browser 接受：
- profile 选择命名浏览器 profile（openclaw、chrome 或远程 CDP）。
- target（sandbox | host | node）选择浏览器所在位置。
- 在沙箱会话中，target: "host" 需要 agents.defaults.sandbox.browser.allowHostControl=true。
- 如果省略 target：沙箱会话默认为 sandbox，非沙箱会话默认为 host。
- 如果已连接支持浏览器的节点，工具可能自动路由到它，除非你显式指定 target="host" 或 target="node"。

这使 agent 行为确定，避免易碎的选择器。

常见问题

怎么配置 OpenClaw 使用 Brave 浏览器而不是 Chrome？

设置 browser.executablePath 指向 Brave 的可执行文件。例如 macOS 上：/Applications/Brave Browser.app/Contents/MacOS/Brave Browser。也可以按 profile 设置：browser.profiles.work.executablePath。修改后需重启 Gateway。

远程 CDP 怎么接入 Browserless？

在 browser.profiles 中添加一个 profile，cdpUrl 设为 Browserless 提供的 WebSocket URL（如 wss://production-sfo.browserless.io?token=...）。如果同主机 Docker 部署，设为 ws://127.0.0.1:3000 并设置 attachOnly: true。注意设置正确的超时参数 remoteCdpTimeoutMs 和 remoteCdpHandshakeTimeoutMs。

为什么 agent 报 browser tool unavailable？

最常见原因是 plugins.allow 列表中未包含 browser。在配置中添加 plugins.allow: ["telegram", "browser"] 即可。如果已加，检查 browser.enabled 是否为 true，并且 plugins.entries.browser.enabled 未被禁用。修改后重启 Gateway。

如何让 agent 能操作我已登录的网站（如 Gmail）？

使用 profile="user" 并配置 user profile（内置）。这需要通过 Chrome MCP 附接到你当前的 Chrome 会话。步骤：在 Chrome 中打开 chrome://inspect/#remote-debugging 启用远程调试，然后运行 openclaw browser --browser-profile user start 并批准连接提示。注意：此模式下 agent 能触及你的登录态，安全风险较高，确保只有你可信任的 agent 在使用。

OpenClaw 浏览器控制配置：隔离 Profile、远程 CDP 与 Chrome 附接 ​

快速开始 ​

插件控制 ​

Agent 指导 ​

缺少 browser 命令或工具 ​

Profile 选择：隔离 openclaw vs 现有用户浏览器 ​

配置详解 ​

端口与可达性 ​

SSRF 策略 ​

Profile 行为说明 ​

使用 Brave 或其他 Chromium 浏览器 ​

本地控制 vs 远程控制 ​

节点宿主机浏览器代理（零配置默认） ​

Browserless（托管远程 CDP） ​

同主机 Docker 中的 Browserless ​

直接 WebSocket CDP 提供商 ​

Browserbase ​

安全配置 ​

通过 Chrome DevTools MCP 附接现有会话 ​

自定义 Chrome MCP 启动 ​

Existing-session 功能限制 ​

隔离保证 ​

浏览器自动选择 ​

控制 API（可选） ​

故障排查 ​

CDP 启动失败 vs 导航 SSRF 拦截 ​

Agent 工具与控制机制 ​

常见问题 ​

怎么配置 OpenClaw 使用 Brave 浏览器而不是 Chrome？ ​

远程 CDP 怎么接入 Browserless？ ​

为什么 agent 报 browser tool unavailable？ ​

如何让 agent 能操作我已登录的网站（如 Gmail）？ ​

OpenClaw 浏览器控制配置：隔离 Profile、远程 CDP 与 Chrome 附接

快速开始

插件控制

Agent 指导

缺少 browser 命令或工具

Profile 选择：隔离 openclaw vs 现有用户浏览器

配置详解

端口与可达性

SSRF 策略

Profile 行为说明

使用 Brave 或其他 Chromium 浏览器

本地控制 vs 远程控制

节点宿主机浏览器代理（零配置默认）

Browserless（托管远程 CDP）

同主机 Docker 中的 Browserless

直接 WebSocket CDP 提供商

Browserbase

安全配置

通过 Chrome DevTools MCP 附接现有会话

自定义 Chrome MCP 启动

Existing-session 功能限制

隔离保证

浏览器自动选择

控制 API（可选）

故障排查

CDP 启动失败 vs 导航 SSRF 拦截

Agent 工具与控制机制

常见问题

怎么配置 OpenClaw 使用 Brave 浏览器而不是 Chrome？

远程 CDP 怎么接入 Browserless？

为什么 agent 报 browser tool unavailable？

如何让 agent 能操作我已登录的网站（如 Gmail）？