2026-04-16 无头租赁云 Mac 上的 OpenClaw 网关升级与回滚
在只讲 SSH 的租赁 Apple Silicon Mac 上交付 OpenClaw，升级就是纯运维：没有 Finder 点选路径，也没有「重启一下应用就好」。这份 2026-04-16 手册覆盖入口冻结、先停后 npm 顺序、对 ~/.openclaw 的校验和备份、版本固定（不要盲用 @latest）、用 openclaw doctor 验证、全局安装后偶发的二次重启网关，以及在构建失控时 3 分钟内完成的 tarball 回滚——与 2026 年 npm 网关运维经验一致。请交叉阅读 环境变量与密钥（2026-04-15）、健康探测 与 反向代理 / Webhook 入口，使 香港 / 日本 / 韩国 / 新加坡 / 美国 全栈叙述一致。
无头网关特有的升级风险
- 热全局 npm —— Node 仍持有句柄时替换文件会导致半安装与「幽灵」版本。
- launchd 重叠 —— 用户 LaunchAgent 若未先 unload，可能在升级中途拉起网关。
- 配置漂移 —— 新小版本可能重命名键；将不含密钥的
openclaw.json导出纳入 Git。 - Webhook 羊群效应 —— 未做就绪检查就恢复 nginx 时合作方会疯狂重试——请使用健康探测文章中的探针。
先冻结公网流量
在使用 反向代理 的主机上，将上游切到维护模式或返回 503 并带 Retry-After: 90。内部金丝雀仍应能访问 127.0.0.1:18789，以便在对外开放前完成验证。
备份矩阵：碰 npm 之前要打包什么
| 路径 / 产物 | 是否纳入？ | 说明 |
|---|---|---|
~/.openclaw（或 $OPENCLAW_STATE_DIR） |
必须 | 先停网关；用 shasum -a 256 验证 gzip 完整性 |
| 全局 npm prefix 树 | 可选 | 保存 npm prefix -g 与 npm ls -g --depth=0 文本便于 diff |
| launchd plist | 必须 | 从 ~/Library/LaunchAgents 复制到同一 tarball 目录 |
TS=$(date +%Y%m%d-%H%M)
tar -czf "/Volumes/backups/openclaw-state-$TS.tgz" -C "$HOME" .openclaw
shasum -a 256 "/Volumes/backups/openclaw-state-$TS.tgz" > "/Volumes/backups/openclaw-state-$TS.tgz.sha256"
安装与固定版本：像数据库迁移一样对待 semver
生产网关应在基础设施仓库中跟踪显式 semver，例如 1.24.3。CI 可以略快浮动，但面向合作方、放在 新加坡 的那台 Mac 不应在凌晨用破坏性插件 API 给你惊喜。停止服务后：
npm install -g openclaw@1.24.3
openclaw gateway status 并与 openclaw --version 对比；不一致表示仍处于中间态。
验证、重启与何时需要「跳两次」
运行 openclaw doctor 并将 stdout 送入日志管道。按 plist 通过 launchctl bootstrap/kickstart 启动网关。若日志出现陈旧模块路径或异常 require 栈，再执行一轮干净停/起——务必文档化，避免 on-call 误判为抖动。在解除 nginx 维护前，用 健康探测 中的合成检查重跑一遍。
回滚：恢复状态，而不是祈祷
- 再次停止网关与 nginx 上游。
- 如有需要卸载损坏的全局安装：
npm rm -g openclaw后重装旧 semver。 - 展开 tarball：
tar -xzf openclaw-state-....tgz -C "$HOME"（确认属主）。 - 若 plist 变更则恢复；按需
launchctl bootout/bootstrap。 - 验证 doctor 与内网 curl；通过后再在公网入口返回 200。
相关手册与密钥纪律
升级触碰的文件与密钥轮换相同——与 launchd 环境指引 对齐，使 .env 与 plist 键保持一致。若增加第二个网关用户做蓝绿，请按该文拆分 OPENCLAW_STATE_DIR。反复失败后需要容量时，从 定价 增加见证节点，而不是无限给一台疲惫主机打补丁。
常见问题：云 Mac 上的网关升级
| 问题 | 回答 |
|---|---|
| 用 pnpm 代替 npm？ | 支持——沿用相同的停/备份/固定/启动纪律；在手册中记录 store 路径。 |
| 能否每周自动升级？ | 仅在有金丝雀主机 + 自动 doctor + 探针门禁时；生产无人工值守时不要自动升级。 |
| 事件记在哪里？ | 使用现有桥接系统；与 结构化日志 字段关联。 |
结论：把 OpenClaw 升级当作数据库故障切换——冻结流量、备份状态、固定版本、验证两轮，并在每个运营区域演练回滚直到形成肌肉记忆。
