# OpenClaw 浏览器中继指南：Chrome 扩展配对、操作浏览器与报错排查

> OpenClaw 浏览器中继用 Chrome 扩展操作你已登录的 Chrome。按当前文档安装配对，排查感叹号与 not reachable after start，升级到安全通告要求的版本。

- Source: https://www.aifreeapi.com/zh/posts/openclaw-browser-relay-guide
- Language: zh
- Published: 2026-02-04
- Updated: 2026-10-09
- Publisher: AI Free API (https://www.aifreeapi.com)

OpenClaw 浏览器中继（Browser Relay）是一个 Chrome 扩展程序加本机中继：它让 OpenClaw 的浏览器工具直接操作你已经登录的 Chrome 里符合条件的标签页，而不是另开一个无头浏览器。截至 2026 年 10 月 9 日，[官方文档](https://docs.openclaw.ai/tools/chrome-extension)给出的接入路径是：在装有 OpenClaw 的同一台机器上运行 `openclaw browser extension install`，完全退出并重新打开 Chrome，批准扩展的安装请求，再用 `openclaw browser --browser-profile chrome tabs` 确认能列出标签页。配对由原生引导程序自动完成，正常情况下不需要手动复制任何密钥。

开始前先看版本。2026 年的两份安全通告分别要求 2026.2.1 和 2026.8.2 以上版本，`openclaw --version` 低于 2026.8.2 的先升级再配对。扩展图标出现红色感叹号、命令行报 `Relay unavailable`，或者报 `Chrome CDP websocket for profile "openclaw" is not reachable after start` 的，直接看后面的"报错排查"一节：前两个是中继连不上，最后一个出在托管浏览器 `openclaw` 配置上，与扩展无关。

## 浏览器中继是什么：用 Chrome 扩展操作你已登录的 Chrome

![OpenClaw 浏览器中继的连接路径：浏览器工具经网关或本机中继进入 Chrome 扩展，再由 chrome.debugger 附着到标签页](https://www.aifreeapi.com/posts/zh/openclaw-browser-relay-guide/img/cdp-architecture.png)

扩展通过 Chrome 的 `chrome.debugger` 接口附着到标签页，所以不需要用远程调试端口启动 Chrome，也不会弹出 Chrome 的远程调试授权提示。它只负责自动化基础设施：扩展本身没有聊天框或提示词输入，弹出窗口只显示连接状态、当前访问模式，以及对当前标签页的 Pause / Allow 开关。真正下指令的是 OpenClaw 的浏览器工具，经由网关（Gateway）的 `/browser/extension` 路由，或本机独立中继的 `ws://127.0.0.1:<port>/extension` 地址进入扩展。扩展申请的权限是 debugger、tabs、tabGroups、storage、alarms 和 nativeMessaging，在 chrome://extensions 里能对照查看。

底层协议是 Chrome DevTools Protocol（CDP），也就是 Chrome 开发者工具和浏览器之间那条 WebSocket 通道。无论是扩展中继还是托管浏览器，OpenClaw 最终都靠 CDP 读取页面、截图和点击，区别只在通道怎么建立：扩展中继借 `chrome.debugger` 进入你现有的 Chrome；托管浏览器则由 OpenClaw 自己启动一个带 CDP 端口的独立 Chromium。关于 CDP 知道这一点就够了，排错时它决定你该查哪一端。

![OpenClaw 浏览器工具的四种接入方式：扩展中继、托管浏览器、user 配置与远程 CDP](https://www.aifreeapi.com/posts/zh/openclaw-browser-relay-guide/img/browser-modes.png)

OpenClaw 的浏览器工具一共有四种接入方式，命令里用 `--browser-profile <name>` 区分，不传时默认是 `openclaw` 或 `browser.defaultProfile` 设定的配置（[浏览器总览](https://docs.openclaw.ai/tools/browser)与 [CLI 文档](https://docs.openclaw.ai/cli/browser)）：

| 接入方式 | 配置名 | 操作的是哪个浏览器 | 适合的情况 |
| --- | --- | --- | --- |
| 扩展中继（Browser Relay） | `chrome`（driver 为 `extension`） | 你正在用、已登录的 Chrome 里符合条件的标签页 | 任务依赖已登录状态，又不想把 Cookie 搬来搬去 |
| 托管浏览器 | `openclaw`（默认） | OpenClaw 启动的独立浏览器，用户数据目录与个人浏览器隔离 | 不想让代理接触个人资料；文档称它是"只给代理用的另一个浏览器" |
| 已登录 Chrome（DevTools MCP） | `user` | 你的 Chrome，通过 Chrome DevTools MCP 接入 | 已经在用 DevTools MCP 的环境 |
| 远程或托管 CDP | 自定义配置 | 另一台机器上的浏览器，或 Browserless、Browserbase、Notte 等服务 | 网关与浏览器分开部署 |

托管浏览器在 macOS 上只能把选定的 Cookie 复制进去，这是文档明确写出的限制；如果任务离不开你个人账号的登录态，扩展中继就是为这个场景准备的。

## 安装前的要求：Chrome 系浏览器、同一台机器，Windows 另需原生程序

文档列出的前提只有三条：

- 浏览器是 Google Chrome、Chrome for Testing 或 Chromium。
- OpenClaw 运行在这台机器上，或者这台机器上运行着一个 OpenClaw 浏览器节点；网关在别的机器上时，要在配对命令里用 `--gateway-url` 指定（见下一节）。
- 操作系统是 macOS 或 Linux；Windows 要有 `OpenClaw.BrowserBootstrap.exe` 这个原生可执行程序，它承担扩展与 OpenClaw 之间的原生消息桥。

Linux 还有一条限制：不会出现按用户弹出的 Chrome 应用商店安装请求。拿不到安装请求时，用下一节的 `--no-store` 方式手动加载扩展。

### Brave、Edge、Firefox 能不能用：只有 Chrome 系有扩展

扩展文档只列出 Google Chrome、Chrome for Testing 和 Chromium。Brave 和 Edge 出现在浏览器总览页的托管浏览器支持列表里（Chrome、Brave、Edge、Chromium），也就是说想让 OpenClaw 用 Brave，走 `openclaw` 托管配置由 OpenClaw 启动 Brave 即可；至于把扩展装进 Brave 或 Edge 能否配对成功，公开文档里没有记载，自己试了也不要指望文档里的排错项都适用。Firefox、Safari 和 Android 没有官方扩展文档，文档里也没有手机端的安装路径；需要在手机场景操作网页的，只能让 OpenClaw 运行在电脑上，用托管浏览器或远程 CDP。

## 安装与配对：从 `openclaw browser extension install` 到 `tabs` 验证

下面是文档给出的当前流程，按顺序执行。

1. 升级 OpenClaw。`openclaw --version` 低于 2026.8.2 的先升级（原因见"安全通告"一节）；安装与升级步骤见 [OpenClaw（原 Clawdbot）安装教程：各系统命令与验证](/zh/posts/openclaw-installation-guide)。

2. 安装扩展。运行下面的命令，保持它运行，然后完全退出 Chrome 再重新打开，在 Chrome 里批准应用商店的安装请求：

   ```bash
   openclaw browser extension install
   # 等待时间可以调整，例如 --wait-ms 60000；脚本里加 --json
   ```

   开发用途，或 Linux 这类拿不到应用商店请求的环境，改用 `--no-store`：命令会打印一个目录路径，到 chrome://extensions 开启开发者模式，用"加载已解压的扩展程序"选中那个路径。

3. 配对。原生引导程序会自动完成配对。需要手动时运行 `openclaw browser extension pair`，把输出的配对字符串当密码对待，不要贴进聊天或工单。网关在另一台机器上时加 `--gateway-url wss://…`；只要不是本机回环地址，就必须是 `wss://`，明文 `ws://` 不被接受。所有 `--json` 输出都不会包含中继密钥（relay key），所以日志里找不到它不是异常。

4. 让浏览器工具默认走扩展。两种写法等价：

   ```bash
   openclaw config set browser.defaultProfile chrome
   ```

   或者在配置文件里把 `browser.profiles.chrome.driver` 设为 `"extension"`。不改默认值也可以，每条命令带 `--browser-profile chrome`。

5. 验证。能列出标签页就说明扩展、中继和 OpenClaw 三者已经接通：

   ```bash
   openclaw browser --browser-profile chrome tabs
   ```

   要看更细的状态，用 `openclaw browser extension setup --action verify --json`（`--action` 还可取 `inspect`、`install`）、`openclaw browser extension status` 和 `openclaw browser doctor --browser-profile chrome`。

关于"验证 token"：文档里没有单独输入 token 的步骤。扩展与 OpenClaw 之间按 Browser Relay Authentication v2 握手，凭据就是配对时交换的中继密钥，由原生引导程序或 `pair` 命令写入，不需要你在扩展界面手动填写。配对失败的表现与处理见"报错排查"。

## 操作浏览器：All tabs 与 Selected tabs，以及第一条命令序列

![OpenClaw 浏览器中继的最短操作序列：doctor、tabs、open、snapshot、screenshot](https://www.aifreeapi.com/posts/zh/openclaw-browser-relay-guide/img/workflow-diagram.png)

扩展有两种访问模式，在弹出窗口里切换：

- All tabs（默认）：扩展可以操作当前 Chrome 里所有符合条件的标签页。
- Selected tabs：只操作你放进名为 OpenClaw 的标签页组里的标签页，其他标签页对代理不可见。

个人浏览器里同时开着网银、邮箱和工作后台的，用 Selected tabs，把要自动化的页面拖进那个标签页组；如果连这一点也不放心，改用托管浏览器 `openclaw`，它根本不接触你的个人资料。无论哪种模式，弹出窗口里的 Pause / Allow 只作用于当前标签页，可以临时暂停代理对某个页面的操作。

以下标签页在任何模式下都不会被操作：无痕窗口、`chrome://` 和 `chrome-extension://` 页面、没有 URL 的标签页，以及 Chrome 应用商店页面；`file://` 页面要先在扩展详情里打开"允许访问文件网址"。

CLI 文档给出的最短序列是 doctor → start → tabs → open。用扩展时 Chrome 本来就开着，重点是 `tabs` 能否列出标签页：

```bash
openclaw browser doctor --browser-profile chrome
openclaw browser --browser-profile chrome tabs
openclaw browser --browser-profile chrome open https://example.com
openclaw browser --browser-profile chrome snapshot
openclaw browser --browser-profile chrome screenshot --full-page
```

`tabs` 输出里的第一个 `suggestedTargetId` 就是后续命令默认操作的标签页；`snapshot` 加 `--urls` 会把链接地址一起列出；`screenshot` 支持 `--full-page`、`--ref` 和 `--labels`；`doctor --deep` 会多做一次实时快照检查。单次请求的超时是 30,000 毫秒，外加 10 秒传输余量，超过这个时间命令会报超时，不会一直等。下载的文件落在 `/tmp/openclaw/downloads`。

还有一个影响体感的细节：本机独立中继进程空闲 10 分钟后会退出，之后的唤醒每分钟最多一次。隔了很久再发第一条命令时等它一下，不要连续重发。

## 报错排查：感叹号、Relay unavailable 与 not reachable after start

扩展中继的链路有三层：网关、扩展与本机中继之间的配对、浏览器本身。排错先判断断在哪一层，再动手。

### 扩展图标红色感叹号、`Relay unavailable`：中继连不上

扩展图标上的红色"!"表示扩展连不上中继服务器，一个社区分支的扩展选项页里是这样解释这个标记的。文档对 `Relay unavailable` 给出的核对顺序是：网关是否在运行；原生消息主机是否已注册；中继是否正在唤醒（空闲退出后每分钟最多唤醒一次）；端口是否被配置改过。对应命令：

```bash
openclaw browser extension status          # 显示 waiting for local OpenClaw 说明扩展在等本机进程
openclaw browser extension cdp             # 打印端口等非敏感元数据，核对实际在用的地址
openclaw browser doctor --browser-profile chrome
```

网关没起来的，先按 [OpenClaw 端口无法监听：完整故障排除指南 [2026]](/zh/posts/openclaw-port-not-listening) 处理，再回来重试扩展。

### 配对失败、`no valid credentials available`、扩展版本不匹配

扩展弹窗提示版本不匹配（version mismatch）时，文档的处理是重新加载扩展并运行 `openclaw browser doctor --browser-profile chrome`；仍不匹配时重新执行 `openclaw browser extension install`，让扩展与本机 OpenClaw 回到同一版本。文档列出的其他配对类故障与处理：

- 原生消息主机未预注册、扩展没有 ID、扩展在引导程序之前就被加载：重新运行 `install`，然后完全退出 Chrome 再打开。Chromium 会按进程缓存"原生主机不存在"的结果，只关窗口不退出进程没有用。
- 提示自动设置已禁用：改用 `openclaw browser extension pair` 手动配对。

社区里还有一类报告值得知道：2026 年 3 月前后，有用户反馈 OpenClaw 强制启用 v2 设备认证后，旧版扩展与网关断连；另有用户描述扩展卡在"!"状态，WebSocket 认证失败并显示 `no valid credentials available`。这些是第三方描述，不是文档条目，但处理思路一致：先把 OpenClaw 与扩展升到同一版本，再重新配对。

### `not reachable after start`：托管浏览器 openclaw 的 CDP 没就绪

完整报错是 `Chrome CDP websocket for profile "openclaw" is not reachable after start`。这里的 profile 是 `openclaw`，也就是托管浏览器，不是扩展中继。它表示 OpenClaw 启动了自己的浏览器，但在限定时间内没连上它的 CDP WebSocket；CLI 文档的指引是先排查 CDP 就绪问题。

2026 年 4 月到 5 月，[项目仓库里一批同名 issue](https://github.com/openclaw/openclaw/issues?q=is%3Aissue+%22not+reachable+after+start%22)（现已全部关闭）记录了报告者给出的原因，其中一条写道，15 秒后网关杀掉 Chrome 并返回 `Error: Chrome CDP websocket for profile "openclaw" is not reachable after start`。报告的原因包括：

- 2026.4.11 与 2026.4.12 版本的回归，升级后恢复；
- 手动指定 CDP 端点能连上、托管启动却失败，多见于 VPS 与 Docker 环境；
- Windows 上就绪检测的超时太短；
- Chrome 启动后 1 到 2 秒内自行退出、更新后 DevToolsActivePort 文件写不出来（macOS ARM64 报告较多）；
- WSL2 或沙箱环境里，SSRF 私有网络策略拦住了本机回环 CDP，以及沙箱里写死的 127.0.0.1；
- 健康检查与附着检测的 bug；
- 配置目录里残留的 SingletonLock 文件，且没有重试退避。

这些来自 issue 标题与标签，不是官方结论。可行的处理顺序是：运行 `openclaw browser doctor --deep` 看就绪检查哪一步失败；确认版本不在 2026.4.11 或 2026.4.12 并升级到当前版本；确认没有上次留下的托管浏览器进程还在运行；Docker、VPS 与 WSL2 环境优先考虑网络策略。只要这条报错还在，扩展中继那边的 `--browser-profile chrome` 命令不受影响，可以先用扩展把任务做完。

### `start` 和 `tabs` 正常但 `open` 失败：导航策略在拦

CLI 文档专门写了这一条：启动和列标签页都正常，只有 `open` 或导航失败，通常是导航的 SSRF 防护策略在拦，而不是中继断了。目标是内网地址或本机服务时尤其常见。先换一个公网地址验证链路没问题，再按文档的导航策略配置放行你需要的目标，不要为此动中继的认证设置。

其他与浏览器中继无关的 OpenClaw 报错，可以在 [OpenClaw 错误排查中心：每个错误代码的完整修复指南（2026）](/zh/posts/openclaw-error-troubleshooting-center)里按错误码查。

## 两份 2026 年安全通告：升级到 2026.2.1 与 2026.8.2 以上

浏览器中继本质上是把一条能读 Cookie、能执行 JavaScript 的通道接到你的个人浏览器上，所以它的安全通告值得单独看：

| 通告 | 影响版本 | 问题 | 修复版本 |
| --- | --- | --- | --- |
| [CVE-2026-28458](https://www.sentinelone.com/vulnerability-database/cve-2026-28458/)（GHSA-mr32-vwc2-5j6h，2026 年 2 月 14 日） | 2026.1.20 至 2026.2.1 之前 | 中继的 `/cdp` WebSocket 端点（当时位于本机端口 18792）接受没有令牌的连接，浏览器里打开的任意网页都能向它发 CDP 命令，包括读取 Cookie、在其他标签页执行 JavaScript；CVSS 7.4（高） | 2026.2.1，WebSocket 升级时校验每会话密钥 |
| [GHSA-m78m-7h3q-q938](https://github.com/openclaw/openclaw/security/advisories/GHSA-m78m-7h3q-q938)（2026 年 9 月 11 日） | 2026.8.2 之前 | 中继在客户端证明持有中继密钥之前，就在一个全局的待认证池里占位；未认证的网络攻击者可以填满所有位置，让已配对的扩展无法完成 Browser Relay Authentication v2 握手。不泄露中继密钥与浏览器数据；CVSS 5.3（中） | 2026.8.2；另建议限制中继路由的网络访问，池被占满时重启中继 |

CVE-2026-28458 的版本范围与细节来自 SentinelOne 漏洞库对通告的摘要以及 GitHub 通告标题。两份通告合起来的结论很简单：装扩展之前先把 OpenClaw 升到 2026.8.2 或更新版本；中继和控制服务都只监听本机回环地址，不要把它们转发到公网；配对字符串按密码保管。

## 其他问题：端口、无痕窗口、手机与模式选择

### OpenClaw 浏览器中继用哪个端口？

文档不再写固定端口。中继端口来自配置文件，包括显式设置的 `cdpPort`；`openclaw browser extension cdp` 会打印当前实际使用的端口等非敏感信息，本机独立中继的地址格式是 `ws://127.0.0.1:<port>/extension`。网上流传的 18792 是 2026 年初那份通告所述版本的中继端口，不要把它当成现行默认值去开防火墙。

### 浏览器中继是无头浏览器吗？

不是。它操作的是你正在用的那个 Chrome 窗口里的标签页，登录态、插件和界面都是你自己的。需要隔离环境的，用托管浏览器 `openclaw` 或远程 CDP。

### 为什么无痕窗口和 chrome:// 页面操作不了？

这是文档写明的排除项：无痕窗口、`chrome://`、`chrome-extension://`、没有 URL 的标签页和 Chrome 应用商店页面都不在扩展可操作范围内，与配置无关。`file://` 页面则要在扩展详情里打开"允许访问文件网址"。

### 手机或 Android 上能用浏览器中继吗？

没有官方的 Android、Firefox 或 Safari 扩展文档。扩展需要 macOS、Linux 或 Windows 上的 Chrome 系浏览器，并且 OpenClaw 要运行在同一台机器上。

### 浏览器中继和托管浏览器怎么选？

任务依赖你个人账号的登录态，选扩展中继，并用 Selected tabs 限制可见范围；任务不需要登录态、或你不想让代理接触个人资料，选托管浏览器。两者可以并存，用 `--browser-profile` 按命令切换。