OPENCLAW GATEWAY
WS_HANDSHAKE_
ED25519_STALL.
2026 年 4.x 周期里，一类「看起来像网络断了、其实是握手链在本地悄悄失败」的故障在社区议题中反复出现：WebSocket 已连上、Gateway 日志里能看到 connect.challenge，但 CLI 或 Control UI 永远等不到 connect.reply，命令行子命令于是无限挂起。根因往往在设备身份（Ed25519 PKCS#8）签名路径、Node 与 OpenSSL 组合边界、或被反代/WebSocket 升级规则吞掉的帧——而不是模型或渠道本身。本文面向自托管与远程 Mac 常驻 Gateway 的运维：先给症状—根因矩阵，再给出五步分层 Runbook（status→logs→设备自检→传输层→远程环境对齐），最后附三条可写进变更单的硬门限与案例复盘。可与站内《OpenClaw 无回复与 doctor 分层》《Gateway launchd/systemd 回滚》及《SSH 与 VNC 远程 Mac 选型》交叉阅读。
1. 痛点拆解：为什么「能 ping 通端口却永远卡住」？
1）传输成功 ≠ 会话成功：ws://127.0.0.1:18789 能建连只说明 TCP/TLS 与升级头过关；OpenClaw 在应用层还要完成设备挑战应答，失败时常无用户可见错误码。2）签名异常被静默吞掉：部分版本路径里，私钥 PEM 解析或 crypto.sign 抛错只在 debug 级别打印，表象就是「challenge 来了但没有 reply」。3）Node 小版本与 OpenSSL 行为漂移：尤其在 Windows Server 或容器里，Node 24 + OpenSSL 3 对 PKCS#8 Ed25519 的严格校验与 macOS 开发机不一致，导致「同一套 identity 在笔记本可用、在 VPS 挂死」。4）远程常驻的环境真源分裂：launchd plist 里缺少与交互 shell 相同的 PATH / HOME，CLI 通过 SSH 调用时读到另一份 openclaw.json，握手走到一半发现 token 与 bind 不一致，表现为间歇挂起而非稳定 401。
2. 症状—根因矩阵（先对照再开 trace）
| 用户可见现象 | 优先怀疑层 | 首选证据 |
|---|---|---|
| 任意需 Gateway 的子命令挂死，CPU 近 0 | 应用层握手 / 设备签名 | Gateway 日志出现 challenge 无 reply；CLI --log-level trace |
| 仅远程节点挂、本机正常 | Node/openssl 或 identity 路径 | 对比 node -p process.versions 与 device.json 权限 |
| 经 Nginx/Caddy 反代后必现 | WebSocket 升级 / 缓冲 / 超时 | 反代 access 与 upstream 499/504、Upgrade 头 |
| 升级后偶发、重启 Gateway 暂时好 | token 漂移 / 多 CLI 并行握手 | openclaw config get gateway.auth 与多终端时间线 |
3. 五步分层 Runbook（生产可抄）
Step 01：确认 Gateway 真在跑且 RPC 探针健康
执行 openclaw gateway status，核对 Runtime: running 与 RPC 探针；若显示 running 但 CLI 仍挂，优先怀疑「CLI 指向的 URL 不是你以为的那个」（例如 gateway.mode=remote 残留）。
Step 02：开 trace，锁定卡在 sendConnect 还是更早
对挂起的子命令加 --log-level trace（或环境变量等价开关），对照 Gateway 侧同一时间线：若 challenge 已下发而客户端无 outbound reply，直接进入 Step 03。
Step 03：设备身份 Ed25519 最小自检（勿在生产直接改私钥）
在副本环境用 Node REPL 对 ~/.openclaw/identity/device.json 的 privateKeyPem 调用 createPrivateKey + sign 对固定 payload 试签；若抛错，优先核对 PEM 是否 PKCS#8、是否被错误换行/转义，再评估 Node 降级或补丁版本。绝不在未备份时覆盖私钥。
Step 04：传输与反代层清单
若直连 loopback 正常、经反代失败：检查 Connection: Upgrade、Sec-WebSocket-Key、上游读超时、以及是否把 /gateway 路径错配到 HTTP 轮询。对 Tailscale/SSH 隧道场景，确认隧道端口与 Gateway bind 一致。
Step 05：远程 Mac launchd 对齐
核对 plist 的 EnvironmentVariables 是否包含与 shell 相同的 OPENCLAW_*；launchctl kickstart 后再次跑 openclaw doctor 与一次 trace 握手。与《SSH 与 VNC 远程 Mac》中的延迟与断连策略一起写进值班手册，避免「人能 SSH、服务却读到另一个 HOME」。若你更关心会话与 OAuth 而非握手，可回看《sessions.json 与 OAuth Runbook》。
4. 决策矩阵：先修客户端、先修 Gateway 还是先动反代
| 证据 | 首选动作 | 次选 | 避免 |
|---|---|---|---|
| REPL 签名校验失败 | 修 PEM / 换兼容 Node 小版本 | 重新生成 identity（需全量重配对） | 反复重启 Gateway 赌运气 |
| 仅反代路径失败 | 修 WebSocket 与超时 | 临时改为 SSH 隧道直连 loopback | 把 Gateway bind 到 0.0.0.0 却不加 auth |
| 多终端并行时偶发 | 串行化 CLI 操作、关 stray watch 进程 | 轮换 gateway token 并写回单一真源 | 同时在笔记本与 CI 跑 attach 脚本抢握手 |
三条可引用门限：① 若 trace 显示 challenge 后 8 秒内无任何 outbound reply 尝试，必须视为 P0 阻断并在变更单里挂「设备身份或客户端版本」标签。② 若同一 identity 在 macOS arm64 Node 上可签、在目标 OS 上不可签，禁止直接切换 bind 到公网暴露作为绕过手段，应先修运行时。③ 若反代层 7 天内出现两次以上 1011/1006 与握手同时发生，必须把反代配置纳入与 Gateway 同级的基础设施评审，而不是丢给应用团队单独消化。
5. FAQ：最容易误判的三件事
Q：为什么 openclaw channels status --probe 还能部分成功，但某些子命令仍挂？A：probe 可能走短路径缓存或不同插件初始化顺序；握手挂起往往发生在需要长会话或设备挑战的 RPC 上，不能仅凭单一命令绿灯推断全局健康。
Q：能否用临时 HMAC 或关闭设备校验「先跑起来」？A：生产上不建议；社区讨论里 Gateway 对挑战应答有明确协议预期，绕过会让后续审计与多机配对更难收尾，应优先修运行时与 PEM。
Q：远程 Mac 上 docker exec 进容器跑 CLI 也挂，宿主机却正常？A：检查容器内 HOME 与挂载的 ~/.openclaw 是否一致、时区与系统时钟是否同步；再对照宿主机 trace，常见是读到空 identity 或只读层导致签名静默失败。
把以上 FAQ 与五步 Runbook 一并贴进内部 Wiki，可减少「先重启三遍再问人」的无效工单；若仍卡在 challenge/reply，请携带两端 Node 版本、Gateway 与 CLI 的 trace 各 50 行、以及反代配置片段再向社区或厂商渠道提问，可显著缩短往返轮次。
补充一条实践纪律：任何涉及 identity 的变更（重装 CLI、迁移 HOME、复制 plist）都必须先在 staging 远程 Mac 上跑通同样的五步，再推进生产；staging 与生产的唯一差异应写在表格里（端口、bind、token 来源），避免「staging 手顺在生产失效」的二次事故。
6. 深度案例：Windows Gateway + macOS 笔记本 CLI 的「周五挂死」
「我们一度以为是防火墙，其实是 SCHEDULED_TASK 下的 Node 24 对 PKCS#8 Ed25519 PEM 解析与开发机不一致；把 CLI 固定到与 Gateway 相同的 LTS 小版本后，connect.reply 恢复，P95 命令耗时从「无限」回到 1.4s。」
某运维团队在 Windows Server 上以 SYSTEM 账户跑 Gateway，工程师在 Mac 笔记本上用全局 npm 安装的 CLI 调试。现象是：部分子命令永远卡住，Gateway 日志里 challenge 正常；网络抓包显示 WebSocket 帧正常往返，但应用层无 reply。把 CLI 与 Gateway 的 Node 小版本对齐后，问题消失；复盘发现任务计划程序环境下的 OpenSSL 与本地 zsh 环境并不一致，REPL 试签在服务器上可稳定复现抛错。团队把「Node 小版本 + REPL 试签」写进发布门禁，并在远程 Mac 备援节点上用 launchd 固定同一 Node 发行版，避免「主节点升级、备援仍是旧运行时」的分裂。该案例说明：握手级故障不应先动模型或渠道配置，而应优先完成身份链路与运行时的可重复自检。
7. 行业洞察：Agent 控制面与「可观测握手」将成为默认 SLA
2026 年随着 OpenClaw 一类控制面组件进入半生产部署，「RPC 探针 ok」将不足以说服安全与基础设施团队；必须把 challenge/reply 时延分布、签名失败计数、反代 101× 与命令挂起关联进同一套仪表盘。纯 Windows 或纯 Linux VPS 方案适合短期验证，但在图形相关工具链、Metal 调试与 Apple 生态脚本上仍常回到 Mac；当 Gateway 需要与本地创意工具链并存、又要求 7×24 时，把稳定常驻放在远程 Mac 机房节点、笔记本只做 CLI 与排障，是更常见的折中。若你希望减少环境漂移、统一 Node/identity 真源，又不自建机房，可考虑租赁 MACGPU 的远程 Mac 作为 Gateway 常驻与握手对齐的基线环境。
收尾对比：在异构 OS 混跑时，握手挂起往往来自「运行时差异」而非「OpenClaw 业务逻辑坏了」；先在 Mac 或与你生产尽量一致的镜像上复现，再决定是修 Node、修反代还是重发 identity，能显著减少无效重启。若你需要可预测的统一内存与图形/自动化工具链共存环境来承载 Gateway 与排障基准机，MACGPU 远程 Mac 租赁可以把握手与常驻从个人笔记本里解耦出去，让团队按小时弹性扩容而不牺牲 Apple Silicon 上的调试效率。