朱鹏飞's Blog

Appearance

OpenClaw 版本更新避坑指南 ​

写在前面 ​

OpenClaw 更新很勤快，但每次更新都可能带来破坏性变更。我之前从 3.24 升到 3.31，翻了不少车——权限问题、配置不兼容、渠道断连，一顿折腾最后还是回退了。但回退之后数据没了，又要从头开始，损失挺大的。

这篇文章就是把这些经验教训总结成一套流程，下次更新时照着做，心里有底。

核心原则：更新前必备份，出问题先回退，不要在坏配置上硬撑。

一、更新前：这几件事必须做 ​

1.1 先看看版本差距和破坏性变更 ​

别急着升级，先看看这两个版本之间差了什么：

bash
# 看当前版本
openclaw --version

然后去 GitHub Releases 或官方文档看看：

  • 有没有 Breaking Changes（会直接废掉现有配置的变更）
  • 社区反馈怎么样，有没有人翻车
  • 特别留意渠道相关的变更（WhatsApp、Telegram、飞书这些）

1.2 备份整个状态目录 ​

这是最重要的一步。OpenClaw 的全部家当都在 ~/.openclaw/ 里，不只是 openclaw.json：

~/.openclaw/
├── openclaw.json          # 主配置
├── credentials/           # API Key、渠道登录凭证都在这
├── agents/              # Agent 会话状态
├── memory/              # 语义记忆
└── plugins/            # 插件

备份命令：

bash
# 直接复制一份（简单粗暴但有效）
cp -r ~/.openclaw ~/.openclaw.backup-$(date +%Y%m%d)

credentials 目录里是你的 API Key 和所有渠道凭证，备份文件要放好，不要传到公开的地方。

1.3 备份工作区 ​

bash
cp -r C:\project C:\project.backup-$(date +%Y%m%d)

MEMORY.md、SOUL.md 这些都在里面，丢了很可惜。

1.4 Docker 用户注意 ​

如果你是 Docker 部署的，在拉新镜像之前先给现在的镜像打个标签：

bash
docker tag openclaw/openclaw:latest openclaw/openclaw:pre-upgrade-backup

这样回退时直接用这个标签，不用担心镜像被覆盖。

二、执行更新 ​

2.1 推荐方式 ​

bash
openclaw update

这个命令会帮你做：检测安装方式 → 下载新版本 → 运行 doctor 迁移配置 → 重启 Gateway，一条龙搞定。

2.2 手动更新 ​

npm 安装：

bash
npm install -g openclaw@latest
openclaw doctor
openclaw gateway restart

Docker：

bash
docker pull openclaw/openclaw:latest
docker-compose up -d
docker exec <container> openclaw doctor

2.3 更新完必做的检查 ​

bash
# 网关状态
openclaw gateway status

# 跑一遍 doctor，自动修一些配置问题
openclaw doctor --fix

# 看下各渠道连接状态
openclaw channels list

三、出问题了怎么办：回退流程 ​

出问题时不要硬撑，第一时间回退。 在坏配置上修来修去只会越来越乱。

3.1 npm 回退 ​

bash
# 回退到指定版本（版本号从 npm 历史或者 shell 记录里找）
npm install -g openclaw@3.24.0
openclaw doctor
openclaw gateway restart

3.2 Docker 回退 ​

bash
# 用之前打的标签恢复
docker stop <container>
docker rm <container>
docker run openclaw/openclaw:pre-upgrade-backup ...

3.3 配置被玩坏了怎么回退 ​

有时更新后 openclaw.json 格式变了，doctor 也修不好，这时候：

bash
# 停网关
openclaw gateway stop

# 把坏的挪走，把备份拿回来
mv ~/.openclaw ~/.openclaw.broken
cp -r ~/.openclaw.backup-YYYYMMDD ~/.openclaw

# 装回原来那个版本
npm install -g openclaw@<原版本>
openclaw doctor
openclaw gateway start

重点：回退时版本和配置要匹配。 用新版本 OpenClaw 跑旧配置，问题只会更糟。

四、常见问题汇总 ​

权限问题 ​

症状：报错 EPERM、Permission denied、Session lock 文件冲突

原因：Windows 下 Gateway 热重启时，lock 文件残留导致新进程起不来

解决：

bash
# 不要热重启，直接停再开
openclaw gateway stop
openclaw gateway start

渠道断连 ​

症状：飞书/微信状态显示正常但收不到消息

解决步骤：

  1. 先跑 openclaw doctor --fix 看能不能救
  2. 不行的话删掉对应渠道配置，重新绑定
  3. 检查 credentials/ 下对应渠道的文件还在不在

插件加载失败 ​

bash
openclaw skills list
# 找到出问题的插件，重新装
openclaw skills install <plugin-name>

配置文件被覆盖 ​

更新后 openclaw.json 格式可能被改掉。保持备份，更新前后 diff 一下，确认是良性变更再采纳。

五、日常维护建议 ​

每周跑一次 doctor ​

bash
openclaw doctor

早发现问题早处理，别等到更新时一起爆发。

定期验证备份 ​

备份不是为了存着，是为了要用的时候真能跑通。隔段时间把备份恢复到临时目录测一下，确保没损坏。

Docker 用户 ​

每次拉新镜像前，一定先打标签备份现在的镜像。这个习惯能在出问题时救你一命。

六、给飞哥的经验教训 ​

根据我自己的血泪史：

  1. 跨版本升级风险更高 — 3.24 直接跳到 3.31，中间隔了好几个小版本，踩坑概率大。如果要升级，逐个小版本递进更稳妥。
  2. 不要在坏配置上缝缝补补 — 出问题先回退到正常状态，再分析原因。在坏配置上改来改去，最后都不知道哪里坏了。
  3. 备份时机比修复方法重要 — 回退能恢复什么取决于你备份了什么。每次更新前认真备份，回退时才能不丢数据或少丢数据。
  4. Windows 热重启不太稳 — openclaw gateway stop && start 比热重启稳定得多。

更新检查清单 ​

步骤确认
□记录当前版本号
□看完破坏性变更再动手
□备份完整状态目录 ~/.openclaw/
□备份工作区 C:\project\
□Docker 先打镜像标签
□执行 openclaw update
□运行 openclaw doctor --fix
□检查网关和渠道状态
□确认没问题后再删旧备份

记住：回退永远比硬撑靠谱。