Chrome 扩展（浏览器中继）

OpenClaw Chrome 扩展让代理控制你已有的 Chrome 标签页（你正常使用的 Chrome 窗口），而不需要启动一个单独的 openclaw 托管 Chrome 配置文件。

附加/解除通过 Chrome 工具栏上的一个按钮完成。

如果你想用 Chrome 官方的 DevTools MCP 附加流程而非 OpenClaw 扩展中继，请使用 existing-session 浏览器配置文件。参见 浏览器。关于 Chrome 自身的设置文档，参见 Chrome for Developers: Use Chrome DevTools MCP with your browser session 和 Chrome DevTools MCP README。

概念

有三个部分：

  • 浏览器控制服务（网关或节点）：代理/工具调用的 API（通过网关）
  • 本地中继服务器（回环 CDP）：在控制服务和扩展之间桥接（默认 http://127.0.0.1:18792）
  • Chrome MV3 扩展：使用 chrome.debugger 附加到活跃标签页，把 CDP 消息传给中继

然后 OpenClaw 通过正常的 browser 工具面（选择正确的配置文件）来控制附加的标签页。

安装/加载（未打包模式）

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

更新（无需构建）

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

升级 OpenClaw 后：

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

使用（设置一次网关 token）

OpenClaw 自带一个名为 chrome 的内置浏览器配置文件，指向默认端口的扩展中继。

首次附加前，打开扩展选项页面并设置：

  • Port（默认 18792）
  • Gateway token（必须匹配 gateway.auth.token / OPENCLAW_GATEWAY_TOKEN）

使用方式：

  • 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"

自定义网关端口

如果你使用了自定义网关端口，扩展中继端口会自动推导：

扩展中继端口 = 网关端口 + 3

比如：如果 gateway.port: 19001，那么：

  • 扩展中继端口：19004（网关 + 3）

在扩展选项页面中配置推导出的中继端口。

附加/解除（工具栏按钮）

  • 打开你想让 OpenClaw 控制的标签页。
  • 点击扩展图标。
    • 徽章显示 ON 表示已附加。
  • 再次点击解除附加。

它控制的是哪个标签页？

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

徽章 + 常见错误

  • ON：已附加；OpenClaw 可以控制该标签页。
  • ...：正在连接本地中继。
  • !：中继不可达/未认证（最常见原因：中继服务器没运行，或网关 token 缺失/错误）。

如果看到 !：

  • 确保网关在本地运行（默认配置），或者如果网关在别处运行，在本机运行节点主机。
  • 打开扩展选项页面；它会验证中继可达性 + 网关 token 认证。

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

本地网关（和 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"。

调试：openclaw sandbox explain

远程访问建议

  • 保持网关和节点主机在同一个 tailnet 上；避免将中继端口暴露到局域网或公网。
  • 有意识地配对节点；不需要远程控制时禁用浏览器代理路由（gateway.nodes.browser.mode="off"）。
  • 默认让中继保持回环绑定，除非你确实有跨命名空间的需求。对于 WSL2 等分离主机场景，将 browser.relayBindHost 设为显式绑定地址如 0.0.0.0，然后通过网关认证、节点配对和私有网络来约束访问。

“extension path” 的工作原理

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

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

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

安全影响（请务必阅读）

这功能强大但有风险。把它当作给模型”在你浏览器上的操控权”。

  • 扩展使用 Chrome 的调试器 API（chrome.debugger）。附加后，模型可以：
    • 在该标签页中点击/输入/导航
    • 读取页面内容
    • 访问该标签页已登录会话能访问的一切
  • 这不像专用的 openclaw 托管配置文件那样隔离。
    • 如果你附加到日常使用的配置文件/标签页，你就授予了对那个账号状态的访问权。

建议：

  • 优先使用专用的 Chrome 配置文件（和个人浏览分开）来使用扩展中继。
  • 保持网关和节点主机仅 tailnet 可达；依赖网关认证 + 节点配对。
  • 避免在局域网（0.0.0.0）上暴露中继端口，也避免 Funnel（公网）。
  • 中继阻止非扩展来源，并要求 /cdp 和 /extension 端点的网关 token 认证。

相关文档：

arrow_back
上一页
Browser Login
下一页
Browser Linux Troubleshooting
arrow_forward