openclaw --version 能输出新版本，只证明 CLI 入口还活着。渠道可能收不到消息，Plugin 可能只完成本地发现却没有在 Gateway 中运行，Browser profile 可能丢失，审批策略也可能发生漂移。
这套升级实验把“成功”拆成八个金丝雀，并提前写好两层回滚：先回退代码，只有旧版本读不了新状态时才恢复备份。
本文依据 2026-09-09 的当前文档核读。npm registry 当日 latest 为 2026.9.3，其 Node 要求是 >=24.16.0 <25 || >=26.1.0。你选择 beta、extended-stable、dev 或固定版本时，以 openclaw update status --json 和目标版本包信息为准，不能照抄本站日期替代现场检查。
1. 先识别安装类型和恢复对象
记录当前版本、Node 版本、安装方式、channel、Gateway 运行方式、配置目录、状态目录、必要 Plugin、渠道和 Browser profile。npm、pnpm、Bun、git 与容器的代码回退方式不同；容器还要检查镜像、volume 和编排 readiness。
把恢复对象分成三层：
| 层 | 例子 | 回退方式 |
|---|---|---|
| 代码 | CLI 包、git checkout、容器镜像 | 重装旧版本或切回旧镜像 |
| 配置 | policy、channels、plugins config | 从已验证备份选择性恢复 |
| 状态 | sessions、凭据、pairing、数据库 | 最后手段，离线恢复 |
升级后产生的新会话和消息属于新状态。恢复旧快照会丢弃备份点以后的变化，所以不能把“有备份”理解成无损撤销。
2. 记录可比较的升级前基线
在受保护目录保存输出，先遮掉 token、手机号、账号和内部地址：
openclaw --version
node --version
openclaw update status --json > update-status-before.json
openclaw doctor --lint --json > doctor-before.json
openclaw gateway status --deep --json > gateway-before.json
openclaw plugins list --json > plugins-before.json再完成 U05–U07 三个业务基线：用自有测试渠道发送唯一 token；触发一个无害审批案例；用专用 Browser profile 打开无敏感数据的已登录测试页。保存预期与实际，不记录密码、Cookie 或完整消息内容。
3. 先 dry-run，再批准目标版本
openclaw update --dry-run --json > update-plan.json检查安装类型、当前 channel、目标版本、包来源、需要重启的组件和 Plugin 兼容提示。若目标超出已批准版本、Node 不满足 engines、关键 Plugin 没有兼容证据，停止升级。
需要换 channel 时使用官方当前支持的参数，例如：
openclaw update --channel extended-stable --dry-run先预演再去掉 --dry-run。不要把 dev、beta 或浮动版本用于生产，仅因为它包含一个想试的新功能。
4. 创建真正的恢复点
官方当前推荐显式创建并验证 broad backup：
mkdir -p ~/Backups/openclaw
chmod 700 ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify检查 archive manifest 中记录的 OpenClaw 版本与源路径。备份可能包含凭据、认证 profile 和渠道状态，必须像线上状态目录一样保护；不要上传到网盘公开链接、Git 仓库、聊天或工单。
openclaw update 的自动预更新配置副本不是完整恢复点。backup create 的 broad archive 也不是“一条命令原地激活”：需要状态恢复时，应先解压到 staging，再按 manifest 的来源映射离线恢复。
5. 执行升级并保留完整输出
在维护窗口运行已批准的命令：
openclaw update当前官方流程会识别安装类型、获取版本、运行 doctor 并重启 Gateway。命令中途失败时，不要立刻手工删除缓存或改配置；保存退出码和最后成功阶段，确认 updater 是否已完成自己的代码回退。
升级完成后先查看：
openclaw --version
openclaw doctor
openclaw gateway restart
openclaw health先阅读 doctor。只有明确知道它要修什么、已保存备份并接受变更时，才考虑 doctor --fix。
6. 按 U01–U08 逐层验收
使用下载矩阵，不改变顺序：
- U01 CLI：版本等于批准目标。
- U02 Config：lint 没有新增阻断诊断。
- U03 Gateway：deep status 和 health 健康。
- U04 Plugin：必要 Plugin 仍在，
plugins doctor --json无兼容或加载失败。 - U05 Channel：自有测试账号完成一次入站和一次原路出站，无重复。
- U06 Approval：同一无害命令仍得到预期 allow、ask 或 deny，并留下正确审计路径。
- U07 Browser：专用 profile 能打开测试页面，没有要求 Agent 自动输入凭据。
- U08 Backup：备份 manifest 可读、验证成功、位置受保护。
openclaw plugins doctor 检查本地 discovery、模块加载、兼容性和配置。运行时状态仍以 openclaw health 为准，两个检查不能互相替代。
任一关键金丝雀失败就暂停流量，不要一边让真实用户继续使用一边盲目修复。
7. 先判断是否只需代码回退
如果新版本代码有问题，但旧版本仍能读取当前配置和状态，优先重装已知旧版本或切回旧镜像。具体命令取决于安装类型，必须来自升级前记录；不要在事故中临时猜包管理器。
代码回退后运行：
openclaw --version
openclaw health
openclaw plugins list --json
openclaw gateway status --deep --json
openclaw doctor --lint --json如果旧版本不能读取迁移后的配置或数据库，再进入状态恢复。先停止 Gateway，另存当前状态，解压 broad archive 到 staging，逐项核对 manifest 后离线恢复。跨 session SQLite 迁移等特殊降级必须采用当前官方 Updating 文档针对该版本给出的步骤。
8. 用通过、回滚或观察结束变更
验收记录只能给出三种结果：
- 通过：八项全部满足，恢复正常流量。
- 回滚：关键链路失败，代码或状态已经按计划恢复并重新验收。
- 暂停观察：非关键问题不影响当前流量，但有负责人、截止时间和退出条件。
把实际目标版本、失败 canary_id、诊断、修复与最终状态写入记录。下一次升级应直接复用这份证据，而不是重新凭记忆列清单。