技能介绍

OpenClaw 大版本跳升从来不是简单 git pull 能解决的。实际运维中最常见的坑包括：

service unit 升级后 user 自定义 env 丢失：service manager 不会保留你在 .env 里手动加的配置，升级后 LD_LIBRARY_PATH、CUDA_HOME 等关键变量直接蒸发，导致 nvidia-smi 报找不到 GPU，但实际上 GPU 确实在跑（WSL2 环境尤甚）。
qmd 索引 ABI mismatch：跨大版本（0.1.x → 2.0/2.5）时，silent ABI mismatch 会抛出 Dimension mismatch 或 better_sqlite3.node 找不到，问题不会直接报错给你看。
per agent 并发重建 index 踩 GPU batch embed lock：多个 agent 同时 rebuild qmd index 会抢 batch embed lock，加上 GPU 资源争用，timeout 直接把进程砍掉，留下半成品 index。

这个 skill 就是把这些散落的坑整理成一套可重复执行的升级流程。

核心思路是 先备份再动手，分阶段验证，每一步都有对应的 references 文档和辅助脚本：

Pre-flight（references/01-preflight.md）：体检当前状态，包括 service unit 的 .bak 备份、qmd doctor baseline 检查、GPU 状态确认，建立升级前的快照。
Backup（references/02-backup.md）：一键备份 service unit、binary、per agent dbs。核心动作是 env 备份，用 scripts/backup-env.sh 把当前所有 user 自定义环境变量导出，这是回滚的生命线。
Upgrade（references/03-upgrade.md）：跑升级流程，但关键动作是 手动合并 user env——skill 会指导你把备份的 env 逐项 merge 回新版 service unit，而不是指望升级脚本自动保留。
Post-flight（references/04-postflight.md）：用 scripts/diff-env.sh 对比当前 service 与 .bak，找出丢失的 user env；同时确认 Description 和 version 字段一致。
Verify（references/05-verify.md）：跑 qmd doctor + memory_search 健康检查，然后串行重建 per agent qmd index（用 scripts/qmd-rebuild-serial.sh，明确不并发），最后用 scripts/upgrade-report.sh 输出升级报告。
紧急回滚（references/06-rollback.md）：如果完全跑不起来，这里提供了逐步回滚步骤。

这个 skill 的设计前提是 你已经在本地 fork 了 OpenClaw 源码，并且熟悉 service unit 的配置方式。它不适用于：

纯 Docker 或容器化部署的升级场景（references 里提到的都是 service unit、binary 层面的操作）。
首次部署而非升级——pre-flight 阶段假设你已经有可回滚的 baseline。
references/80-notes.md 里列出了更多容易踩的点，建议升级前过一遍，比如确认你的 qmd 版本跨度是否触发了已知的 silent failure 高发期。

核心原则只有一句：env 是最容易丢的，service 跟 user shell 的 GPU 资源完全不同，所有环境变量必须显式设。