OpenClaw 浏览器中继（Browser Relay）是一个 Chrome 扩展程序加本机中继：它让 OpenClaw 的浏览器工具直接操作你已经登录的 Chrome 里符合条件的标签页，而不是另开一个无头浏览器。截至 2026 年 10 月 9 日，官方文档给出的接入路径是：在装有 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
扩展通过 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 的浏览器工具一共有四种接入方式，命令里用 --browser-profile <name> 区分，不传时默认是 openclaw 或 browser.defaultProfile 设定的配置（浏览器总览与 CLI 文档）：
| 接入方式 | 配置名 | 操作的是哪个浏览器 | 适合的情况 |
|---|---|---|---|
| 扩展中继（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 验证
下面是文档给出的当前流程，按顺序执行。
-
升级 OpenClaw。
openclaw --version低于 2026.8.2 的先升级（原因见"安全通告"一节）；安装与升级步骤见 OpenClaw（原 Clawdbot）安装教程：各系统命令与验证。 -
安装扩展。运行下面的命令，保持它运行，然后完全退出 Chrome 再重新打开，在 Chrome 里批准应用商店的安装请求：
bashopenclaw browser extension install # 等待时间可以调整，例如 --wait-ms 60000；脚本里加 --json开发用途，或 Linux 这类拿不到应用商店请求的环境，改用
--no-store：命令会打印一个目录路径，到 chrome://extensions 开启开发者模式，用"加载已解压的扩展程序"选中那个路径。 -
配对。原生引导程序会自动完成配对。需要手动时运行
openclaw browser extension pair，把输出的配对字符串当密码对待，不要贴进聊天或工单。网关在另一台机器上时加--gateway-url wss://…；只要不是本机回环地址，就必须是wss://，明文ws://不被接受。所有--json输出都不会包含中继密钥（relay key），所以日志里找不到它不是异常。 -
让浏览器工具默认走扩展。两种写法等价：
bashopenclaw config set browser.defaultProfile chrome或者在配置文件里把
browser.profiles.chrome.driver设为"extension"。不改默认值也可以，每条命令带--browser-profile chrome。 -
验证。能列出标签页就说明扩展、中继和 OpenClaw 三者已经接通：
bashopenclaw 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，以及第一条命令序列
扩展有两种访问模式，在弹出窗口里切换：
- All tabs（默认）：扩展可以操作当前 Chrome 里所有符合条件的标签页。
- Selected tabs：只操作你放进名为 OpenClaw 的标签页组里的标签页，其他标签页对代理不可见。
个人浏览器里同时开着网银、邮箱和工作后台的，用 Selected tabs，把要自动化的页面拖进那个标签页组；如果连这一点也不放心，改用托管浏览器 openclaw，它根本不接触你的个人资料。无论哪种模式，弹出窗口里的 Pause / Allow 只作用于当前标签页，可以临时暂停代理对某个页面的操作。
以下标签页在任何模式下都不会被操作：无痕窗口、chrome:// 和 chrome-extension:// 页面、没有 URL 的标签页，以及 Chrome 应用商店页面；file:// 页面要先在扩展详情里打开"允许访问文件网址"。
CLI 文档给出的最短序列是 doctor → start → tabs → open。用扩展时 Chrome 本来就开着，重点是 tabs 能否列出标签页：
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-pagetabs 输出里的第一个 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 给出的核对顺序是：网关是否在运行；原生消息主机是否已注册；中继是否正在唤醒（空闲退出后每分钟最多唤醒一次）；端口是否被配置改过。对应命令：
openclaw browser extension status # 显示 waiting for local OpenClaw 说明扩展在等本机进程
openclaw browser extension cdp # 打印端口等非敏感元数据，核对实际在用的地址
openclaw browser doctor --browser-profile chrome网关没起来的，先按 OpenClaw 端口无法监听：完整故障排除指南 [2026] 处理，再回来重试扩展。
配对失败、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（现已全部关闭）记录了报告者给出的原因，其中一条写道，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）里按错误码查。
两份 2026 年安全通告：升级到 2026.2.1 与 2026.8.2 以上
浏览器中继本质上是把一条能读 Cookie、能执行 JavaScript 的通道接到你的个人浏览器上，所以它的安全通告值得单独看：
| 通告 | 影响版本 | 问题 | 修复版本 |
|---|---|---|---|
| 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（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 按命令切换。
