Chrome 扩展

Chrome 扩展 (浏览器中继)

OpenClaw Chrome 扩展允许代理控制你 现有的 Chrome 标签页（你正常的 Chrome 窗口），而不是启动一个单独的由 openclaw 托管的 Chrome 配置文件。

附加/分离通过 单个 Chrome 工具栏按钮 完成。

它是什么（概念）

它由三个部分组成：

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

然后，OpenClaw 通过正常的 browser 工具界面（选择正确的配置文件）控制附加的标签页。

安装 / 加载 (未解压)

将扩展安装到稳定的本地路径：

openclaw browser extension install

openclaw browser extension path

Chrome → chrome://extensions

启用“开发者模式”
“加载已解压的扩展程序” → 选择上面打印的目录

固定扩展程序。

更新 (无构建步骤)

扩展程序作为静态文件包含在 OpenClaw 发布版（npm 包）中。没有单独的“构建”步骤。

升级 OpenClaw 后：

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

使用它 (无需额外配置)

OpenClaw 附带一个名为 chrome 的内置浏览器配置文件，该配置文件针对默认端口上的扩展中继。

使用它：

CLI：openclaw browser --browser-profile chrome tabs
代理工具：browser 带有 profile="chrome"

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

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

附加 / 分离 (工具栏按钮)

打开你想要 OpenClaw 控制的标签页。
点击扩展图标。
- 附加后徽章显示 ON。
再次点击以分离。

它控制哪个标签页？

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

徽章 + 常见错误

ON：已附加；OpenClaw 可以驱动该标签页。
…：正在连接到本地中继。
!：中继不可达（最常见：浏览器中继服务器未在此机器上运行）。

如果你看到 !：

确保网关正在本地运行（默认设置），或者如果网关在其他地方运行，请在此机器上运行节点主机。
打开扩展程序的“选项”页面；它会显示中继是否可达。

远程网关 (使用节点主机)

本地网关 (与 Chrome 在同一台机器上) —— 通常无需额外步骤

如果网关与 Chrome 在同一台机器上运行，它会在回环上启动浏览器控制服务并自动启动中继服务器。扩展程序与本地中继通信；CLI/工具调用则转到网关。

远程网关 (网关在其他地方运行) —— 运行节点主机

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

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

沙盒化 (工具容器)

如果你的代理会话被沙盒化（agents.defaults.sandbox.mode != "off"），browser 工具可能会受到限制：

默认情况下，沙盒化会话通常针对 沙盒浏览器 (target="sandbox")，而不是你的主机 Chrome。
Chrome 扩展中继接管需要控制主机浏览器控制服务器。

选项：

最简单：从 非沙盒化 会话/代理使用扩展程序。
或者允许沙盒化会话的主机浏览器控制：

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

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

调试：openclaw sandbox explain

远程访问提示

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

“扩展路径”如何工作

openclaw browser extension path 打印包含扩展文件的磁盘上 已安装 的目录。

CLI 有意地不打印 node_modules 路径。始终先运行 openclaw browser extension install 以将扩展程序复制到 OpenClaw 状态目录下的稳定位置。

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

安全影响 (请阅读)

这非常强大但也很有风险。请将其视为让模型“上手你的浏览器”。

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

建议：

优先使用专用的 Chrome 配置文件（与你的个人浏览分开）进行扩展中继。
保持网关和任何节点主机仅限 tailnet；依赖网关身份验证 + 节点配对。
避免通过局域网 (0.0.0.0) 暴露中继端口，并避免 Funnel（公开）。