2026年 OpenClaw 更新后 CLI 与 Gateway 版本不一致：npm 全局与 ~/.openclaw/lib 双栈同步、LaunchAgent 重启与 openclaw doctor 修复在远程 Mac SSH 上的可复现清单 + FAQ
大版本或通道更新后，常见现象是：openclaw --version 已变新，但 Gateway 仍报旧协议或健康检查里仍是旧构建。根因往往是两条安装真源（npm 全局 CLI 与 ~/.openclaw/lib 下的运行时/网关依赖）未同步，再加上 LaunchAgent 未冷重启导致进程仍吃旧代码。本文给 SSH 独占远程 Mac 上的对照顺序与 FAQ。
1. 先把「不一致」说清楚：是显示问题还是真双栈
版本字符串不一致未必都是 bug：有时是CLI 与 Gateway 分包版本号策略不同（例如一个带构建元数据、一个只显示 semver）。需要警惕的是：协议/路由/探针路径与文档新版本冲突，或 doctor 明确提示「运行时路径与 CLI 不匹配」。此时按「双栈真源」排查，而不是反复重装 npm 却不动 ~/.openclaw。若你还同时跑了 gateway 与 mac 助手等多份 LaunchAgent，请先核对各 plist 的 Label 与 ProgramArguments，避免指向旧入口脚本。
2. 双栈真源：npm 全局 CLI 与 ~/.openclaw/lib
典型布局是：npm 全局提供 openclaw 可执行文件，而 Gateway 进程实际加载的依赖可能落在用户目录下的 OpenClaw 管理目录（常见为 ~/.openclaw/lib 及其 node_modules）。只执行 npm update -g 而不触发 OpenClaw 侧同步，就会出现「CLI 新、网关旧」或相反。
- CLI 侧：
which openclaw、openclaw --version、npm ls -g --depth=0（核对包名与版本）。 - 用户栈侧：
ls -la ~/.openclaw、ls ~/.openclaw/lib（若文档版本将依赖固定在此，则此处为真源之一）。 - 进程侧：对正在跑的 Gateway PID 用同一用户执行环境探查（见下节清单），确认
NODE_PATH/ 启动脚本是否仍指向旧目录。
与「升级大版本后插件/SDK/环境变量」一并核对时，建议按官方升级说明逐项执行 doctor 与依赖同步，避免只改 CLI 或只改用户栈的一边。
3. 远程 Mac SSH 可复现清单（建议照抄到 Runbook）
以下假设你以与 LaunchAgent 相同用户登录 SSH（与 plist 中 UserName 一致）。若不一致，先回到用户对齐，否则路径与权限全假阴性。
| 步骤 | 命令 / 动作 | 期望结论 |
|---|---|---|
| A. 固定身份 | whoami、id、与 LaunchAgent 用户比对 |
与 plist 执行用户一致 |
| B. CLI 真源 | which openclaw、openclaw --version |
路径在预期前缀（如全局 npm bin） |
| C. 用户栈 | 查看 ~/.openclaw/lib 与相关 package.json / 锁文件是否存在、时间戳是否在更新之后 |
与升级时间线一致；无「半截」目录 |
| D. 自愈 | openclaw doctor，必要时 openclaw doctor --fix（以当前版本帮助为准） |
无「路径不一致」类阻断；按提示补权限或重装用户栈 |
| E. 冷重启 | launchctl kickstart -k gui/$(id -u)/<你的 Gateway Label> 或 unload/load 对应 plist |
进程 PID 变化；健康检查与版本输出一致 |
Dashboard 或本机监听异常时，请把「版本不一致」与「端口/转发/仅监听 127.0.0.1」分开分诊：前者对照本文双栈与冷重启，后者用 lsof/curl 与 SSH 本地转发逐条验证。
4. LaunchAgent：为什么要 kickstart -k
仅改磁盘上的包不等于改内存里的 Node 进程。kickstart -k 意图是先杀再起，避免 launchd 仍保留旧解释器上下文。若你使用自定义 Label，请以 launchctl print gui/$(id -u) 或团队文档中的 plist 文件名为准替换占位符。
5. openclaw doctor 在 SSH 上的注意点
在交互式 SSH 会话里跑 doctor 与在 launchd 无人值守环境下跑，PATH 与 shell profile 可能不同。建议：
- 在与 LaunchAgent 相同环境下验证（必要时用包装脚本在 plist 里显式
export PATH=...）。 - doctor 报修复项后，再执行一次「C 步用户栈核对」，确认
~/.openclaw/lib与 CLI 指向同一发布线。 - 若团队通过 SSH 隧道暴露网关，可结合 OpenClaw 安全部署与 SSH 隧道 的运维习惯，避免「修完 CLI、隧道仍指向旧本地端口」的二次漂移；在独占节点上搭整套宿主环境时也可参考 在独享 Mac mini 上部署 MCP 宿主环境 的路径与权限纪律。
6. FAQ
Q1：openclaw --version 与 Dashboard 里显示的 Gateway 版本差一位小数，算事故吗？
不一定。以协议兼容与 doctor 是否报错为准；若功能与探针均正常，可记录为展示策略差异。
Q2：npm 全局已经最新，为什么 ~/.openclaw/lib 还是旧的？
可能升级流程只更新了全局 CLI，未执行 OpenClaw 自带的同步/安装步骤；或上次失败留下半目录。以官方推荐的「安装/更新」命令与 doctor 输出为准，必要时在备份配置后清理再拉取（团队须有变更窗口）。
Q3：冷重启后仍不一致，下一步？
查是否多套 plist 或多个用户各跑一套 Gateway；用监听端口与进程命令行核对真实入口脚本。仍怀疑环境分裂时，优先核对 LaunchAgent 的 stdout/stderr 与 Gateway 健康探针是否指向同一绑定地址与路径。
在 Mac mini 上，双栈升级更可控
版本漂移本质是「状态分散在多处」：全局 npm、用户目录与 launchd 进程各持一份真相。Apple Silicon Mac mini 作为独占远程节点时，磁盘与家目录路径稳定、无桌面用户随意插拔工具链，配合 macOS 与 launchd 的原生服务模型，Runbook 更容易写成可重复执行的步骤；待机功耗低、长期在线成本也更适合跑 Gateway 这类常驻组件。安全面上，Gatekeeper、SIP 与 FileVault 与 SSH 跳板组合使用时，也比在通用办公机上混装多份 Node 更易于审计。
如果你希望把 OpenClaw 的 CLI、用户栈与 LaunchAgent 固定在可预期、可回放的环境里，一台专属远程 Mac mini M4 仍是 2026 年性价比突出的选择之一。现在即可从首页了解套餐，把本篇清单并入你的变更与回滚手册。