从旧版升到OpenClaw 4.12可能遇到的问题和解法全在这里

不少人反馈：OpenClaw 升级这件事，看着简单，实际上坑不少。

特别是从 4.x 早期版本（4.0 ~ 4.9）升上来的用户，配置结构、插件行为都有一些变化。

这篇专门讲「从旧版本升级」这件事。

升级前：先搞清楚你现在的版本

• ▶4.9 及以下 → 有较多配置迁移工作，建议逐步升
• ▶4.10 ~ 4.11 → 直接升，改动不大，主要是几个配置字段调整
• ▶4.12 RC 版本 → 直接覆盖即可

第一步：备份一切

这步不能省。

第二步：了解 4.12 的破坏性变化

变化一：插件加载方式改变

旧版本所有插件在启动时全量加载，4.12 改为按 manifest 声明按需加载。

影响：如果你的自定义插件没有正确声明 manifest.json，它可能在 4.12 里无法自动加载。

解决：检查插件目录：

手动在 config 里补上缺失的 agent 声明，或者删除孤立目录。

变化二：memory QMD 集合去重

旧版本会把 memory.md（小写）注册为独立集合，4.12 改为统一使用 MEMORY.md（大写）+ memory/ 目录树。

影响：如果你同时有 memory.md 和 MEMORY.md，旧的小写版本不再被识别。

解决：

变化三：gateway 默认密钥检测

如果你用的是从 .env.example 直接复制来的默认密钥，4.12 启动时会直接报错拒绝启动。

解决：生成新的随机密钥：

第三步：执行升级

如果更新脚本报错（chunk 路径失效，这是旧版本的 bug）：

第四步：升级后的健康检查

从 4.9 以下升级的额外注意事项

Active Memory 是新功能，默认关闭。 如果你想开启：

Dreaming 时区问题已修复。 如果旧版本的 DREAMS.md 里时间戳显示 UTC，现在会自动使用本地时区。

exec-policy 新命令：

真实遇到过的升级故障

故障一：升级后 Telegram 审批按钮无响应

→ 这是 4.12 之前的 bug，升到 4.12 就修了。如果升后仍有问题，重启 OpenClaw 进程。

故障二：Discord 频道连接报 WARN，消息发不出去

→ 检查 channels.discord.streaming 配置是否被旧版 doctor --fix 改坏（见坑二篇）。

故障三：升级后 iMessage 通道频繁重连

→ 4.12 修了 iMessage 的 watch.subscribe 重试逻辑，重启一次就好。

故障四：WhatsApp 重连后发消息没反应

→ 4.12 重写了 WhatsApp 连接所有权管理，老连接的 socket 状态漂移问题已修复。直接重启服务。

升级遇到问题怎么办

升级顺利的话不用花超过 10 分钟。