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

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

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

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

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

●●●Bash

openclaw --version

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

第一步：备份一切

这步不能省。

●●●Bash

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

# 备份记忆文件（如果你在用 memory 功能）
cp -r ~/.openclaw/workspace/memory ~/.openclaw/workspace/memory.bak.$(date +%Y%m%d)

# 备份 MEMORY.md
cp ~/.openclaw/workspace/MEMORY.md ~/.openclaw/workspace/MEMORY.md.bak 2>/dev/null || true

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

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

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

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

解决：检查插件目录：

●●●Bash

openclaw doctor
# 如果看到类似警告：
# WARN: agent directory exists but no matching agents.list[] entry found
# 说明插件目录存在但配置里没有声明

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

变化二：memory QMD 集合去重

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

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

解决：

●●●Bash

# 检查是否有旧格式文件
ls ~/.openclaw/workspace/memory.md 2>/dev/null

# 如果存在，合并到 MEMORY.md
cat memory.md >> MEMORY.md && rm memory.md

变化三：gateway 默认密钥检测

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

●●●Code

ERROR: Gateway credential matches a known public example value.

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

●●●Bash

openssl rand -hex 32
# 把输出的值填到 config.yaml 里的 gateway.token

第三步：执行升级

●●●Bash

openclaw update

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

●●●Bash

# 方法一：npm 重装
npm install -g openclaw

# 方法二：清除 npx 缓存后重试
npx clear-npx-cache
npx openclaw update

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

●●●Bash

# 检查版本
openclaw --version # 应该显示 2026.4.12

# 检查配置
openclaw doctor

# 检查所有 channel 状态
openclaw status

# 如果用了 cron 任务，验证还在运行
openclaw cron list

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

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

●●●Yaml

plugins:
active-memory:
enabled: true
mode: "recent" # 建议先用 recent 模式，性能影响小

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

exec-policy 新命令：

●●●Bash

# 4.12 新增：查看当前命令执行策略
openclaw exec-policy show

# 可选：同步到严格模式
openclaw exec-policy preset strict

真实遇到过的升级故障

故障一：升级后 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 状态漂移问题已修复。直接重启服务。

升级遇到问题怎么办

1先看 openclaw doctor 输出

2检查日志：openclaw logs --tail 50

3临时回滚：用备份的 config.yaml 覆盖现有文件，openclaw restart

4社区提问：Discord 的 #help 频道，通常几小时内有人回

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

遇到问题欢迎评论区留言，说清楚版本号和报错内容，能帮你看看。

⭐点赞、转发、在看一键三连⭐，点亮星标，锁定极速推送！