openclaw update · 备份钉扎 · doctor · 回滚
已上线 OpenClaw 的开发者与小团队在跟进版本时，常见痛苦不是「不会跑 openclaw update」，而是升级后 Gateway 起不来、端口仍被旧进程占用、PATH 指向旧二进制、配置迁移与工具配置被静默改写。本文先拆五条升级风险，再给官方 update 路径与 npm 全局、源码安装的对照表、六步可复现 Runbook（含备份与通道策略）、升级后 doctor 与健康检查顺序，以及端口冲突与双安装证据表；并与多平台安装与守护进程、安装与 doctor 排障、运行期排障互链，便于把升级、观测与回滚一次对齐。
官方文档推荐 openclaw update 并在升级后跑 openclaw doctor，但生产环境还会叠加守护进程未随包管理器切换、旧 Gateway 未释放监听、以及多份 CLI 并存。若你已在阅读生产加固清单，会知道通道白名单与监听面收敛和升级顺序强相关；跳过停止 Gateway 直接换包，常见症状是 18789 端口仍被旧进程占用。
进程与包版本脱节：全局 npm 已升到新版本，但 launchd 或 systemd 仍拉起旧工作目录里构建的二进制，表现为 openclaw --version 与 gateway status 报告不一致。
配置迁移与静默改写：大版本可能调整 openclaw.json 字段语义，doctor 会尝试迁移，但若合并策略与团队 GitOps 流程未对齐，会出现「文件在磁盘上变了但评审记录里没有」。
自动更新通道与变更窗口冲突：稳定通道延迟与抖动设计是为避免全员同时爆炸，但若与业务发布窗口未对齐，会在周五晚触发计划外重启；与通道探针组合时更要先确认 Gateway 真重启成功。
回滚证据不足：没有备份或钉版本记录时，只能「再装一遍最新」而不是回到已知良好状态；与常驻云端部署联用时，节点上往往还有定时任务与外部 webhook，回滚顺序错了会放大停机。
观测字段缺失：只保存「升级成功」截图而不保存 gateway status --deep 与监听地址，事后无法证明当时绑定面是否符合安全基线。
把以上五条写成发布前勾选清单，再进入下一节对比安装路径，才能把「能更新」升级到「可审计、可回滚的更新」。个人笔记本上的休眠与系统更新窗口也会让守护进程状态短暂不一致；需要合同化 SLA 的云端 Mac 节点才能把升级窗口与可用性条款写进验收范围。
三条路径没有绝对优劣，只有与团队规模、是否要钉提交审计、以及是否允许自动重启 Gateway是否匹配。官方 update 子命令适合大多数团队；全局包管理器路径适合 CI 镜像；源码适合要贡献补丁或锁 dev 通道的工程组。
| 维度 | openclaw update | npm 全局 / brew | git 源码构建 |
|---|---|---|---|
| 上手成本 | 低；一条命令串联拉取、doctor、重启提示 | 中；需自己串联 doctor 与 gateway 重启 | 高；需 pnpm 构建与路径管理 |
| 版本可追溯 | 中；依赖发布元数据 | 强；锁 package 版本号 | 强；可钉 commit SHA |
| 回滚路径 | 中；配合钉版本与备份 | 强；npm i -g openclaw@x | 强；git checkout 后重建 |
| 自动化友好 | 强；适合 runbook | 强；适合镜像层 | 弱；构建耗时与缓存策略复杂 |
| 与守护进程 | 需确认 stop 再 start 顺序 | 同左 | 最易出现双路径并存 |
可持续升级的关键，是「失败能否用版本号与备份路径解释」，而不是「偶尔能起 gateway」。
若你已在实践多平台 install-daemon，把本节选型结论写进运维手册，可避免「文档写 brew、机器上却是 npm、定时任务又指向第三条路径」的三体问题。
下面六步刻意可在 on-call 手册里逐条打勾：无论你用何种安装方式，只要顺序一致，新同事可以在一小时内完成一次演练。与运行期三段分流联用时，请在升级后保留一份 gateway status 输出片段，便于与通道层、模型层问题区分。
冻结变更窗口：在变更单里写明目标版本号与允许中断的分钟数；禁止与大规模模型密钥轮换同一晚执行。
备份配置与身份路径：使用官方备份能力或至少打包 ~/.openclaw 中与配置、身份相关的目录；校验备份校验和。
优雅停止 Gateway：先 openclaw gateway stop，确认监听释放，再执行更新命令；避免半升级态占用端口。
执行更新并记录通道：若使用 openclaw update，保存命令输出中的版本与通道信息到工单索引字段。
运行 doctor 与 health：按顺序执行，收集迁移提示与告警；有非预期字段变更时暂停自动重启并人工 diff。
探针通道与最小消息：在允许的环境发一条探针消息或调用 channels status，确认回调路径仍可达。
openclaw gateway stop openclaw update openclaw doctor openclaw gateway start openclaw health openclaw gateway status --deep
提示：若 update 内建重启与手动脚本并发，可能短暂出现双监听；升级脚本应序列化「停—装—起」而非并行。
社区常见问题包含「升级后端口仍被占用」与「CLI 显示新版本但进程仍是旧构建」。排障时先收敛到单一真相源：监听地址、进程二进制路径、包安装路径，再才怀疑配置。与安装与 doctor 清单交叉阅读时，把下列表格当作附录粘贴进工单。
端口占用：证据为 lsof -i :18789 或平台等价命令显示旧 PID；动作为先 gateway stop，失败再按手册安全杀进程并复核无残留。
双安装路径：证据为 which openclaw 与 npm root -g 指向不同前缀；动作为统一 PATH 并移除冗余全局包或固定别名。
守护单元未刷新：证据为 plist 或 unit 仍引用旧 WorkingDirectory；动作为重装 daemon 或执行文档中的 force 安装步骤后再 kickstart。
配置校验失败：证据为 doctor 报字段迁移冲突；动作为从备份恢复后分步升级或手工合并 JSON 并二次 doctor。
健康检查假绿：证据为 health 通过但通道无回调；动作为按运行期排障文做三段分流，不提前结案。
回滚后仍异常：证据为环境变量或 shell 启动脚本仍注入旧 NODE_PATH；动作为清理登录会话与 CI 镜像层缓存。
注意：在共享节点上「帮同事试一下」临时 export 的路径若写进 profile，会把个人试错变成全局事故；共享池场景请用独立 Unix 用户或容器边界。
下列三条来自大量小团队落地 OpenClaw 的经验区间，用于立项前核对而非厂商承诺；你应用真实工单样本替换它们。
| 团队规模 | 变更频率 | 风险承受 | 更稳的第一选择 |
|---|---|---|---|
| 个人 | 随意 | 高 | 官方 update + 手动停起；保留备份 zip |
| 小团队 | 每周 | 中 | 钉 npm 版本 + 变更单 + doctor 输出归档 |
| 平台化 | 每日 | 低 | 镜像层构建 + 金丝雀节点 + 自动化探针 |
| 外包协作 | 不规则 | 中 | 只读运行手册 + 独立节点；禁止共享 HOME |
个人设备上的休眠、磁盘空间与系统更新窗口会持续打断守护进程；即便升级流程正确，本地环境仍难满足「可验收的升级 SLA」。相较之下，可合同化的云端 Mac Mini 节点才能把进程常驻、网络入口与维护窗口写进条款。
常见误区：把「health 通过」当成「通道与模型侧也健康」；健康检查只覆盖网关子集，完整验收仍需按运行期排障顺序走一遍。
若团队需要可回滚的 OpenClaw 升级与可观测的 Gateway 生命周期，又希望节点始终在线、避免笔记本休眠导致 Agent 中断，对需要生产级自动化与 iOS 相关构建环境 的场景，VpsMesh 的 Mac Mini 云端租赁通常是更优解：按周期计费、区域可选、专用节点可审计，让升级讨论建立在真实可用性之上。