文档
工具（Tools）
Chrome 扩展（浏览器中继）

Chrome 扩展（浏览器中继）

适用范围

在以下情况使用本页面：

  • 您希望代理驱动现有的 Chrome 选项卡（工具栏按钮）
  • 您需要通过 Tailscale 进行远程网关 + 本地浏览器自动化
  • 您想了解浏览器接管的安全影响

Moltbot Chrome 扩展允许代理控制您的现有 Chrome 选项卡（您的正常 Chrome 窗口），而不是启动单独的 clawd 托管的 Chrome 配置文件。

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

它是什么（概念）

有三个部分：

  • 浏览器控制服务器（HTTP）：代理/工具调用的 API（browser.controlUrl）
  • 本地中继服务器（loopback CDP）：在控制服务器和扩展之间桥接（默认 http://127.0.0.1:18792）
  • Chrome MV3 扩展：使用 chrome.debugger 附加到活动选项卡并将 CDP 消息管道传输到中继

然后 Moltbot 通过正常的 browser 工具表面控制附加的选项卡（选择正确的配置文件）。

安装/加载（未打包）

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

更新（无需构建步骤）

扩展作为静态文件在 Moltbot 发布（npm 包）中发布。没有单独的"构建"步骤。

升级 Moltbot 后：

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

使用它（无需额外配置）

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

使用它：

  • CLI：moltbot browser --browser-profile chrome tabs
  • 代理工具：browser 与 profile="chrome"

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

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

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

  • 打开您希望 Moltbot 控制的选项卡。
  • 单击扩展图标。
    • 徽章在附加时显示 ON。
  • 再次单击以分离。

它控制哪个选项卡？

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

徽章 + 常见错误

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

如果您看到 !：

  • 确保网关在本地运行（默认设置），或者在此机器上运行 moltbot browser serve（远程网关设置）。
  • 打开扩展选项页面；它显示中继是否可达。

我需要 moltbot browser serve 吗？

本地网关（与 Chrome 相同的机器）——通常不需要

如果网关在与 Chrome 相同的机器上运行，并且您的 browser.controlUrl 是 loopback（默认）， 您通常不需要 moltbot browser serve。

网关的内置浏览器控制服务器将在 http://127.0.0.1:18791/ 上启动，Moltbot 将 在 http://127.0.0.1:18792/ 上自动启动本地中继服务器。

远程网关（网关在其他地方运行）——需要

如果您的网关在另一台机器上运行，请在运行 Chrome 的机器上运行 moltbot browser serve （并通过 Tailscale Serve / TLS 发布）。参见下面的部分。

沙箱（工具容器）

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

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

选项：

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

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

调试：moltbot sandbox explain

远程网关（推荐：Tailscale Serve）

目标：网关在一台机器上运行，但 Chrome 在其他地方运行。

在浏览器机器上：

moltbot browser serve --bind 127.0.0.1 --port 18791 --token <token>
tailscale serve https / http://127.0.0.1:18791

在网关机器上：

  • 将 browser.controlUrl 设置为 HTTPS Serve URL（MagicDNS/ts.net）。
  • 提供令牌（最好使用环境变量）：
export MOLTBOT_BROWSER_CONTROL_TOKEN="<token>"

然后代理可以通过调用远程 browser.controlUrl API 来驱动浏览器，而扩展 + 中继保持在浏览器机器上本地。

“扩展路径"如何工作

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

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

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

安全影响（请阅读此内容）

这很强大且有风险。把它当作给模型"在浏览器上的手”。

  • 扩展使用 Chrome 的调试器 API（chrome.debugger）。附加时，模型可以：
    • 在该选项卡中单击/输入/导航
    • 读取页面内容
    • 访问选项卡的登录会话可以访问的任何内容
  • 这不是隔离的，就像专用的 clawd 托管配置文件。
    • 如果您附加到日常驱动程序配置文件/选项卡，您将授予对该账户状态的访问权限。

建议：

  • 最好为扩展中继使用专用的 Chrome 配置文件（与个人浏览分开）。
  • 保持浏览器控制服务器仅限 tailnet（Tailscale）并要求令牌。
  • 避免在 LAN（0.0.0.0）上暴露浏览器控制，并避免 Funnel（公共）。

相关：

apply_patch 工具ClawdHub