Self Upgrade Gateway

零停机升级 OpenClaw Gateway：查 release notes → 主公确认 → 旁路备份 → npm install → node版本自动检测 → 重启 + 回滚兜底

self-upgrade-openclaw

用途

零停机升级 OpenClaw。

核心策略

text

查 release notes → 主公确认无 breaking change → 
旁路备份（安全锚点）→ npm install -g → 
修正 systemd Node 路径 → 更新 systemd 版本号 → 重启 + 健康检查 →
失败则从备份回滚 / 成功则自动清理

环境要求

项目	说明
操作系统	Linux（WSL2 亦可）
Node.js	至少一个版本满足新版 openclaw 的 engines.node 要求
npm	任意
service 管理	systemd user 模式
磁盘空间	至少 2G 可用
网络	能访问 registry.npmjs.org 和 api.github.com

前提假设

• OpenClaw 通过 npm install -g 全局安装
• 服务通过 systemd user 管理（openclaw-gateway.service）
• npm global 在 $HOME/.npm-global/
• 有 systemctl --user 权限

流程

阶段 0: 获取当前状态 + Node 版本兼容性预检

1. 读取 systemd 单元文件和 npm 全局目录，获取当前版本
2. 查询 npm registry 获取最新稳定版版本号
3. 如果最新版 ≤ 当前版，告知主公已是最新版，结束
4. Node 兼容性预检：用 npm pack 下载目标版本 → 读取 engines.node 要求 → 遍历 which -a node 及常见 Node 安装路径 → 如果没有一个 Node 版本满足要求则提示升级 Node 后重试

阶段 1: 获取 release notes，主公确认

1. 从 GitHub API 获取目标版本的 release notes
2. 展示给主公：当前版本 → 目标版本、Node 版本兼容性检查结果、release notes 核心摘要、是否包含 breaking changes
3. 询问主公是否现在升级

阶段 2: 执行升级

运行升级脚本，全自主执行：

1. 前置检查（命令可用性、磁盘空间、服务状态）
2. Node 版本兼容性预检（预下载包、读 engines、扫描兼容 Node）
3. 查 release notes（备忘）
4. 旁路备份
5. npm install -g openclaw@latest（失败自动回滚）
6. 修正 systemd ExecStart 中的 Node 路径（如果旧 Node 不满足新版本要求）
7. 更新 systemd 版本号
8. 重启 + 健康检查（60s 超时）
9. 失败回滚 / 成功清理

阶段 3: 汇报结果

安全机制

机制	说明
Node 兼容性预检	预下载包 → 解析 engines.node → 检查系统所有 Node → 无兼容版本则中止
systemd Node 路径自动修正	检测 ExecStart 中的 node 路径，不满足要求时自动切换到兼容版本
旁路备份 + 自动回滚	健康检查失败后恢复旧代码 + 旧 Node 路径 + 重启旧版
全日志落盘	不依赖终端
人工确认	先展示 release notes 再执行

变更日志

v2.0.0

• 新增 Node 版本兼容性预检
• 新增自动修正 systemd ExecStart 路径
• 兼容两种版本号格式
• 修复 release notes 查询硬编码版本号的 bug

v1.0.0

• 初始版本