升级 OpenClaw 后你遇到的是哪一类「坏」？是 gateway 起不来、RPC 探针失败，还是 CLI 说已升级、用户级 systemd 服务仍指向旧路径？本文给生产读者：先用七条隐性假设拆穿 split brain（新旧二进制分叉），再用一张症状对照表区分「配置戳版本」与「Token／远程 URL」类问题，然后给出六步安全恢复 Runbook（PATH → gateway install --force → gateway restart → doctor），并说明破坏性环境变量闸门何时才值得打开。文内链到 cron 与升级回归、远程模式、生产观测 分工阅读。
官方 troubleshooting 已说明：当较新版本的 OpenClaw 写入 openclaw.json 并更新 meta.lastTouchedVersion 一类戳记后，若仍在路径上解析到旧 openclaw 二进制，读操作可能仍可进行，但一旦涉及网关服务安装／重启／卸载等破坏性变更，CLI 会拒绝以避免把半新半旧的元数据写入磁盘——这就是常被口语称为 split brain 的生产场景。
把「npm 已成功」等价于「服务已切换到新二进制」：npm install -g 只更新全局前缀下的可执行文件；launchd/systemd --user 单元里若仍指向旧绝对路径，重启后照旧。
在登录 shell 与 service 环境里混用 PATH：交互式会话找到 which openclaw 正确，并不等于 daemon 环境里一致。
忽略多套安装源并存：Homebrew、官方安装脚本与 npm 全局可能同时存在多份二进制；谁先谁后取决于 PATH 前缀顺序。
升级后跳过 gateway install --force：官方建议在 service 与实际二进制漂移时重装服务封装；仅靠「手动启动一次 gateway」会留下下一轮重启再次分叉的雷。
把 「doctor 报错」一律当配置文件写坏：有时是二进制与配置守卫不匹配，需要先对齐版本再谈逐项改键。
在远程模式与本地模式之间来回试错却不截屏配置：应与 远程模式篇 相同纪律：先 openclaw config get gateway.mode 再决定探针打向哪台主机。
升级后只看 channels 不看调度面：定时任务与 cron 与 Gateway 同一进程族，升级回归应读 cron 篇 的检查表。
这些问题的共同根因，是把「配置文件能读」误当成「执行面一致」。正确心智是：配置戳只代表谁最后写了文件，而真正跑服务的二进制身份需要单独验真。
下表用于把值班记录从「感觉升级坏了」推进到「可签字的分支」：
| 表征 | 更像是 split brain | 更像鉴权 / 会话问题 | 更像远程 URL / 拓扑问题 |
|---|---|---|---|
| doctor 关键词 | 提示新旧二进制分叉、阻止 gateway 破坏性动作 | Token / device 相关错误码，与二进制版本无关 | RPC 探针失败且本地 gateway status --deep 指向意外主机 |
| gateway status | Runtime 行为与 CLI --version 明显不一致 | Runtime 正常但仍 unauthorized | 本机停在 stopped，远端实际在跑 |
| 首选动作 | 对齐 PATH → gateway install --force → restart | 轮换或对齐 token／设备握手 | 核对 gateway.remote.url 与环境变量是否与 远程模式篇一致 |
升级夜的黄金句：(A) 哪个二进制在跑？(B) 哪个配置戳被谁写过？两件事一致，再讨论频道与 cron。
若你与 Tailscale / 私有隧道 结合部署，别把「隧道通」与「RPC 通」混为一谈；仍建议对照 Tailscale 私网暴露 篇做双端验收。
以下为顺序敏感流程；每一步若发现新旧仍不一致，应先回到本节前一步，而不要并行改配置文件与二进制。
冻结现场：openclaw --version、服务单元里显式二进制路径（若可见）、以及 doctor 输出截屏存档。
修正 PATH 与别名：确保非交互会话下 which openclaw 指向拟定升级版本；移除会遮蔽路径的 shell 别名。
对齐安装源：选定单一维护通道（文档推荐的 npm／安装脚本等），避免「上一版 brew、这一版 npm」的长期混装。
重装服务封装：在确认 PATH 后对同一用户执行 openclaw gateway install --force，刷新 launchd/systemd 元数据。
冷启动 Gateway：openclaw gateway restart，随后再跑 gateway status 与 RPC 探针。
回归清单：openclaw doctor → channels status --probe → 对照 cron list 是否仍注册。
openclaw --version command -v openclaw openclaw gateway status openclaw doctor openclaw gateway install --force openclaw gateway restart openclaw channels status --probe
提示：若日志出现端口占用、内存尖峰或 compose 启动顺序问题，应并列阅读 Gateway not ready 实操 与 closed(1000) RPC，避免把资源类故障误判为 split brain。
官方 troubleshooting 将「较新配置 + 旧二进制」视为危险组合：旧进程若仍获得写网关服务元数据的权限，可能把磁盘状态磨成不可回放混合体。为保护用户，新版本 OpenClaw 可能对 gateway 相关破坏性操作加硬闸——仅当你明确需要用旧二进制执行单次紧急恢复时才应设置相应的 OPENCLAW_* 环境变量（名称与语义以当期官方文档为准）。
注意：此类变量不是「跳过一切检查」的神奇开关；它解决的是你已理解风险并接受可能损坏服务封装的窄场景。默认值应保持未设置，除非你按文档写有回滚条目。
工程上更可维护的做法通常是：修好 PATH → 重装服务 → 用新二进制跑完整升级；只有在供应商阻断旧包下载等特殊情况下，才把降级路径写进单独的变更单并接受审计副本。
以下是平台侧内部对齐可用的量化锚点：
openclaw --version 输出截图，二者应在恢复后完全一致。doctor 清洁结果。纯笔记本或共享开发机上的 Gateway 常受睡眠、系统更新与多用户冲突影响；把 OpenClaw 落在可 7×24 常驻、SSH 可达、磁盘与网络口径写进合同的独占远程 Mac 上，通常比反复「升级后又分叉」更值得长期投入。NodeMini 云端 Mac Mini 租赁可提供固定 SSH 与独占算力，适合承载 AI 网关与企业内部自动化；规格与接入可参考 租赁价格说明与 帮助中心。更多 OpenClaw 实操可在博客筛选 OpenClaw 专栏，按「观测 → cron → 远程模式 → 本文升级分叉」递进阅读。
可把它当成「最后一次由哪一版 OpenClaw 写完配置文件」的版本戳；当你在 PATH 上仍解析到更旧二进制，就会出现「守卫拒绝继续写 service」一类的保护性行为。修好 PATH 并按 Runbook 重装服务后再看 doctor，通常先于逐行改 JSON。
在 split brain 未排除前，cron 列表可能「看起来正常」但执行面拒绝动作；应先完成本文第三节，再按 cron 手册做周期回归。更多文章见 OpenClaw 筛选。