ClawCN - OpenClaw 中文版

主题

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 工具界面控制附加的标签页(选择正确的配置文件)。

安装/加载(解压) ​

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

更新(无构建步骤) ​

扩展作为静态文件包含在 OpenClaw 发布版(npm 包)中。没有单独的"构建"步骤。

升级 OpenClaw 后:

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

使用(无需额外配置) ​

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

使用方法:

  • 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"

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

  • 打开您想让 OpenClaw 控制的标签页。
  • 点击扩展图标。
    • 附加时徽章显示 ON。
  • 再次点击以分离。

它控制哪个标签页? ​

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

徽章 + 常见错误 ​

  • ON:已附加;OpenClaw 可以驱动该标签页。
  • …:正在连接到本地中继。
  • !:中继无法访问(最常见:浏览器中继服务器未在此机器上运行)。

如果您看到 !:

  • 确保 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 上;避免将中继端口暴露给 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 客户端提供内部身份验证令牌。

相关: