版本升级策略

升级类型

类型	说明	变化程度	建议
Patch升级	修复bug	小	直接升级
Minor升级	新功能	中	测试后升级
Major升级	大版本	大	全面测试后升级

版本号规则

版本号：1.2.3

- 1：Major版本（大版本，可能有破坏性变化）
- 2：Minor版本（新功能，向后兼容）
- 3：Patch版本（bug修复）

升级决策

当前版本：1.1.5

可用版本：
- 1.1.6 (Patch) → 可直接升级
- 1.2.0 (Minor) → 测试后升级
- 2.0.0 (Major) → 评估后升级

决策：
- Patch：自动升级
- Minor：周末测试后升级
- Major：先在新环境测试，确认兼容后再升级生产

---

升级前准备

检查当前版本

# 查看当前版本
openclaw --version

# 输出
OpenClaw v1.1.5
Node.js v18.17.0

检查可用更新

# 检查更新
openclaw update check

# 输出
当前版本：1.1.5
可用版本：
  - 1.1.6 (Patch)
  - 1.2.0 (Minor)
  - 2.0.0 (Major)

推荐升级：1.2.0 (Minor)

变更日志：
  1.2.0:
    - 新增：MCP支持
    - 新增：Gateway模式
    - 改进：性能优化20%
    
  1.1.6:
    - 修复：内存泄漏问题
    - 修复：飞书连接稳定性

备份当前配置

# 备份配置文件
cp ~/.openclaw/config.yaml ~/.openclaw/config.yaml.bak

# 备份整个配置目录
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# 备份数据库
pg_dump openclaw > openclaw-db-$(date +%Y%m%d).sql

---

升级流程

Patch版本升级

# 直接升级
openclaw update

# 或指定版本
openclaw update --version 1.1.6

# 输出
正在升级到 1.1.6...
✅ 下载完成
✅ 安装完成
✅ 验证成功

当前版本：1.1.6

Minor版本升级

# 1. 测试环境升级
openclaw update --version 1.2.0

# 2. 运行测试
openclaw test --all

# 3. 检查配置兼容性
openclaw config migrate --check

# 输出
配置迁移检查：
✅ agents: 兼容
✅ channels: 兼容
⚠️ skills: 需要更新格式

建议运行：openclaw config migrate

Major版本升级

# 1. 创建新环境测试
mkdir ~/.openclaw-v2
cp ~/.openclaw/config.yaml ~/.openclaw-v2/

# 2. 在新环境测试升级
export OPENCLAW_CONFIG=~/.openclaw-v2
openclaw update --version 2.0.0

# 3. 运行迁移
openclaw config migrate --major

# 4. 全面测试
openclaw test --all --verbose

# 5. 确认无问题后升级生产
# 回到生产配置
unset OPENCLAW_CONFIG

# 升级生产
openclaw update --version 2.0.0
openclaw config migrate --major
openclaw restart

---

配置迁移

配置兼容检查

# 检查配置是否需要迁移
openclaw config migrate --check

# 输出
配置迁移分析：

需要迁移的配置项：
1. skills配置格式（v1 → v2）
   - 旧格式：skills: ["skill1", "skill2"]
   - 新格式：skills:
              - name: skill1
                version: latest
                
2. channel配置结构
   - 新增：retry配置
   - 新增：timeout配置

不兼容的配置项：
1. providers.openai.modelMapping
   - 此功能已移除，请使用 providers.openai.models

迁移命令：openclaw config migrate

执行配置迁移

# 自动迁移配置
openclaw config migrate

# 输出
正在迁移配置...

迁移项目：
✅ skills配置格式更新
✅ channel配置更新
⚠️ providers.openai.modelMapping → 需要手动处理

迁移完成！
配置已保存到：~/.openclaw/config.yaml

原配置备份：~/.openclaw/config.yaml.v1.1.5

手动迁移不兼容项

# 旧配置（v1.x）
providers:
  openai:
    apiKey: "${OPENAI_API_KEY}"
    modelMapping:
      default: "gpt-4o"
      fast: "gpt-3.5-turbo"

# 新配置（v2.x）
providers:
  openai:
    apiKey: "${OPENAI_API_KEY}"
    models:
      - name: "gpt-4o"
        alias: "default"
      - name: "gpt-3.5-turbo"
        alias: "fast"

---

版本间差异

v1.x → v2.x 主要变化

变化项	v1.x	v2.x
Skills配置	数组格式	对象格式
MCP支持	不支持	支持
Gateway模式	不支持	支持
配置热重载	不支持	支持
多Agent协作	不支持	支持

Skills配置迁移

# v1.x 格式
agents:
  my-agent:
    model: "deepseek-chat"
    skills:
      - daily-news
      - weather

# v2.x 格式
agents:
  my-agent:
    model: "deepseek-chat"
    skills:
      - name: daily-news
        version: latest
        enabled: true
        
      - name: weather
        version: latest
        enabled: true

Channel配置迁移

# v1.x 格式
channels:
  feishu:
    enabled: true
    appId: "cli_xxx"
    appSecret: "${FEISHU_SECRET}"

