我们第一次干净地跑通 Relay 时，文件装完之后仍然失败了。原生宿主（native host）已经存在，中继端口也在监听，OpenClaw 却依然返回零个已附加标签页。这个失败恰恰是本文最有价值的部分：Browser Relay 是一条链路，而不是一条安装成功的绿色提示。
OpenClaw Browser Relay 是一条本地连接通路，让 OpenClaw 通过扩展程序、回环中继（loopback relay）以及经过鉴权的 Gateway 或浏览器节点，来检查和操作符合条件的 Chrome 标签页。它不是 OpenClaw 托管的浏览器，也不会仅仅因为 Chrome 已登录，就授予对所有标签页的访问权限。
什么是 OpenClaw Browser Relay，什么时候需要它？
Browser Relay（浏览器中继）适用于这样一种场景：任务必须在一个已经包含已批准会话的 Chrome 浏览器配置文件（Profile）中完成。该扩展程序会在符合条件的标签页上使用 Chrome 的调试器权限，然后通过 OpenClaw 的本地浏览器控制服务暴露这些标签页。浏览器仍然决定该扩展程序可以访问哪些页面。
这一区别很重要。OpenClaw 浏览器控制还包括托管配置文件（Profile）和其他 CDP 路线。Relay 是进入已批准 Chrome 标签页的扩展程序专用路线。只有当现有的浏览器状态是任务的一部分时，才选择它。
OpenClaw 的几种浏览器接入方式，哪种适合当前任务？
从任务所需的状态开始，而不是从最熟悉的命令开始。下表将控制对象与操作负担分开。
| 路线 | 它能做什么 | 它不能假设什么 |
|---|---|---|
| 托管浏览器 | 启动一个单独的、由 OpenClaw 拥有的 Chrome 浏览器配置文件（Profile），并产生可重复的浏览器状态。 | 它不会继承日常 Chrome 中的 Cookie 或标签页。 |
| Browser Relay | 在已批准的、已登录的 Chrome 浏览器配置文件（Profile）中操作符合条件的标签页。 | 它无法绕过标签页访问限制、Chrome 排除项、MFA 或站点策略。 |
| 远程 CDP | 将 OpenClaw 连接到一个单独配置的浏览器端点。 | 它默认不会让端点暴露或凭证变得安全。 |
安装前需要准备什么？
截至 2026 年 9 月 10 日，官方 Chrome 扩展程序页面列出了在故障排查之前应完成的三项检查：当前版本的 OpenClaw CLI、受支持的 Chrome 系列浏览器，以及为所选配对运行中的 Gateway 或浏览器节点。当前的 npm 版本在我们的测试中增加了第四项：OpenClaw 2026.9.3 需要 Node 24.16.0 或更高版本。
node --version
openclaw --version
openclaw browser extension status --json
openclaw browser profiles --json
使用官方 OpenClaw Chrome 扩展程序文档并在安装前验证 Chrome 应用商店的发布者。GitHub 分支可能对研究有用，但它不定义官方 ID、权限模型或默认行为。
如何安装并连接 OpenClaw Browser Relay？
运行安装程序，并在 Chrome 完成其设置部分时保持终端打开。在 macOS 上，该命令会注册原生宿主（native host）并请求应用商店扩展程序。Chrome 可能需要完全退出并重新打开才会显示该请求。OpenClaw 不会替你批准 Chrome 的权限提示。
openclaw browser extension install --json
openclaw gateway run
openclaw browser --browser-profile chrome tabs --json该失败揭示了一条实用规则：当需要走应用商店路径时，不要用随机的解压副本替换身份检查。完成 Chrome 的官方批准流程，然后验证已连接的标签页。
如何验证扩展程序、Gateway、中继和标签页？
良好的验证从宿主向外进行。我们的第一次 doctor 运行失败，因为缺少 Gateway 凭证。在启动一个隔离的、基于 Token 认证的 Gateway 后，端点和插件通过了，而托管浏览器正确地保持未运行状态。启动该浏览器后，所有七项 doctor 检查都变为通过。该对照案例证明了服务正常工作，但并未证明 Relay 连接性。
# Layer 1: Gateway and browser service
openclaw browser doctor --json
# Layer 2: extension files and native host
openclaw browser extension status --json
# Layer 3: extension-backed profile
openclaw browser --browser-profile chrome tabs --json
# Layer 4: reversible action on the intended test tab
openclaw browser --browser-profile chrome snapshot --efficient| 层级 | 可提供的证据 | 它仍然无法证明什么 |
|---|---|---|
| Gateway | doctor 显示浏览器控制端点可达 | 尚未附加任何 Chrome 标签页。 |
| 原生宿主（native host） | 注册状态已归属，且扩展 ID 已获批准 | 扩展程序可能仍处于暂停或断开状态。 |
| Relay 配置文件 | chrome profile 报告了预期的标签页 | 该标签页可能属于错误的账号或页面。 |
| 任务结果 | 一个低风险操作改变了预期的测试页面，并且第二次读取确认了该变化 | 一次成功并不能证明所有网站或未来版本都没问题。 |
如何排查 Browser Relay 的常见故障？
先诊断第一个出错的层级。重装扩展程序无法修复缺失的 Gateway Token，轮换 Token 也无法批准 Chrome 扩展程序。
| 症状 | 可能的层级 | 下一步检查 |
|---|---|---|
| CLI 在启动前就退出 | 运行时 | 用 node --version 与当前包的 engine 要求做对比。 |
| GatewayCredentialsRequiredError | Gateway 鉴权 | 传入已批准的 Token 或密码，并确认使用的是同一个配置路径。 |
| manualSetupRequired=true | Chrome 批准或原生宿主（native host） | 分别检查 installedCopy、registrations、Store 请求、发现的 ID 以及 Chrome 批准状态。 |
| chrome tabs 返回空列表 | Relay 或标签页访问权限 | 打开扩展程序的 Settings，确认连接状态、访问模式、目标浏览器配置文件（Profile）以及已选中的标签页。 |
| 切换模式后选错的标签页消失 | 已选标签页策略 | 确认该标签页仍在 OpenClaw 分组中，且没有跳到被排除的 URL。 |
哪些权限和证据可以安全分享？
扩展程序可以检查和操作已附加的合格标签页内容。请把截图、快照、URL 和控制台输出都当作账号数据对待。使用测试页面，抹掉姓名和 Token，只截取足以证明结果的那一层信息。
ego (lite) 适合用在哪里，又不适合用在哪里？
Relay 的故障是分层出现的，而这里的每一层都属于那座桥：Gateway Token、Chrome 对扩展程序身份的批准，以及原生宿主（native host）的注册与配对。ego (lite) 本身就是浏览器，所以 Agent 和页面之间没有中继，没有需要维持的连接，也没有哪一层会在你不知情的情况下断开。在 9 月 10 日的 QA 检查中，一个 Space 检查了八个文章页面在桌面宽度和 390 像素移动端宽度下的表现，核对了标题、图片、锚点、代码溢出、canonical，并真实点击了一次大纲。
这并不能修复 OpenClaw。使用 ego (lite) 快速开始当实际需求是为 Claude Code、Codex 或其他编码 Agent 提供一个独立的浏览器工作区时，请使用 ego (lite) 快速开始。当工作流依赖 OpenClaw 的 Gateway、Agent 系统、频道或浏览器 CLI 时，请继续使用 OpenClaw。
FAQ
OpenClaw Browser Relay 和托管浏览器是同一个东西吗？
不是。Relay 通过扩展程序连接已批准的 Chrome 浏览器配置文件（Profile）中符合条件的标签页。托管路线则启动一个由 OpenClaw 拥有的浏览器配置文件（Profile），状态相互独立。
扩展程序安装成功就能证明 Relay 已连接吗？
不能。需要确认原生宿主（native host）、扩展程序的实时状态、由扩展程序支持的浏览器配置文件（Profile）、目标标签页，以及一次可回退的操作后状态。
为什么 openclaw browser tabs 返回空列表？
空列表通常意味着该浏览器配置文件（Profile）下没有附加任何符合条件的标签页。请检查扩展程序连接、访问模式、浏览器配置文件（Profile）选择、标签页分组以及排除 URL 规则。
在我们的测试中，GatewayCredentialsRequiredError 是什么原因导致的？
CLI 在没有已批准的 Token 或密码的情况下访问了某个 Gateway 操作。启动一个隔离的、基于 Token 鉴权的 Gateway 修复了这一层，随后 doctor 暴露出下一层的状态，而不是重复报凭证错误。
Relay 能控制无痕窗口或 chrome:// 页面吗？
9 月 10 日的官方文档排除了无痕窗口、chrome://、chrome-extension:// 以及没有可用 URL 的标签页。file:// 还需要 Chrome 单独的文件访问权限。
Gateway Token 可以出现在截图里吗？
不可以。请抹掉 Token、Cookie、账号名和私有 URL。OpenClaw 的 JSON 状态输出设计上会省略 relay keys 和 pairing strings，但分享前仍要检查一遍。
Edge 能用同一个扩展程序吗？
本指南不声称支持 Edge，因为我们在 9 月 10 日的运行使用的是 macOS 上的 Google Chrome 152。在把步骤扩展到其他 Chromium 浏览器之前，请以当前官方浏览器支持说明为准。
测试结束后如何移除原生宿主（native host）？
运行 openclaw browser extension uninstall-host，然后再次检查扩展程序状态。我们的清理移除了八个自有产物，并使全部四个注册项恢复为 missing。
ego (lite) 能修复出问题的 OpenClaw Relay 吗？
不能。ego (lite) 不会修复 OpenClaw 的 Token、原生宿主（native host）注册、Gateway 配对或扩展程序状态，它本来也不是做这个的。当你真正想要的是一个供 Agent 使用的浏览器工作区，且不与自己在用的标签页冲突时，它才是更合适的选择。
