Chrome extension（浏览器中继）

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

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

它是什么（概念）

有三个部分：

  • Browser control service（浏览器控制服务）（Gateway 或 node）：agent/tool 调用的 API（通过 Gateway）
  • Local relay server（本地中继服务器）（loopback CDP）：在控制服务器和扩展之间桥接（默认 http://127.0.0.1:18792）
  • Chrome MV3 extension（Chrome MV3 扩展）：使用 chrome.debugger 附加到活动标签页，并将 CDP 消息传输到中继

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

安装 / 加载（unpacked 未打包）

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

更新（无构建步骤）

扩展作为静态文件随 OpenClaw 发布（npm 包）一起提供。没有单独的"构建"步骤。

升级 OpenClaw 后：

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

使用它（无需额外配置）

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

使用它：

  • CLI：openclaw browser --browser-profile chrome tabs
  • Agent 工具：browser 带 profile="chrome"

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

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

附加 / 分离（工具栏按钮）

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

它控制哪个标签页？

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

Badge + 常见错误

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

如果你看到 !：

  • 确保 Gateway 在本地运行（默认设置），或者如果 Gateway 在别处运行，则在此机器上运行 node host。
  • 打开扩展选项页；它显示中继是否可访问。

远程 Gateway（使用 node host）

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

如果 Gateway 与 Chrome 在同一台机器上运行，它会在 loopback 上启动浏览器控制服务并自动启动中继服务器。扩展与本地中继通信；CLI/tool 调用转到 Gateway。

远程 Gateway（Gateway 在别处运行）— 运行 node host

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

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

沙箱化（工具容器）

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

  • 默认情况下，沙箱会话通常定位 sandbox browser（沙箱浏览器）（target="sandbox"），而不是你的 host Chrome。
  • Chrome 扩展中继接管需要控制 host 浏览器控制服务器。

选项：

  • 最简单：从 非沙箱 会话/agent 使用扩展。
  • 或允许沙箱会话的 host 浏览器控制：
{
  agents: {
    defaults: {
      sandbox: {
        browser: {
          allowHostControl: true
        }
      }
    }
  }
}

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

调试：openclaw sandbox explain

远程访问提示

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

"extension path" 的工作原理

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

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

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

安全影响（请阅读）

这很强大但也有风险。将其视为给模型 "在你的浏览器上操作的权限"。

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

建议：

  • 优先使用专用的 Chrome 配置文件（与你的个人浏览分开）用于扩展中继。
  • 将 Gateway 和任何 node hosts 保持在仅 tailnet 上；依赖 Gateway 认证 + node 配对。
  • 避免在 LAN（0.0.0.0）上暴露中继端口，避免使用 Funnel（公开）。

相关：

← 返回文档首页