# v2.x 格式
channels:
  feishu:
    enabled: true
    appId: "cli_xxx"
    appSecret: "${FEISHU_SECRET}"
    
    # 新增配置
    retry:
      enabled: true
      maxRetries: 3
      
    timeout:
      connect: 5000
      request: 30000
      
    healthCheck:
      enabled: true
      interval: 30000

---

升级后验证

功能验证

# 运行功能测试
openclaw test --all

# 输出
功能测试结果：

✅ 服务启动测试
✅ Agent运行测试
✅ Channel连接测试
✅ Skills调用测试
✅ MCP工具测试
✅ Gateway模式测试

全部测试通过！

性能验证

# 性能对比
openclaw benchmark compare --prev-version 1.1.5

# 输出
性能对比（1.1.5 → 1.2.0）：

响应时间：
  - 平均：200ms → 160ms（提升20%）
  - P99：500ms → 400ms（提升20%）

内存使用：
  - 平均：512MB → 450MB（减少12%）

吞吐量：
  - QPS：50 → 60（提升20%）

性能提升明显！

兼容性验证

# 兼容性测试
openclaw test compatibility

# 输出
兼容性测试：

✅ 配置文件兼容
✅ Skills兼容
✅ Channels兼容
✅ MCP服务器兼容
⚠️ 插件需要更新（2个）

需要更新的插件：
1. my-plugin-1 → 请运行 openclaw plugin update my-plugin-1
2. my-plugin-2 → 请运行 openclaw plugin update my-plugin-2

---

回滚流程

快速回滚

# 回滚到上一版本
openclaw rollback

# 输出
正在回滚...
从 1.2.0 回滚到 1.1.5

✅ 版本回滚成功
✅ 配置恢复成功

当前版本：1.1.5

回滚到指定版本

# 回滚到指定版本
openclaw rollback --version 1.1.5

# 恢复配置备份
cp ~/.openclaw/config.yaml.bak ~/.openclaw/config.yaml

# 重启服务
openclaw restart

紧急回滚

# 紧急回滚（不验证）
openclaw rollback --force

# 输出
紧急回滚模式：
跳过验证，立即回滚

✅ 版本回滚：1.2.0 → 1.1.5
✅ 配置恢复
✅ 服务重启

警告：紧急回滚可能导致部分数据丢失
建议检查服务状态：openclaw status

---

版本锁定

锁定当前版本

# ~/.openclaw/config.yaml

version:
  # 锁定版本
  locked: true
  current: "1.1.5"
  
  # 自动更新配置
  autoUpdate:
    enabled: true
    # 只自动更新Patch版本
    allowPatch: true
    # 不自动更新Minor版本
    allowMinor: false
    # 不自动更新Major版本
    allowMajor: false

版本锁定命令

# 锁定当前版本
openclaw version lock

# 解锁版本
openclaw version unlock

# 查看版本状态
openclaw version status

# 输出
版本状态：
当前版本：1.1.5
锁定状态：已锁定
自动更新：Patch版本

---

多版本管理

版本切换

# 查看已安装版本
openclaw version list

# 输出
已安装版本：
  - 1.1.5 (当前)
  - 1.2.0
  - 2.0.0

# 切换版本
openclaw version use 1.2.0

# 输出
切换到版本 1.2.0
当前版本：1.2.0

并行运行多版本

# 使用不同配置运行不同版本

# v1.1.5 环境
export OPENCLAW_CONFIG=~/.openclaw-v1
export OPENCLAW_VERSION=1.1.5
openclaw start --port 3000

# v2.0.0 环境
export OPENCLAW_CONFIG=~/.openclaw-v2
export OPENCLAW_VERSION=2.0.0
openclaw start --port 3001

---

升级最佳实践

升级时间选择

场景	建议
Patch升级	随时升级
Minor升级	周末或非高峰期升级
Major升级	预留充足时间，提前测试

升级检查清单

升级前检查：
✅ 查看当前版本
✅ 查看更新日志
✅ 备份配置文件
✅ 备份数据库
✅ 测试环境验证

升级中检查：
✅ 执行升级命令
✅ 运行配置迁移
✅ 运行功能测试
✅ 检查错误日志

升级后检查：
✅ 验证功能正常
✅ 验证性能稳定
✅ 验证兼容性
✅ 观察运行状态

---

升级命令速查

命令	说明
openclaw --version	查看版本
openclaw update check	检查更新
openclaw update	升级到最新版
openclaw update --version x.x.x	升级到指定版本
openclaw config migrate --check	检查迁移
openclaw config migrate	执行迁移
openclaw rollback	回滚到上一版本
openclaw rollback --version x.x.x	回滚到指定版本
openclaw version lock	锁定版本
openclaw version list	列出已安装版本

---

总结

OpenClaw版本升级：

步骤	说明
1	检查当前版本和可用更新
2	备份配置和数据
3	执行升级命令
4	运行配置迁移
5	功能和性能验证
6	如有问题则回滚

平滑升级，不踩坑。

版本管理，掌控自如。

---

🦞 Claw is the law. 版本升级，稳中求进。