OpenClaw 升级避坑指南:解决 PATH 版本冲突与 Config Legacy Key 自动修复
本文记录了将 OCPlatform 从版本 2026.4.2 升级至 2026.4.5 的过程中遇到的典型问题及其解决方案,核心涉及多 Node 环境下的 PATH 优先级陷阱以及配置项变更后的自动修复流程。
升级操作: 2026.4.2 → 2026.4.5
问题现象
在本机执行 ocplatform update 命令完成升级后,在 shell 中通过 openclaw -v 查看版本,却发现显示的依然是旧的 2026.4.2 版本。
问题根源分析
问题的根源在于本机环境中并存了两个不同版本的 openclaw 可执行文件:
| 安装路径 | 版本 | 来源说明 |
|---|---|---|
/opt/homebrew/bin/openclaw |
2026.4.5 ✅ | 通过 Homebrew 下的 npm 全局安装 |
~/.asdf/installs/nodejs/24.9.0/bin/openclaw |
2026.4.2 ❌ | 通过 asdf 管理的 Node.js 24.9.0 环境下的 npm 全局安装 |
openclaw update 命令仅更新了 Homebrew 路径下的版本。由于用户在 shell 中的 PATH 环境变量设置,使得 asdf 路径的优先级更高,因此 which openclaw 命令始终指向那个旧的版本,导致版本检查出现不一致。
解决方案与步骤
- 移除 asdf 环境下的旧版本可执行文件:
执行以下命令删除旧版本:
操作完成后,再次执行
rm ~/.asdf/installs/nodejs/24.9.0/bin/openclawwhich openclaw,将正确指向/opt/homebrew/bin/openclaw,即 2026.4.5 版本。 - 终止遗留的 npm 安装进程:
在排查过程中,曾尝试通过
npm install -g openclaw@latest命令在 asdf 环境下直接更新,但该进程占用超过 1.1GB 内存且长时间未完成,最终选择手动终止该进程。
升级后出现的新问题:Config Legacy Key
在解决了版本问题并重启 gateway 服务时,遇到了新的报错信息:
Config invalid
channels.discord.accounts.<id>.guilds.<id>.channels.<id>.allow is legacy;
use channels.discord.accounts.<id>.guilds.<id>.channels.<id>.enabled instead.
问题原因: 在 2026.4.5 版本中,Discord 渠道的配置结构发生了变更,原先的 allow 字段被重命名为了 enabled,导致旧的配置文件不再兼容。
修复方法: 运行 OpenClaw 自带的诊断修复命令即可自动处理此问题:
openclaw doctor --fix
经验总结与最佳实践
- 警惕多 Node 环境下的 PATH 优先级:在使用 asdf、nvm、Homebrew 等多版本管理工具时,可能会无意中安装多份全局 CLI 工具。
openclaw update这类命令通常只更新其当前安装路径下的副本,不会更新所有副本。 - 升级前确认实际使用的二进制文件:在执行升级前,先运行
which openclaw命令,明确当前生效的 openclaw 来自哪个路径,确保后续更新操作的目标正确。 - 升级后执行诊断命令:版本升级可能伴随着配置模版(schema)的变更。升级完成后,运行
openclaw doctor是一个好习惯,它能检查并提示配置兼容性问题。 - 统一安装来源:为了避免版本混乱,建议清理多余的安装副本,并固定使用一个主要的安装源。例如,在本机环境中统一使用
/opt/homebrew/bin/openclaw。