核心用法
openclaw-upgrade 是一套针对 OpenClaw 平台的标准化升级运维技能，通过九步闭环流程实现安全可控的版本迭代：
1. 环境探测（第零步）：自动检测 Node.js 版本、IPv4/IPv6 网络速度差异、代理可用性、多用户冲突风险及临时目录权限，提前暴露升级 blocker
2. 目标版本确认（第一步）：对比当前与目标版本，通过 GitHub API 获取 release notes，并强制核对 Node 版本兼容性（engines.node 字段），避免版本不匹配导致的 gateway 启动失败
3. 插件兼容性扫描（第二步）：针对 feishu、lossless-claw、minimax 等关键插件检索 release notes 中的 breaking changes
4. 快照与备份（第三至四步）：完整备份 openclaw.json、.env、systemd override.conf、lossless-claw 及 feishu 插件目录
5. 预置通知 cron（第五步）：在重启前设置 3 分钟后触发的 systemEvent 通知，解决升级完成后 session 丢失导致的"静默完成"问题
6. 执行升级（第六步）：根据网络探测结果自动注入代理或 IPv4 优先策略，执行 npm install -g openclaw@<target>
7. 多维度验证（第七步）：版本校验、doctor 诊断、插件加载状态对比、diff 快照差异
8. 安全重启（第八步）：优先使用平台 `gateway` 工具而非裸调 systemctl，规避进程树自毁风险
9. 一键回滚：任一步骤异常时，可快速还原至备份版本并重启 gateway
显著优点
- 教训驱动设计：每个步骤均对应真实生产事故（NAS 欢欢 6 小时停机、IPv6 卡顿 4 分半、Node 版本不匹配导致 gateway 拒启），形成可执行的防御性编程范式
- 多实例感知：自动检测同机其他 OpenClaw 用户及 WSL 实例，规避
npm install -g的全局副作用 - 网络自适应：IPv4/IPv6 速度探测 +
NODE_OPTIONS动态注入，解决 registry.npmjs.org 的 connectivity 瓶颈 - 零静默失败：预置 cron 通知机制，确保升级结果必达
- 回滚即代码：备份清单与还原逻辑脚本化，故障时分钟级恢复
潜在缺点与局限性
- 平台耦合：深度依赖 OpenClaw 生态（systemd user service、特定目录结构、
gateway工具等），迁移至其他 Agent 平台需大幅改造 - Node 升级外部化：仅检测 Node 版本缺口，实际 Node 升级需人工介入（apt/nvm），未实现全自动化
- WSL 检测脆弱性：依赖
powershell.exe与 WSL interop，部分精简版 WSL 环境可能探测失败 - GitHub API 依赖：获取 release notes 需有效的
GITHUB_TOKEN，令牌失效时将降级为盲升级
适合的目标群体
- OpenClaw 私有化部署运维人员：WSL2/Linux VM/原生 Linux 环境下的系统管理员
- 多用户共享开发机场景：实验室、家庭 NAS、团队共享服务器等存在多个 OpenClaw 实例的环境
- 对可用性敏感的生产环境：不能容忍 gateway 长时间中断、需要可审计回滚能力的业务部署
常规风险提示
- 性能风险：npm install 期间若触发插件依赖首次安装（如 codex），可能出现 3-5 分钟的 CPU/IO 峰值，需提前评估系统负载
- 依赖项风险：lossless-claw 等外部插件与主版本存在历史不兼容记录（4.14 事故），升级前必须人工复核 release notes
- 网络稳定性：IPv6 慢速或 npm registry 瞬断可能导致 install 挂起，建议配合
timeout或 CI 超时机制使用 - 权限隐患：
/tmp/jiti权限问题可能导致 codex 插件 EACCES 错误，多用户环境需确保chmod 1777 - session 中断：第八步重启必然中断当前对话上下文，所有关键信息必须在第五步前固化至 cron payload