OpenClaw Upgrade#

升级 OpenClaw 主程序端到端 skill。 大方向按 5 阶段跑：

1. Pre-flight — 体检当前状态，建立 baseline
2. Backup — 完整回滚点
3. Upgrade — 跑升级 + 合并 user env
4. Post-flight — diff env，确认没漏
5. Verify — 健康检查 + 修复

详细流程 → 各自 references 文档。

阶段文档关键点0. Pre-flightreferences/01-preflight.mdservice unit .bak + qmd doctor baseline + GPU 状态1. Backupreferences/02-backup.mdbinary + service + dbs（ 核心：env 备份）2. Upgradereferences/03-upgrade.md跑升级 + 手动合并 user env（关键）3. Post-flightreferences/04-postflight.mddiff env 找丢失的 + Description 跟 version 一致4. Verifyreferences/05-verify.mdqmd doctor + memory_search + per agent serial rebuild紧急回滚references/06-rollback.md完全跑不起来的回滚步骤注意事项references/80-notes.md一些容易踩的点（不是 silent failure 之王）

辅助脚本#

脚本用途scripts/backup-env.sh一键备份 service unit + binary + per agent dbsscripts/diff-env.shdiff 当前 service 跟 .bak，列丢失的 user envscripts/qmd-rebuild-serial.sh串行 重建 per agent qmd index（不并发）scripts/upgrade-report.sh输出升级报告模板

核心原则（记住这 5 条就够了）#

1. 先备份再动手 — 任何升级前必须有可回滚点
2. env 是最容易丢的 — service unit 升级时 不保留 user 自定义 env
3. service 跟 user shell GPU 资源不同 — LD_LIBRARY_PATH / CUDA_HOME 必须显式设
4. per agent rebuild 不要并发 — 抢 batch embed lock + GPU = timeout 砍
5. 大版本升级前看 changelog — qmd 跳 0.1.x → 2.0 / 2.5 是 silent ABI mismatch 高发期

触发场景#

• user 喊"升级 OpenClaw" / "5.28 → 6.0" / "升级 5.28"
• 5.28 service 跑得不对劲（memory_search 报错 / agent timeout）
• qmd 报错 ABI mismatch / Dimension mismatch / better_sqlite3.node 找不到
• service unit 升级后 user 自定义 env 丢失
• nvidia-smi 找不到但实际 GPU 在（WSL2 误判）