Chrome 扩展（浏览器中继）

Moltbot Chrome 扩展让代理控制你现有的 Chrome 标签（你的正常 Chrome 窗口），而无需启动独立的 clawd 托管 Chrome 配置。通过一个 Chrome 工具栏按钮进行附加/分离。

概念（三部分）

浏览器控制服务（网关或节点）：代理/工具调用的 API（经网关）
本地中继服务器（回环 CDP）：在控制服务与扩展之间桥接（默认 http://127.0.0.1:18792）
Chrome MV3 扩展：使用 chrome.debugger 附加到当前标签，将 CDP 消息管道到中继

Moltbot 通过常规 browser 工具表面（选择正确配置）控制已附加的标签。

安装 / 加载（解压）

将扩展安装到稳定本地路径：moltbot browser extension install
打印已安装扩展目录：moltbot browser extension path
Chrome → chrome://extensions → 开启“开发者模式”→“加载已解压的扩展程序”→ 选择上一步打印的目录
固定扩展。

更新（无构建步骤）

扩展随 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 可驱动该标签。
…：正在连接本地中继。
!：中继不可达（最常见：本机未运行浏览器中继服务）。

若看到 !：确保网关在本地运行（默认部署），或若网关在别处则在本机运行节点主机。打开扩展选项页可查看中继是否可达。

远程网关（使用节点主机）

本地网关（与 Chrome 同机）— 通常无需额外步骤

若网关与 Chrome 在同一机器，网关会在回环启动浏览器控制服务并自动启动中继。扩展与本地中继通信；CLI/工具调用发往网关。

远程网关（网关在别处）— 需运行节点主机

若网关在另一台机器，请在运行 Chrome 的机器上启动节点主机。网关会将浏览器操作代理到该节点；扩展与中继仍留在浏览器所在机器。若连接了多个节点，可通过 gateway.nodes.browser.node 固定一个，或设置 gateway.nodes.browser.mode。

沙箱（工具容器）

若代理会话处于沙箱（agents.defaults.sandbox.mode != "off"），browser 工具可能受限：

默认沙箱会话常指向沙箱浏览器（target="sandbox"），而非你的主机 Chrome。
Chrome 扩展中继接管需要控制主机浏览器控制服务。

可选做法：最简单是使用非沙箱会话/代理；或允许沙箱会话使用主机浏览器控制：


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

然后确保工具未被工具策略拒绝，必要时在调用 browser 时使用 target="host"。调试：moltbot sandbox explain。

远程访问建议

将网关与节点主机放在同一 tailnet；避免将中继端口暴露到 LAN 或公网。
有意配对节点；若不需要远程控制可关闭浏览器代理路由（gateway.nodes.browser.mode="off"）。

“extension path” 如何工作

moltbot browser extension path 打印已安装的、包含扩展文件的磁盘目录。CLI intentionally 不打印 node_modules 路径。请先运行 moltbot browser extension install 将扩展复制到 Moltbot 状态目录下的稳定位置。若移动或删除该安装目录，Chrome 会将扩展标为损坏，直到从有效路径重新加载。

安全影响（必读）

功能强但风险高；相当于给模型“对你浏览器的操作权”。

扩展使用 Chrome 的 debugger API（chrome.debugger）。附加后，模型可：在该标签内点击/输入/导航、读取页面内容、访问该标签已登录会话能访问的一切。
与专用 clawd 托管配置不同，无隔离。若附加到日常使用的配置/标签，即授予对该账号状态的访问。

建议：优先为扩展中继使用专用 Chrome 配置（与个人浏览分开）。保持网关与节点主机仅限 tailnet；依赖网关认证与节点配对。避免将中继端口暴露到 LAN（0.0.0.0），避免 Funnel（公网）。