Chrome 扩展
Chrome 扩展：让 OpenClaw 驱动您现有的 Chrome 标签页
OpenClaw Chrome 扩展让代理控制您的现有 Chrome 标签页（您的普通 Chrome 窗口），而不是启动单独的 openclaw 管理的 Chrome 配置文件。
附加/分离通过单个 Chrome 工具栏按钮完成。
它是什么（概念）
有三个部分：
- 浏览器控制服务（网关或节点）：代理/工具调用的 API（通过网关）
- ''本地中继服务器''（环回 CDP）：在控制服务器和扩展之间桥接（默认 ''http://127.0.0.1:18792''）
- ''Chrome MV3 扩展''：使用 ''chrome.debugger'' 附加到活动标签页，并将 CDP 消息管道传输到中继
然后 OpenClaw 通过普通的 ''browser'' 工具界面控制附加的标签页（选择正确的配置文件）。
安装/加载（解压）
1. 将扩展安装到稳定的本地路径：
openclaw browser extension install
2. 打印已安装的扩展目录路径：
openclaw browser extension path
3. Chrome → ''chrome://extensions''
- 启用"开发者模式"
- "加载已解压的扩展程序" → 选择上面打印的目录
4. 固定扩展。
更新（无构建步骤）
扩展作为静态文件随 OpenClaw 发布（npm 包）提供。没有单独的"构建"步骤。
升级 OpenClaw 后：
- 重新运行 ''openclaw browser extension install'' 以刷新 OpenClaw 状态目录下安装的文件。
- Chrome → ''chrome://extensions'' → 点击扩展上的"重新加载"。
使用它（无需额外配置）
OpenClaw 附带一个名为 ''chrome'' 的内置浏览器配置文件，该配置文件在默认端口上针对扩展中继。
使用它：
- CLI：''openclaw browser --browser-profile chrome tabs''
- 代理工具：''browser'' 并设置 ''profile="chrome"''
如果您想要不同的名称或不同的中继端口，请创建自己的配置文件：
openclaw browser create-profile \ --name my-chrome \ --driver extension \ --cdp-url http://127.0.0.1:18792 \ --color "#00AA00"
附加/分离（工具栏按钮）
- 打开您希望 OpenClaw 控制的标签页。
- 点击扩展图标。
- 附加时徽章显示 ''ON''。
- 再次点击以分离。
它控制哪个标签页？
- 它不会自动控制"您正在查看的任何标签页"。
- 它仅控制您通过点击工具栏按钮明确附加的标签页。
- 要切换：打开另一个标签页并在那里点击扩展图标。
徽章 + 常见错误
- ''ON''：已附加；OpenClaw 可以驱动该标签页。
- ''…''：正在连接到本地中继。
- ''!''：中继不可达（最常见：浏览器中继服务器未在此机器上运行）。
如果您看到 ''!''：
- 确保网关在本地运行（默认设置），或者如果网关在其他地方运行，则在此机器上运行节点主机。
- 打开扩展选项页面；它显示中继是否可达。
远程网关（使用节点主机）
#
本地网关（与 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,
},
},
},
},
}然后确保工具未被工具策略拒绝，并（如果需要）使用 ''target="host"'' 调用 ''target="host"''。
调试：''openclaw sandbox explain''
远程访问提示
- 将网关和节点主机保持在同一个 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 配置文件（与您的个人浏览分开）用于扩展中继使用。
- 将网关和任何节点主机保持在仅 tailnet；依赖网关认证 + 节点配对。
- 避免通过 LAN（''0.0.0.0''）暴露中继端口，避免 Funnel（公共）。
- 中继阻止非扩展来源，并需要 CDP 客户端的内部认证令牌。
相关：
- 浏览器工具概述：''浏览器''
- 安全审计：''安全''
- Tailscale 设置：''Tailscale''