2026 OPENCLAW
UPDATE_
WROTE_
WRONG_
NODE.

升级到 OpenClaw v2026.5.20 前后，一类极易被误判为「假升级」或「频道鉴权坏了」的故障，其实是：LaunchAgent 里固化的 Node 路径与当前 shell 里 which node 不一致，openclaw update 在 follow-up 步骤里用 PATH 上的「另一个 Node」重写了服务单元，下次 gateway restart 直接起不来。5.20 官方修复（PR #84043）要求全程使用托管 Gateway 的 service Node，并在 gateway status --json 中暴露运行版本以识别 CLI/Gateway 协议 skew。本文给出症状矩阵—决策表—六步 Runbook—三道门禁—案例—FAQ，并与站内《假升级与 gateway status》《LaunchAgent token 过期》《invalid config 与 doctor》分工，帮助你在远程 Apple Silicon Gateway上完成 7×24 对照验收与回滚。

1. 痛点拆解：不是版本号不一致，而是 Node 二进制漂移

1）多 Node 并存极常见：同一台 Mac 上 Homebrew /opt/homebrew/opt/node/bin/node、nvm 默认 22.x、fnm 全局 20.x 同时存在；openclaw gateway install 时会把当时的 node 绝对路径写进 ai.openclaw.gateway plist。2）PATH 切换触发漂移：你在终端 nvm use 25 后执行 openclaw update，旧版逻辑会用新 PATH 的 node 跑 post-install、doctor、重启——若 package root 未变，服务单元却被悄悄换成另一套全局 npm 前缀下的 openclaw。3）与「假升级」分工：假升级是 CLI 已 5.20、运行中 Gateway 仍 5.12；本文是二进制与 engines.node 不匹配导致启动即崩溃或 WS 握手失败。4）协议 skew：5.20 保留「CLI 比 Gateway 新一个小版本」时的 restart health check；若 Node 漂移导致 Gateway 起不来，你会看到 unauthorized 或 RPC 超时，而非单纯的版本字符串不一致。5）遗留 updater LaunchAgent：Issue #82167 描述 ai.openclaw.update.* 反复 relaunch、SIGTERM 网关；5.20 起 update 会 best-effort disable 遗留 job——升级 Runbook 必须包含 launchctl 清单核对。

2. 决策矩阵：先对齐 Node，还是先回滚包？

现场信号	首选动作	禁止
openclaw --version 与 plist 内 node 路径指向不同 major	冻结 PATH → 用 service Node 重跑 update 或 gateway install --force	禁止在未备份 plist 前手改 ProgramArguments
gateway status --json 无 runningVersion	先 gateway restart --wait，再查 launchd 退出码	禁止删除整个 ~/.openclaw
升级后仅 Telegram 偶发断连	先排除 Node 漂移，再查频道层	禁止与 5.2 HTTP 超时混修（见专稿）
笔记本验证 OK、远程 Mac 全挂	对照节点比对 plist node 与 npm root -g	禁止把本机 nvm 路径复制到远程
需生产变更审计	远程对照机先跑六步 + 30 分钟探针	禁止周五晚高峰无回滚窗口升级

3. 六步落地 Runbook

Step 1 冻结「三元组」证据

记录：openclaw --version、which node 与 node -v、LaunchAgent plist 中 ProgramArguments 前两段（node 路径 + openclaw 入口）。另存 openclaw gateway status --json 输出中的 runningVersion（5.20+）。

Step 2 解析 engines.node 门槛

在全局 openclaw 包目录查看 package.json 的 engines.node（或 release 注记）。若 service Node 的 major 低于要求，先升级 service 所用 Node，再动 openclaw 包——避免 doctor 通过但 Gateway 启动失败。

Step 3 对齐托管 Gateway 的 Node（5.20 推荐路径）

升级到 2026.5.20 后执行 openclaw update：官方会优先使用 LaunchAgent 内 baked node 跑 follow-up。若你已漂移，执行 openclaw gateway install --force 用当前 intended 的 node 重新固化路径，并确认 npm root -g 与 plist 一致。

