OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

快速开始

Chrome 扩展程序

Chrome 扩展

OpenClaw Chrome 扩展让智能体无需启动单独的托管浏览器，即可控制你已登录的 Chrome 标签页，并且不会触发 Chrome 阻塞操作的 “Allow remote debugging?” 提示。

当你通过手机（Telegram、WhatsApp 等）操控 OpenClaw 时，这一点很重要：​​user 配置文件会通过 Chrome 的远程调试端口连接，这会弹出桌面同意对话框，而你不在电脑旁时无人可以点击。该扩展改用 chrome.debugger API，因此页面内唯一的提示是 Chrome 可关闭的 “OpenClaw started debugging this browser” 横幅。

Anthropic 的 Claude in Chrome 和 OpenAI 的 Codex Chrome 扩展也采用相同的架构。

工作原理

它由三部分组成：

  • 浏览器控制服务（Gateway 网关或节点主机）：browser 工具调用的 API。
  • 扩展中继（local loopback WebSocket）：控制服务在 127.0.0.1 上启动的小型服务器。它向 OpenClaw 提供 Chrome DevTools Protocol 端点，并与扩展通信。双方都使用主机本地令牌进行身份验证（见下文）。
  • OpenClaw Chrome 扩展（MV3）：使用 chrome.debugger 连接标签页、转发 CDP 流量，并管理 OpenClaw 标签页组。

OpenClaw 只能看到和控制 OpenClaw 标签页组中的标签页。该标签页组是用户授权边界：将标签页拖入组中即可共享，将其拖出（或点击工具栏按钮）即可立即撤销访问权限。

安装并配对

  1. 输出未打包扩展的路径：

    bash
    openclaw browser extension path

  2. 打开 chrome://extensions，启用 Developer mode，点击 Load unpacked，然后选择输出的目录。

  3. 输出配对字符串：

    bash
    openclaw browser extension pair

  4. 点击 OpenClaw 工具栏图标，将配对字符串粘贴到弹出窗口中。 扩展连接到中继后，徽标会变为 ON。

配对令牌是首次使用时创建的主机本地密钥，存储在状态目录的 credentials/ 下（权限模式为 0600）。每台运行浏览器的机器（Gateway 网关主机以及每台浏览器节点主机）都拥有自己的令牌，因此无需在机器之间传输凭据。若要轮换令牌，请删除 browser-extension-relay.secret 文件，然后重新配对。

使用方法

在 browser 工具调用中选择内置的 chrome 配置文件，或将其设为默认配置文件：

bash
openclaw config set browser.defaultProfile chrome
json5
{  browser: {    profiles: {      chrome: { driver: "extension", color: "#FF4500" },    },  },}
  • 共享标签页：在该标签页中点击 OpenClaw 工具栏按钮（它会加入 OpenClaw 标签页组），或将任意标签页拖入该组。
  • 智能体也可以打开新标签页；这些标签页会自动加入该组。
  • 撤销访问权限：再次点击按钮、将标签页拖出组，或关闭 Chrome 的调试横幅。智能体会立即失去对该标签页的访问权限。

远程／跨机器使用

Chrome 无需运行在 Gateway 网关主机上。支持以下三种拓扑：

  • 同一主机（Gateway 网关与 Chrome 位于同一台机器）：在该机器上使用 openclaw browser extension pair 进行配对。中继仅限 local loopback。
  • 直接连接远程 Gateway 网关（Chrome 位于你的笔记本电脑上，Gateway 网关位于 VPS 上，并且笔记本电脑上没有运行任何其他组件）：在 Gateway 网关上运行 openclaw browser extension pair --gateway-url wss://your-gateway.example.com。 它会输出一个 wss://…/browser/extension#<secret> 字符串；在笔记本电脑上加载扩展并进行配对。扩展通过 wss:// 直接连接 Gateway 网关——笔记本电脑上无需安装 OpenClaw、Node 或 CLI，也无需开放入站端口。这是托管服务场景使用的路径。
  • 通过浏览器节点主机（Chrome 位于已运行 OpenClaw 节点的机器上）：在节点上运行 pair 并进行本地配对；Gateway 网关通过现有的已验证节点链路，将浏览器操作代理到该节点。

配对密钥按主机独立设置（直接连接时为 Gateway 网关的密钥），由 Gateway 网关的 /browser/extension 路由验证。使用直接连接路径时，请通过 TLS（wss://）提供 Gateway 网关服务，以加密配对密钥和 CDP 流量。 密钥保留在配对字符串的 URL 片段中，并在 WebSocket 握手期间作为子协议凭据提供，因此常规代理访问日志不会从请求 URL 中获取该密钥。请确保所有反向代理都保留标准的 Sec-WebSocket-Protocol 标头。

诊断

bash
openclaw browser status --browser-profile chromeopenclaw browser doctor --browser-profile chrome

在扩展弹出窗口显示 Connected 之前，doctor 会将 Chrome 扩展中继检查报告为失败。

安全模型

  • 中继仅绑定 local loopback；WebSocket 双方都使用派生令牌进行身份验证，并且扩展端会检查来源是否为 chrome-extension://。
  • 直接 Gateway 网关配对不接受请求 URL 中的中继令牌；内置扩展改为通过 WebSocket 子协议列表携带该令牌。
  • 智能体只能查看和操控 OpenClaw 标签页组中的标签页。你的其他标签页会保持私密。
  • 相较于 user（Chrome MCP）配置文件——一旦你批准远程调试提示，它就会开放整个已登录的浏览器——该扩展将共享范围限定在你一眼即可查看和控制的标签页组内。

另请参阅：浏览器，了解完整的配置文件模型，以及托管的 openclaw 配置文件和 Chrome MCP user 配置文件。

Was this useful?
On this page

On this page