跳转至

远程和托管浏览器

本地控制与远程控制

  • 本地控制(默认): Gateway 启动回环控制服务,并可以启动本地浏览器。无目标的操作可以启动它(例如 open、navigate 或 openclaw browser start)。通过 targetId、标签页 id 或标签来命名标签页的操作绝不会启动已停止的浏览器,因为新浏览器无法包含该标签页;请先启动浏览器或打开新标签页,然后选择当前目标。
  • 远程控制(节点主机): 在装有浏览器的机器上运行节点主机(配对参见 节点,openclaw node run 参见 节点主机 CLI);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 启动的浏览器进程
  • 仅附加(attach-only)和远程 CDP 配置文件:openclaw browser stop 会关闭当前控制会话,并释放 Playwright/CDP 模拟覆盖(视口、配色方案、区域设置、时区、离线模式及类似状态),即使 OpenClaw 未启动任何浏览器进程

远程 CDP URL 可以包含认证信息:

  • 查询令牌(例如 https://provider.example?token=<token>)
  • HTTP 基本认证(例如 https://user:pass@provider.example)

OpenClaw 在调用 /json/* 端点以及连接到 CDP WebSocket 时会保留该认证信息。对于令牌,建议使用环境变量或密钥管理器,而不是将其写入配置文件。

节点浏览器代理(零配置默认)

如果你在装有浏览器的机器上运行节点主机,当 Gateway 主机没有本地浏览器能力时,OpenClaw 可以将浏览器工具调用自动路由到该节点。自动路由优先选择主机,包括已安装可执行文件但处于停止状态的托管浏览器。显式的 target="node"、node 选择器或 gateway.nodes.browser.node 会覆盖该偏好;target="host" 始终停留在主机上。

即使未安装托管浏览器可执行文件,所选主机配置文件仍拥有现有会话、扩展、仅附加(attach-only)和远程 CDP 连接。启动失败、无效的可执行文件设置、权限错误和页面操作失败都保留在该所有者上;OpenClaw 不会在另一台机器上重放这些操作。仅当所选节点尚未处理请求时,才允许从所选节点自动回退到主机。一旦操作到达节点,其后续快照或设置将保留在该节点上,而不会切换浏览器。

独立运行(例如 openclaw agent exec)在未选择 Gateway 或节点路由时使用主机浏览器。它们不需要 Gateway 凭据即可进行本地浏览器控制。沙箱路由和主机控制限制仍然适用。若要从独立运行中通过本地 Gateway 发现浏览器节点,请设置 gateway.nodes.browser.mode="auto";只有在本地能力不可用时才会执行发现。显式的节点目标或固定(pin)、远程 Gateway 配置或 OPENCLAW_GATEWAY_URL 也会保持节点发现启用。显式的节点目标和固定会保留连接和认证错误。

注意:

  • 节点主机通过代理命令暴露其本地浏览器控制服务器。
  • 配置文件来自节点自身的 browser.profiles 配置(与本地相同)。
  • 代理命令绝不允许持久化配置文件变更(create-profile、delete-profile、reset-profile),无论 allowProfiles 如何设置;请直接在节点上进行这些更改。
  • nodeHost.browserProxy.allowProfiles 是可选的。将其留空以获得旧版/默认行为:所有已配置的配置文件仍可通过代理访问。
  • 如果设置了 nodeHost.browserProxy.allowProfiles,OpenClaw 会将其视为最小权限边界,限制代理可以定向的配置文件名称。
  • 请求在准备工作期间会保留所选的配置文件。节点会在浏览器操作前重新检查代理和配置文件访问权限,包括在启动或上传准备之后。
  • 如果不想要此功能,可将其禁用:
  • 在节点上:nodeHost.browserProxy.enabled=false
  • 在网关上:gateway.nodes.browser.mode="off"(也接受 "auto" 以优先使用主机并回退到单个已连接的浏览器节点,或 "manual" 以要求显式选择节点或配置固定)

Browserless(托管远程 CDP)

Browserless 是一种托管的 Chromium 服务,通过 HTTPS 和 WebSocket 暴露 CDP 连接 URL。OpenClaw 可以使用其中任意一种形式,但对于远程浏览器配置文件,最简单的选项是使用 Browserless 连接文档中的直接 WebSocket URL。

示例:

{
  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

当 Browserless 在 Docker 中自托管而 OpenClaw 运行在主机上时,请将 Browserless 视为外部管理的 CDP 服务:

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

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 连接仍然会失败。

对于回环地址的 Browserless 配置文件,不要不设置 attachOnly。没有 attachOnly 时,OpenClaw 会将回环端口视为本地受管浏览器配置文件,并可能报告该端口已被占用但并非由 OpenClaw 拥有。

直接 WebSocket CDP 提供商

某些托管浏览器服务提供直接 WebSocket 端点,而不是基于 HTTP 的标准 CDP 发现机制(/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,则使用该 URL,否则 OpenClaw 会在裸根地址上回退到直接 WebSocket 握手。如果广告的 WebSocket 端点拒绝了 CDP 握手,但配置的裸根地址接受该握手,OpenClaw 也会回退到该根地址。这样,指向本地 Chrome 的裸 ws:// 仍然可以连接,因为 Chrome 只接受来自 /json/version 的、 特定于每个目标的路径上的 WebSocket 升级,而托管提供商在它们的发现端点广告了 不适合用于 Playwright CDP 的短时 URL 时,仍然可以使用它们的根 WebSocket 端点。

openclaw browser doctor 使用与运行时连接相同的“发现优先、WebSocket 回退”逻辑, 因此能够成功连接的裸根地址不会被诊断报告为不可达。

Browserbase

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

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

说明:

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

Notte

Notte 是一个云平台,用于运行无头浏览器, 内置隐身功能、住宅代理和 CDP 原生的 WebSocket 网关。

{
  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 指南和集成示例。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw