Chrome 扩展（浏览器中继）

OpenClaw Chrome 扩展让 Agent 可以控制你现有的 Chrome 标签页（你正常使用的 Chrome 窗口），而不是启动一个单独的 openclaw 管理的 Chrome Profile。

通过一个 Chrome 工具栏按钮就能连接/断开控制。

它是什么（概念）

这个系统由三部分组成：

• 浏览器控制服务（Gateway 或 node）：Agent/工具调用的 API（通过 Gateway）
• 本地中继服务器（loopback CDP）：在控制服务器和扩展之间架桥（默认是 http://127.0.0.1:18792）
• Chrome MV3 扩展：使用 chrome.debugger 连接到活动标签页，并将 CDP 消息传递给中继服务器

然后 OpenClaw 通过正常的 browser 工具界面（选择正确的 Profile）来控制连接的标签页。

安装/加载（解压模式）

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

openclaw browser extension install

2. 打印已安装扩展的目录路径：

openclaw browser extension path

3. Chrome → chrome://extensions

• 启用 “Developer mode”
• “Load unpacked” → 选择上面打印出的目录

4. 固定扩展图标。

更新（无需构建步骤）

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

升级 OpenClaw 后：

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

使用（无需额外配置）

OpenClaw 自带一个名为 chrome 的内置浏览器 Profile，它指向默认端口上的扩展中继服务器。

使用方法：

• 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 控制的标签页。
• 点击扩展图标。
  • 连接后徽章显示 ON。
• 再次点击即可断开。

它控制哪个标签页？

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

徽章 + 常见错误

• ON：已连接；OpenClaw 可以控制该标签页。
• …：正在连接到本地中继服务器。
• !：中继服务器无法访问（最常见原因：浏览器中继服务器没有在这台机器上运行）。

如果你看到 !：

• 确保 Gateway 在本地运行（默认设置），或者如果 Gateway 在别处运行，就在这台机器上运行一个 node host。
• 打开扩展的 Options 页面；它会显示中继服务器是否可访问。

远程 Gateway（使用 node host）

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

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

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

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

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

Sandbox（工具容器）

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

• 默认情况下，沙箱化的 Session 通常针对 Sandbox 浏览器（target="sandbox"），而不是你的宿主 Chrome。
• Chrome 扩展中继接管需要控制宿主浏览器控制服务器。

选项：

• 最简单：从非沙箱化 Session/Agent 使用扩展。
• 或者允许沙箱化 Session 控制宿主浏览器：

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

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

调试：openclaw sandbox explain

远程访问提示

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

“扩展路径”的工作原理

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

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

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

安全影响（请阅读）

这个功能很强大，但也有风险。把它当作给模型”操控你浏览器的权限”。

• 扩展使用 Chrome 的调试器 API（chrome.debugger）。连接后，模型可以：
  • 在该标签页中点击/输入/导航
  • 读取页面内容
  • 访问该标签页已登录 Session 可以访问的任何内容
• 这不是隔离的，不像专用的 openclaw 管理的 Profile。
  • 如果你连接到日常使用的 Profile/标签页，就等于授予了对该账户状态的访问权限。

建议：

• 优先使用专用的 Chrome Profile（与你的个人浏览分开）来使用扩展中继。
• 将 Gateway 和任何 node hosts 保持在 tailnet 内；依赖 Gateway 认证 + node 配对。
• 避免将中继端口暴露到局域网（0.0.0.0），避免使用 Funnel（公网）。
• 中继服务器会阻止非扩展来源，并要求 CDP 客户端提供内部认证令牌。

相关文档：

• Browser 工具概述：Browser
• 安全审计：Security
• Tailscale 设置：Tailscale