Step 4 清理遗留 updater LaunchAgent

launchctl list | grep openclaw：若存在 ai.openclaw.update.* 且反复重启，在 5.20+ 上由 update 自动 disable；旧版可手动 launchctl bootout gui/$UID/ai.openclaw.update.*（先确认非进行中任务）。对照 Issue #82167 避免「升级脚本已成功但网关每 3 分钟 SIGTERM」。

Step 5 Gateway 有序重启与 JSON 探针

openclaw gateway restart --force --wait 后，连续三次 openclaw gateway status --json，要求 runningVersion 与目标一致、RPC 在阈值内成功。远程 Mac 用 launchctl kick -k gui/$UID/ai.openclaw.gateway 后重复。

Step 6 远程 7×24 对照与回滚窗口

在对照节点保持未切换 nvm 的干净 PATH，重复 Step 1–5。若生产仍失败，钉版本并保留 plist/npm 前缀 diff；连续 30 分钟 channels.probe 全绿才 closure。

4. 三道自检门禁

第一道Node 门禁：plist 内 node 路径存在且 node -v 满足 engines.node。第二道版本门禁：gateway status --json 的 runningVersion 与 openclaw --version 在可接受 skew 内（5.20 健康检查覆盖一小版差异）。第三道渠道门禁：openclaw channels status --probe 无红，且 30 分钟内无「重启后立刻退出」。

5. 深度案例：「update 成功，次晨 Gateway 全渠道离线」

团队先按《假升级》专稿查版本字符串，发现 CLI 与 status 都是 5.20，误判为频道 token。直到对比 plist 与 which node 才定位Node 漂移。在 MACGPU 对照机上用单一 Homebrew Node 重装 Gateway 后，生产 Studio 仅替换 plist 前两段并 gateway install --force，30 分钟内恢复。复盘写入变更单：禁止从带 nvm 的交互 shell 对远程 launchd 服务执行 update；升级窗口统一用 service 账户或 env -i 最小 PATH。

6. 行业洞察：Agent 网关「运行时钉扎」与 Mac 托管实践

2026 年 Node 生态分裂（nvm/fnm/Volta/Homebrew）让「全局 CLI」与「daemon 固化运行时」成为两套真相。OpenClaw 5.20 把managed service Node写进更新链，标志着 Agent 运维从「能装就行」进入可钉扎、可 diff、可回滚阶段。甲方开始要求升级工单附带：plist node 路径、engines.node 校验截图、gateway status JSON——而非仅版本号截图。

在 Windows/Linux 上同样存在多 Node 并存，但 macOS launchd 的绝对路径语义更「硬」——漂移一次就全站离线。Apple Silicon 远程 Mac 因独占内存、Metal 生态与 7×24 图形/Agent 混合负载，常被用作黄金对照环境：PATH 干净、磁盘可快照、日志可工单回放。若你希望把 5.20 升级、Node 对齐与回滚放在与本机 nvm 隔离的节点上完成，可租赁 MACGPU 远程 Mac：先在对照机跑通六步与 30 分钟探针，再动生产。

7. 可引用数字门槛

① plist node 与 which node 路径不一致：禁止宣告升级成功。② engines.node 要求 Node ≥22（以你安装包为准）：service Node 不满足则先换运行时。③ 升级后 30 分钟 内 launchd 退出码非 0 超过 3 次：默认回滚并保留 plist diff。④ gateway status --json 三次拿不到 runningVersion：Unhealthy。⑤ 远程与本地 npm 全局前缀不同：禁止复制 plist 片段跨机粘贴。

8. FAQ

问：和假升级有何不同？答：假升级看版本字符串；本文看Node 二进制与 plist 路径。问：必须升到 5.20 吗？答：5.20 起官方修复漂移；更低版本请手动 gateway install --force 对齐。问：Docker 部署呢？答：容器内通常单一 Node；注意挂载卷与镜像 tag 即可。问：能否手改 plist？答：可以但须备份；推荐 gateway install --force。问：MACGPU 节点做什么？答：对照验收、PATH 隔离与回滚窗口，不替代变更审批。