跳转至

远程和托管浏览器

本地控制与远程控制

  • 本地控制（默认）： 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> 或带有 /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 发现（将协议规范化为 http/https）；如果发现返回 webSocketDebuggerUrl，则使用它，否则 OpenClaw 回退到在裸根上执行直接 WebSocket 握手。如果通告的 WebSocket 端点拒绝 CDP 握手，但配置的裸根接受该握手，OpenClaw 也会回退到该根。这使得指向本地 Chrome 的裸 ws:// 仍然可以连接，因为 Chrome 只接受来自 /json/version 的特定于每个目标的路径上的 WebSocket 升级，而托管提供商在其发现端点通告了一个不适合 Playwright CDP 的短生命周期 URL 时，仍可使用其根 WebSocket 端点。

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

Browserbase

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

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

说明：

  • 注册，并从 概览仪表板 复制你的 API Key。
  • 将 <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 Key。
  • 将 <NOTTE_API_KEY> 替换为你的真实 Notte API 密钥。
  • Notte 会在 WebSocket 连接时自动创建浏览器会话，因此无需手动创建会话步骤。当 WebSocket 断开时，会话会被销毁。
  • 查看 定价 了解当前免费层限制和付费计划。
  • 查看 Notte 文档 了解完整 API 参考、SDK 指南和集成示例。

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