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 命令始终指向那个旧的版本，导致版本检查出现不一致。

解决方案与步骤

  1. 移除 asdf 环境下的旧版本可执行文件： 执行以下命令删除旧版本： 
    rm ~/.asdf/installs/nodejs/24.9.0/bin/openclaw
    操作完成后，再次执行 which openclaw，将正确指向 /opt/homebrew/bin/openclaw，即 2026.4.5 版本。
  2. 终止遗留的 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

经验总结与最佳实践

  1. 警惕多 Node 环境下的 PATH 优先级：在使用 asdf、nvm、Homebrew 等多版本管理工具时，可能会无意中安装多份全局 CLI 工具。openclaw update 这类命令通常只更新其当前安装路径下的副本，不会更新所有副本。
  2. 升级前确认实际使用的二进制文件：在执行升级前，先运行 which openclaw 命令，明确当前生效的 openclaw 来自哪个路径，确保后续更新操作的目标正确。
  3. 升级后执行诊断命令：版本升级可能伴随着配置模版（schema）的变更。升级完成后，运行 openclaw doctor 是一个好习惯，它能检查并提示配置兼容性问题。
  4. 统一安装来源：为了避免版本混乱，建议清理多余的安装副本，并固定使用一个主要的安装源。例如，在本机环境中统一使用 /opt/homebrew/bin/openclaw。