Browser Relay · SSH 隧道 · Gateway 端口 · 六步验收 Runbook
你在 VPS 或云端 Mac 上跑通了 OpenClaw Gateway，却希望用本机 Chrome 与官方 Browser Relay 扩展做网页自动化——而不是在容器里堆无头 Chromium。常见故障是扩展显示已连接，但 CDP 报 no tab is connected，或经 SSH 隧道 后出现 401、端口探测错位。本文写给要把「远端控制面 + 本机真实浏览器」落成可审计拓扑的开发者：先给决策矩阵在无头 Docker 与本机 Relay 之间选型，再用症状对照表对齐 18792 健康检查与隧道参数，最后按六步 Runbook验收。可与 无头浏览器 Skill 清单、Compose 网络排障 分工阅读。
OpenClaw 在 2026 年的默认路径里，Gateway 常监听 127.0.0.1:18789，而 Browser Relay 服务在开发机上多见于 127.0.0.1:18792。当你把 Gateway 搬到远端 VPS，控制面与浏览器面被拆到两个网络命名空间：Agent 以为浏览器「在 localhost」，实际却在你的笔记本上。社区 issue（如远程 Gateway + SSH 隧道场景）反复出现三类问题：中继认证只认本机 runtime 表导致隧道后 401、EADDRINUSE 探测端口与真实 Relay 端口不一致、以及扩展 ON 但无标签页挂载。若仍用「通道能回消息」当唯一验收，会把小时级排障浪费在模型超时上。
把扩展绿灯当成端到端通过：扩展 UI 显示 ON 只说明中继进程在听；未在目标站点打开标签并 Attach，CDP 仍会报无 tab。
隧道方向搞反：需要让远端 Gateway 能访问本机 18792 时，应使用远程转发 -R 或等价的反向隧道；仅用 -L 把远端 18789 拉到本机，解决不了浏览器面。
token 与端口表不同步：Gateway 配置里的 relay token、隧道映射端口与扩展选项必须同一套；改一处忘另一处会出现 401 或连到空端口。
与无头 Docker 路径混谈：容器内 Chromium 要调 shm_size；本机 Relay 要调隧道与扩展挂载，故障树不应合并，见 无头清单。
把 Gateway 绑到 0.0.0.0 图省事：为修 Relay 而扩大暴露面，会把控制面一起暴露；应坚持本机绑定 + 隧道或私网，对齐 网络排障文。
把五条写成变更单上的「隧道必须项」与「禁止项」，比事后在群里问「谁改了端口」便宜得多。下一节用矩阵在无头容器与本机 Relay 之间做可签字选型，再进入可复制的验收步骤。
选型不要凭偏好，而要看浏览器在哪台机器、谁持有用户会话、以及合规边界。下表用于评审会一页纸决策；选定后只走对应 Runbook，避免两套参数同时改。
| 模式 | 适用场景 | 主要代价与风险 |
|---|---|---|
| Docker 无头 Chromium | 纯 VPS、无人值守批处理、不需登录你本机 SSO | shm/内存峰值高；站点指纹与真实用户浏览器可能不同 |
| 本机 Chrome + Relay | 需要本机 Cookie/SSO、人工旁观页面、交互式排障 | 必须维护 SSH 隧道与扩展挂载；远端 Gateway 不可直连公网浏览器 |
| 专用 24/7 云端 Mac + Relay | 团队共用、希望浏览器与控制面同地区 | 需独占节点与标准化隧道模板；运维成本上移但 SLA 可辩护 |
Relay 拓扑的稳定，本质是谁监听 18792、隧道把哪一侧的 localhost 映射给谁、token 是否同一套；其它优化都要让位。
2026 年官方文档与社区指南仍强调：安装后运行 openclaw onboard --install-daemon，用 openclaw gateway status 与 openclaw doctor 验收控制面；浏览器类能力则额外要求 Relay 健康与标签挂载。你若已选本机 Relay，请把「18792 可达 + tab attached」写进与 Gateway 同级的发布门禁。
下列顺序与 Gateway 安装排障清单 衔接：先证明控制面，再证明浏览器面。每步输出粘贴到工单。
验收 Gateway：在 VPS 上执行 openclaw gateway status，确认监听 127.0.0.1:18789（或你文档化的本机端口）；外网访问只经反代或 SSH，不直接裸露。
本机启动 Relay：安装 Chrome 扩展并打开中继；在本机执行 curl -sS http://127.0.0.1:18792/health，应返回健康 JSON（字段以你版本为准）。
挂载标签页：在要自动化的站点打开标签，用扩展执行 Attach；未 Attach 时 Skill 报 no tab is connected 是预期行为，不是 Gateway 坏了。
建立隧道：若 Gateway 在远端、浏览器在本机，典型为在本机执行 ssh -N -R 18793:127.0.0.1:18792 user@vps，并在 Gateway 侧把 relay URL 指向 127.0.0.1:18793（端口与变更单一致）；也可用 -L 把远端 Gateway 拉到本机调试，但勿与浏览器面混淆。
对齐 token：将 Gateway 配置中的 relay/gateway token 与扩展或环境变量注入保持一致；隧道后 401 时先查 token 是否仍走「仅本机 runtime 表」路径，必要时改用文档推荐的 gateway token 头。
端到端 Skill 试跑：运行最小浏览器 Skill（单页标题读取即可），同时开 openclaw logs --follow；失败则按下一节症状表二分，禁止同时改隧道与模型密钥。
curl -sS http://127.0.0.1:18792/health openclaw gateway status ssh -N -R 18793:127.0.0.1:18792 user@your-vps.example curl -sS http://127.0.0.1:18793/health
提示：若你最终改走容器内无头浏览器，请切换到 无头 Skill 清单，不要在本 Runbook 上叠 shm_size 参数。
用「现象 → 先查什么 → 动作」索引，方便值班。每次只改一格并记录前后 curl 与日志片段。
| 你看到的症状 | 优先核对 | 常见根因与动作 |
|---|---|---|
| 扩展 ON，Skill 报 no tab connected | 是否在目标 URL 打开标签并 Attach | 属操作遗漏；写进 Runbook 门禁，不是网络故障 |
| 隧道后 curl 18793/health 失败 | ssh -R 是否存活、远端是否监听 | 隧道进程退出或端口被占；用 ss -lntp 查占用 |
| Relay 401 / unauthorized | token 头、Gateway 与扩展配置 | 远程隧道未走 gateway token；对齐配置后重试，参考社区 #33807 类案例 |
| EADDRINUSE 仍报浏览器不可用 | 探测端口 vs 实际 Relay 端口 | 探测用了隧道端口但 Relay 在 18792；统一端口表 |
| Gateway CLI 超时 | 18789 可达性、SSH -L | 先读 网络排障文，勿先怀疑 Relay |
openclaw gateway status 为准）；与 Relay 18792 不可混记在同一行配置里。/health 再建隧道；隧道映射后应对映射端口再 curl 一次，形成两段证据。注意：勿在同一变更单里同时旋转 API Key、反代证书与隧道端口；三角变更无法二分回滚。
本机 Relay 适合交互式调试与依赖本机身份的场景；当任务要 24/7 无人值守、或团队不愿长期维护个人笔记本隧道时，应主动迁移拓扑。
| 信号 | 建议动作 | 说明 |
|---|---|---|
| 多人依赖同一开发者笔记本隧道 | 迁移到无头 Docker 或专用云端 Mac | 消除单点与离职风险 |
| 隧道每周因休眠断开 | 改用同区域 24/7 节点 + 标准化 systemd/ssh 配置 | 把隧道 uptime 纳入 SLO |
| 必须公网直达浏览器 | 禁止；改无头或合规远程桌面 | Relay 设计假设 loopback 信任边界 |
在「自建 VPS + 手工 SSH」路径上，Relay 方案短期灵活，但当 OpenClaw 要进入多人协作、可审计变更与稳定夜间批处理阶段，个人笔记本隧道往往无法签字 SLA。此时把 Gateway 与浏览器工作负载放到可预期规格的 24/7 云端 Mac，并用固定 Runbook 管理隧道或改无头 profile，通常比反复改端口更划算。对需要独占资源、地区稳定的小团队，VpsMesh 的 Mac Mini 云端租赁通常是更优解：便于与控制面同机或同区域部署 Relay/无头组合，并与 Mac Mesh 协作叙事对齐；价格见 价格页，路径见 帮助中心。
若你只是把远端 Gateway 控制面拉到本机调试，常用 -L 18789:127.0.0.1:18789。若 Gateway 在 VPS、浏览器在本机，需要让 VPS 上的 Agent 访问本机 18792，则在本机对 VPS 建 -R 把本机 Relay 映射到 VPS 的 loopback 端口，并与 Gateway relay URL 一致。更多控制面超时见 Compose 网络排障。
在目标站点打开标签并使用扩展 Attach；这是操作门禁而非服务故障。若已 Attach 仍失败，再查隧道 health 与 token，并对比 安装排障清单 中的日志分段采集顺序。
不推荐：会把浏览器控制面暴露到不可信网络。应坚持 loopback + SSH/私网。若必须无人值守批处理，请改 无头 Docker Skill 或专用节点。