OpenClaw Upgrade
升级 OpenClaw 主程序端到端 skill。大方向按 5 阶段跑：
- Pre-flight — 体检当前状态，建立 baseline
- Backup — 完整回滚点
- Upgrade — 跑升级 + 合并 user env
- Post-flight — diff env，确认没漏
- Verify — 健康检查 + 修复
详细流程 → 各自 references 文档。
| 阶段 | 文档 | 关键点 |
|---|---|---|
| 0. Pre-flight | references/01-preflight.md | service unit .bak + qmd doctor baseline + GPU 状态 |
| 1. Backup | references/02-backup.md | binary + service + dbs（核心：env 备份） |
| 2. Upgrade | references/03-upgrade.md | 跑升级 + 手动合并 user env（关键） |
| 3. Post-flight | references/04-postflight.md | diff env 找丢失的 + Description 跟 version 一致 |
| 4. Verify | references/05-verify.md | qmd 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 dbs |
scripts/diff-env.sh |
diff 当前 service 跟 .bak，列丢失的 user env |
scripts/qmd-rebuild-serial.sh |
串行重建 per agent qmd index（不并发） |
scripts/upgrade-report.sh |
输出升级报告模板 |
核心原则（记住这 5 条就够了）
- 先备份再动手 — 任何升级前必须有可回滚点
- env 是最容易丢的 — service unit 升级时不保留 user 自定义 env
- service 跟 user shell GPU 资源不同 — LD_LIBRARY_PATH / CUDA_HOME 必须显式设
- per agent rebuild 不要并发 — 抢 batch embed lock + GPU = timeout 砍
- 大版本升级前看 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 误判）
