升级前准备
在升级 OpenClaw 之前，建议完成以下准备工作：
# 1. 查看当前版本
openclaw --version
# 2. 备份配置文件
cp -r ~/.config/openclaw ~/.config/openclaw.backup
cp -r ~/.openclaw ~/.openclaw.backup
# 3. 停止正在运行的服务
openclaw gateway stop
升级方式
方式一：Web 安装器（推荐）
最简单的升级方式，自动检测并安装最新版本：
curl -fsSL https://install.openclaw.dev | bash
安装器会自动检测已有安装并执行升级，配置文件不受影响。
方式二：npm / pnpm 更新
如果通过包管理器安装：
# npm 升级
npm update -g openclaw
# pnpm 升级
pnpm update -g openclaw
方式三：源码升级
从 Git 仓库拉取最新代码：
cd /path/to/openclaw-source
# 确保工作区干净
git status
# 如果有未提交更改，先提交或暂存
git stash
# 拉取最新代码
git pull origin main
# 重新安装依赖
npm install
# 重新构建
npm run build
注意：源码升级要求工作区处于干净状态（clean working tree），否则 git pull 可能产生冲突。
频道切换
OpenClaw 提供多个发布频道，适合不同需求：
| 频道 | 说明 | 适用场景 |
|---|---|---|
stable |
稳定版（默认） | 生产环境 |
beta |
测试版 | 尝鲜新功能 |
dev |
开发版 | 开发者测试 |
# 切换到 beta 频道
openclaw channel switch beta
# 切换回 stable 频道
openclaw channel switch stable
# 查看当前频道
openclaw channel current
升级后操作
运行 doctor 检查
升级完成后，务必运行 openclaw doctor 进行全面检查：
openclaw doctor
doctor 命令会自动执行：
- 配置迁移：将旧版配置格式迁移到新版
- 安全审计：检查文件权限和凭证安全性
- 依赖检查：验证运行时依赖是否完整
- 兼容性检测：检查已安装插件与新版本的兼容性
重启网关
# 重启网关服务
openclaw gateway restart
# 检查健康状态
openclaw gateway health
健康检查输出示例：
Gateway Status: running
Port: 8080
Uptime: 5s
Channels: 2 connected
Agents: 3 loaded
Memory: 128MB
回滚到特定版本
如果升级后遇到问题，可以回滚到之前的版本：
# 查看可用版本
openclaw versions list
# 回滚到指定版本
npm install -g openclaw@1.2.3
# 或使用安装器指定版本
curl -fsSL https://install.openclaw.dev | bash -s -- --version 1.2.3
从备份恢复配置
# 如果 doctor 的自动迁移出现问题
cp -r ~/.config/openclaw.backup/* ~/.config/openclaw/
cp -r ~/.openclaw.backup/* ~/.openclaw/
# 重启服务
openclaw gateway restart
跨大版本升级注意事项
大版本升级（如 1.x → 2.x）可能包含破坏性变更：
# 查看升级说明
openclaw changelog
# 或查看在线文档中的迁移指南
openclaw docs migration
常见的破坏性变更：
- 配置文件格式变化（
doctor会自动迁移） - API 接口路径调整
- 插件接口变更（需要更新插件）
- 数据库 Schema 变更（
doctor会自动迁移）
自动更新
可以配置 OpenClaw 自动检查并安装更新：
{
updates: {
// 自动检查更新
autoCheck: true,
// 自动安装补丁版本更新
autoInstall: "patch",
// 更新检查间隔（小时）
checkInterval: 24
}
}
常见问题排查
- 升级后无法启动：运行
openclaw doctor检查配置兼容性 - 插件不兼容：暂时禁用插件后启动，等待插件作者更新
- 配置迁移失败：从备份恢复旧配置，手动参照文档调整格式
- 版本降级失败：确认指定的版本号存在于发布列表中