OpenClaw版本升级和更新教程

前言

OpenClaw 作为一个活跃的开源项目（GitHub 100k+ stars），版本更新频繁，新版本通常包含功能改进、性能优化和安全修复。本文将介绍如何安全地进行版本升级，包括更新前的准备工作、多种安装方式的更新方法、以及出问题时的回滚策略。

升级前的准备

在进行任何升级操作之前，务必完成以下准备工作。

查看当前版本

openclaw --version

查看最新版本和变更日志

# 查看 npm 上的最新版本
npm view openclaw version

# 查看所有可用版本
npm view openclaw versions --json

# 查看变更日志
npm view openclaw changelog

你也可以在 GitHub 的 Releases 页面查看每个版本的详细更新说明：

https://github.com/openclaw/openclaw/releases

检查当前配置

确认当前运行状态正常：

openclaw doctor

备份配置和数据

这是最重要的一步，请不要跳过：

# 创建备份目录
mkdir -p ~/openclaw-backup/$(date +%Y%m%d)

# 备份配置文件
cp -r ~/.config/openclaw ~/openclaw-backup/$(date +%Y%m%d)/config

# 备份技能文件
cp -r ~/.openclaw ~/openclaw-backup/$(date +%Y%m%d)/openclaw-data

# 记录当前版本号
openclaw --version > ~/openclaw-backup/$(date +%Y%m%d)/version.txt

echo "备份完成：~/openclaw-backup/$(date +%Y%m%d)"

你也可以写一个简单的备份脚本方便日后使用：

cat > ~/openclaw-backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="$HOME/openclaw-backup/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp -r ~/.config/openclaw "$BACKUP_DIR/config" 2>/dev/null
cp -r ~/.openclaw "$BACKUP_DIR/openclaw-data" 2>/dev/null
openclaw --version > "$BACKUP_DIR/version.txt" 2>/dev/null
echo "备份已保存到: $BACKUP_DIR"
EOF
chmod +x ~/openclaw-backup.sh

npm 方式更新

更新到最新版本

# 停止 OpenClaw
openclaw restart  # 或先手动停止

# 更新到最新版本
npm install -g openclaw@latest

# 验证版本
openclaw --version

# 重新启动
openclaw up

更新到指定版本

如果你不想直接跳到最新版本，可以指定具体的版本号：

npm install -g [email protected]

检查是否有可用更新

npm outdated -g openclaw

输出示例：

Package    Current  Wanted  Latest  Location
openclaw   2.4.3    2.5.1   2.5.1   global

Current：当前安装的版本
Wanted：满足版本范围的最新版本
Latest：npm 上的最新版本

Homebrew 方式更新

如果你通过 Homebrew 安装，更新过程非常简单：

# 更新 Homebrew 索引
brew update

# 查看是否有 OpenClaw 更新
brew outdated openclaw

# 升级 OpenClaw
brew upgrade openclaw

# 重启服务
openclaw restart

Docker 方式更新

更新 Docker 镜像

# 拉取最新镜像
docker pull openclaw/openclaw:latest

# 停止并删除旧容器
docker stop openclaw
docker rm openclaw

# 用新镜像重新创建容器
docker run -d \
  --name openclaw \
  --restart always \
  -p 18789:18789 \
  -v /path/to/config:/app/config \
  -v /path/to/data:/app/data \
  -e OPENCLAW_CONFIG=/app/config/openclaw.json5 \
  -e TZ=Asia/Shanghai \
  openclaw/openclaw:latest

docker-compose 方式更新

cd /path/to/openclaw-compose

# 拉取最新镜像
docker-compose pull

# 重新创建容器
docker-compose up -d

# 清理旧镜像
docker image prune -f

更新到指定 Docker 版本

docker pull openclaw/openclaw:2.5.0

然后修改 docker-compose.yml 中的 image 标签，或在 docker run 命令中指定版本号。

升级后的验证

无论使用哪种方式升级，完成后都应该进行验证：

# 确认版本号
openclaw --version

# 运行诊断
openclaw doctor

# 检查日志是否有错误
openclaw logs

# 测试 Dashboard 是否可访问
curl -s http://localhost:18789/health

验证清单

检查项目	验证方法	预期结果
版本号	`openclaw --version`	显示新版本号
服务状态	`openclaw doctor`	所有检查通过
Dashboard	浏览器访问	正常加载页面
日志	`openclaw logs`	无异常错误
频道连接	发送测试消息	正常回复
技能	`openclaw skill list`	已有技能正常列出

回滚到旧版本

如果新版本出现问题，可以快速回滚。

npm 回滚

# 安装指定旧版本
npm install -g [email protected]

# 恢复备份的配置文件
cp -r ~/openclaw-backup/20260318/config/* ~/.config/openclaw/

# 重启
openclaw restart

Docker 回滚

# 使用旧版本镜像重建容器
docker stop openclaw
docker rm openclaw
docker run -d \
  --name openclaw \
  --restart always \
  -p 18789:18789 \
  -v /path/to/config:/app/config \
  -v /path/to/data:/app/data \
  openclaw/openclaw:2.4.3

Homebrew 回滚

Homebrew 不直接支持回滚，但可以通过 npm 安装指定版本：

brew uninstall openclaw
npm install -g [email protected]

自动更新策略

使用 cron 定时检查更新

创建一个检查更新的脚本：

cat > ~/openclaw-check-update.sh << 'SCRIPT'
#!/bin/bash
CURRENT=$(openclaw --version 2>/dev/null)
LATEST=$(npm view openclaw version 2>/dev/null)

if [ "$CURRENT" != "$LATEST" ]; then
    echo "[$(date)] OpenClaw 有新版本可用: $CURRENT -> $LATEST"
    # 可选：发送通知
fi
SCRIPT
chmod +x ~/openclaw-check-update.sh

# 每天检查一次
(crontab -l 2>/dev/null; echo "0 9 * * * ~/openclaw-check-update.sh >> ~/openclaw-update.log") | crontab -

Docker Watchtower 自动更新

使用 Watchtower 可以自动更新 Docker 容器：

docker run -d \
  --name watchtower \
  --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --interval 86400 \
  openclaw

这会每 24 小时检查一次 OpenClaw 镜像是否有更新，自动拉取新镜像并重启容器。

大版本升级注意事项

当进行大版本升级（如从 1.x 到 2.x）时，需要特别注意：

仔细阅读 Release Notes — 大版本通常包含破坏性变更
检查配置文件格式变化 — 新版可能修改了配置文件结构
运行配置迁移工具（如果有）：

openclaw migrate

在测试环境先行验证 — 先在非生产环境测试新版本
准备回滚方案 — 确保有完整的备份

更新频率建议

更新类型	版本号变化	建议策略
补丁版本	x.x.1 → x.x.2	及时更新，通常是 bug 修复
次版本	x.1.x → x.2.x	一周内更新，新功能和改进
主版本	1.x.x → 2.x.x	谨慎更新，先阅读迁移指南

总结

版本升级是保持 OpenClaw 稳定和安全运行的重要环节。核心原则是：备份先行，验证随后，回滚备案。养成定期检查更新的习惯，及时修补安全漏洞，同时避免盲目追求最新版本而影响生产环境的稳定性。