Chrome 扩展（浏览器中继）

OpenClaw Chrome 扩展让代理控制你的现有 Chrome 标签（你的普通 Chrome 窗口），而不是启动单独的 openclaw 托管 Chrome 配置文件。

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

它是什么（概念）

有三部分：

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

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

安装/加载（未打包）

  1. 将扩展安装到稳定的本地路径：
openclaw browser extension install
  1. 打印已安装的扩展目录路径：
openclaw browser extension path
  1. Chrome 中访问 chrome://extensions
  • 启用”开发者模式”
  • “加载未打包的” 并选择上面打印的目录
  1. 固定扩展。

更新（无需构建步骤）

扩展作为静态文件附带在 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"

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

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-token 认证?

远程 Gateway（使用节点主机）

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

如果 Gateway ?Chrome 运行在同一台机器上，它会在 loopback 上启动浏览器控制服务并自动启动中继服务器。扩展与本地中继对话；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 扩展中继接管需要控?*主机**浏览器控制服务器?

选项?

  • 最简单：?*非沙箱化**会话/代理使用扩展?
  • 或为沙箱化会话允许主机浏览器控制?
{
  agents: {
    defaults: {
      sandbox: {
        browser: {
          allowHostControl: true,
        },
      },
    },
  },
}

然后确保工具没有被工具策略拒绝，并且（如需要）?target="host" 调用 browser?

调试：openclaw sandbox explain

远程访问提示

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

”扩展路径”如何工作

openclaw browser extension path 打印包含扩展文件?*已安?*磁盘目录?

CLI 故意**?*打印 node_modules 路径。始终先运行 openclaw browser extension install 将扩展复制到 OpenClaw 状态目录下的稳定位置?

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

安全影响（请阅读?

这很强大也有风险。把它想象成给模?把手放在你的浏览器上”?

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

建议?

  • 优先使用专用 Chrome 配置文件（与你的个人浏览分开）用于扩展中继使用?
  • 保持 Gateway 和任何节点主机仅?tailnet；依?Gateway 认证 + 节点配对?
  • 避免通过 LAN（0.0.0.0）暴露中继端口，避免 Funnel（公共）?
  • 中继阻止非扩展来源，并为 /cdp ?/extension 都需?gateway-token 认证?

相关?