迁移
版本迁移与升级检查单
在 OpenClaw 版本升级前后，优先检查配置、CLI、认证和入口层变化，避免把升级直接变成线上事故。
AI 摘要
这页重点
核心结论
在 OpenClaw 版本升级前后，优先检查配置、CLI、认证和入口层变化，避免把升级直接变成线上事故。
适用主题
迁移
高频关键词
migration / upgrade / release / checklist
可信信号
最后更新 2026-03-11
版本迁移与升级检查单
OpenClaw 迭代节奏较快，升级不能只看一句“有新版本了”。更稳的做法，是把每次升级都当成一次小型迁移：先看 breaking changes，再看配置和入口边界，再做验证。
先建立一个升级判断框架
每次升级前先判断这次变化属于哪类：
- 文案或界面级更新
- 新能力加入
- 配置字段变化
- 渠道或网关行为变化
- CLI、包名或扩展生态变化
真正有风险的，通常是后面三类。
一个值得记住的版本节点
根据官方 release 记录，在 2026.1.29 版本中，OpenClaw 发生过一轮关键迁移：
- npm 包和 CLI 名称统一为
openclaw - 旧名称兼容保留了一段时间
- 扩展生态移动到
@openclaw/*作用域 - 配置和状态路径引入自动迁移逻辑
这类变化说明：升级不仅可能影响命令本身，还可能影响包名、配置路径和扩展依赖。
升级前检查单
1. 看 release 里有没有这些关键词
- breaking
- migrate
- rename
- auth
- gateway
- onboarding
- doctor
2. 盘点当前环境
升级前至少要知道：
- 当前线上或本地运行的版本
- 当前使用了哪些渠道
- 是否有自定义工具、Hooks、扩展包
- 认证和网关配置是否为默认值还是自定义值
3. 备份关键配置
至少保留：
- 当前配置文件
- 环境变量清单
- 当前可工作的版本号
- 一份最小验证流程
升级后的验证顺序
不要一升级完就直接看“能不能聊天”。建议按下面顺序检查：
- 进程是否正常启动
- onboarding / Control UI 是否正常
- 认证和网关是否仍按预期工作
- 主渠道是否可用
- 常用工具与模型是否正常
哪些变化最值得警惕
CLI 与包名变化
如果官方调整了 CLI 名称、包作用域或扩展安装方式，自动化脚本、部署脚本和团队文档都可能一起失效。
认证和网关变化
release 里如果出现认证、gateway 暴露、query token、header auth、bypass 等关键词，应优先检查安全边界，而不是只看功能。
doctor / diagnostics 变化
这类变化通常意味着官方在提醒一类常见错误配置。升级后建议先跑一轮诊断，再继续扩展。
适合中国用户的升级策略
- 先在本地或预览环境验证，不要直接在线上首发
- 只在工作日白天做关键升级，便于观察和回滚
- 把 release 的核心变化翻成内部可执行检查项，而不是只转发链接
什么时候应该暂缓升级
如果你符合下面任一情况，更适合先观察：
- 当前环境稳定且没有新功能需求
- release 涉及较大的认证或渠道改动
- 团队没有准备最小回滚方案
- 你依赖了较多自定义工具或 Hook