Chrome 扩展

Chrome 扩展（浏览器中继）

OpenClaw Chrome 扩展允许代理控制你现有的 Chrome 标签页（你的正常 Chrome 窗口），而不是启动单独的 OpenClaw 管理的 Chrome 配置文件。连接/断开通过单个 Chrome 工具栏按钮完成。

概念说明

有三个部分：

浏览器控制服务（Gateway 或节点）：代理/工具调用的 API（通过 Gateway）
本地中继服务器（回环 CDP）：在控制服务和扩展之间架桥（默认 http://127.0.0.1:18792）
Chrome MV3 扩展：使用 chrome.debugger 连接到活跃标签页，并将 CDP 消息管道传输到中继

OpenClaw 然后通过正常的 browser 工具接口控制连接的标签页（选择正确的配置文件）。

安装 / 加载（非打包）

将扩展安装到稳定的本地路径：
bash
```
openclaw browser extension install
```
1
打印已安装的扩展目录路径：
bash
```
openclaw browser extension path
```
1
Chrome → chrome://extensions
- 启用"开发者模式"
- "加载已解压的扩展程序" → 选择上面打印的目录
固定该扩展。

更新（无构建步骤）

扩展作为静态文件包含在 OpenClaw 发行版（npm 包）中。没有单独的"构建"步骤。升级 OpenClaw 后：

重新运行 openclaw browser extension install 以刷新 OpenClaw 状态目录下的已安装文件。
Chrome → chrome://extensions → 点击扩展上的"重新加载"。

使用它（设置一次 Gateway 令牌）

OpenClaw 内置了一个名为 chrome 的浏览器配置文件，目标是默认端口上的扩展中继。首次连接前，打开扩展选项并设置：

Port（默认 18792）
Gateway token（必须匹配 gateway.auth.token / OPENCLAW_GATEWAY_TOKEN）

使用方式：

CLI：openclaw browser --browser-profile chrome tabs
代理工具：browser 配合 profile="chrome"

如果你想要不同的名称或不同的中继端口，创建你自己的配置文件：

bash

openclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

自定义 Gateway 端口

如果你使用自定义 Gateway 端口，扩展中继端口会自动派生：扩展中继端口 = Gateway 端口 + 3 示例：如果 gateway.port: 19001，则：

扩展中继端口：19004（gateway + 3）

在扩展选项页面中配置使用派生的中继端口。

连接 / 断开（工具栏按钮）

打开你希望 OpenClaw 控制的标签页。
点击扩展图标。
徽章显示 ON 表示已连接。
再次点击断开。

控制哪个标签页？

它不会自动控制"你正在查看的任何标签页"。
它仅控制你通过点击工具栏按钮显式连接的标签页。
要切换：打开另一个标签页并在那里点击扩展图标。

徽章 + 常见错误

ON：已连接；OpenClaw 可以驱动该标签页。
…：正在连接到本地中继。
!：中继不可达/未认证（最常见原因：中继服务器未运行，或 Gateway 令牌缺失/错误）。

如果你看到 !：

确保 Gateway 正在本地运行（默认设置），或者如果 Gateway 在其他地方运行，则在此机器上运行节点主机。
打开扩展选项页面；它会验证中继可达性 + Gateway 令牌认证。

远程 Gateway（使用节点主机）

本地 Gateway（与 Chrome 同一台机器）— 通常无需额外步骤

如果 Gateway 在与 Chrome 相同的机器上运行，它会在回环上启动浏览器控制服务并自动启动中继服务器。扩展与本地中继通信；CLI/工具调用发送到 Gateway。

远程 Gateway（Gateway 在其他地方运行）— 运行节点主机

如果你的 Gateway 在另一台机器上运行，在运行 Chrome 的机器上启动节点主机。Gateway 会将浏览器操作代理到该节点；扩展 + 中继保持在浏览器机器本地。

如果连接了多个节点，使用 gateway.nodes.browser.node 固定一个或设置 gateway.nodes.browser.mode。

沙箱（工具容器）

如果你的代理会话处于沙箱模式（agents.defaults.sandbox.mode != "off"），browser 工具可能会受到限制：

默认情况下，沙箱会话通常以沙箱浏览器（target="sandbox"）为目标，而不是你的宿主 Chrome。
Chrome 扩展中继接管需要控制宿主浏览器控制服务。

选项：

最简单：从非沙箱会话/代理使用扩展。

或者为沙箱会话允许宿主浏览器控制：

json5

{
  agents: {
    defaults: {
      sandbox: {
        browser: {
          allowHostControl: true,
        },
      },
    },
  },
}

然后确保工具未被工具策略拒绝，并（如需要）使用 target="host" 调用 browser。

调试：openclaw sandbox explain

远程访问提示

将 Gateway 和节点主机保持在同一个 tailnet 上；避免将中继端口暴露到局域网或公共互联网。
有意识地配对节点；如果你不想远程控制，禁用浏览器代理路由（gateway.nodes.browser.mode="off"）。

"extension path" 的工作原理

openclaw browser extension path 打印包含扩展文件的已安装磁盘目录。CLI 故意不打印 node_modules 路径。始终先运行 openclaw browser extension install 将扩展复制到 OpenClaw 状态目录下的稳定位置。

如果你移动或删除了该安装目录，Chrome 会将扩展标记为损坏，直到你从有效路径重新加载。

安全影响（请阅读）

这功能强大但有风险。将其视为给模型"在你的浏览器上操作的双手"。

扩展使用 Chrome 的调试器 API（chrome.debugger）。连接时，模型可以：
- 在该标签页中点击/输入/导航
- 读取页面内容
- 访问该标签页已登录会话可以访问的任何内容
这不像专用的 OpenClaw 管理的配置文件那样隔离。
如果你连接到你的日常使用配置文件/标签页，你就是在授予对该账户状态的访问权限。

建议：

优先使用专用的 Chrome 配置文件（与你的个人浏览分开）进行扩展中继使用。
将 Gateway 和任何节点主机保持在仅 tailnet 可访问；依赖 Gateway 认证 + 节点配对。
避免通过局域网（0.0.0.0）暴露中继端口，避免使用 Funnel（公共）。
中继阻止非扩展来源，并且 /cdp 和 /extension 都需要 Gateway 令牌认证。

Chrome 扩展 ​

Chrome 扩展（浏览器中继） ​

概念说明 ​

安装 / 加载（非打包） ​

更新（无构建步骤） ​

使用它（设置一次 Gateway 令牌） ​

自定义 Gateway 端口 ​

连接 / 断开（工具栏按钮） ​

控制哪个标签页？ ​

徽章 + 常见错误 ​

远程 Gateway（使用节点主机） ​

本地 Gateway（与 Chrome 同一台机器）— 通常无需额外步骤 ​

远程 Gateway（Gateway 在其他地方运行）— 运行节点主机 ​

沙箱（工具容器） ​

远程访问提示 ​

"extension path" 的工作原理 ​

安全影响（请阅读） ​