夜雨聆风
OpenClaw 升级5.22至5.26填坑记录
小龙虾🦞OpenClaw 个人实践 · B-25
升级排查专篇 · 主程对了插件没对齐 · 从报错到收敛
OpenClaw 升级别只看版本号
插件偷偷”反超”主程，对话直接炸了
本文基于我自己 2026.5.22 → 2026.5.26 的一次真实升级 · 命令可直接复制 · 适合在用 OpenClaw 的人
有读者问：照着升级步骤一步步做完，openclaw --version 也已经显示成新版本了，怎么一发消息就报错？
这个问题我自己刚踩过，而且踩得很典型。所以这篇不讲”怎么升级”，讲一件更容易被忽略的事：主程升上去了，不代表升级就完成了。
我会把这次的真实排查过程原样写下来——包括我一开始判断错的方向，因为那几个错误方向，才是大多数人会卡住的地方。
一、现象：版本显示对了，对话却炸了
背景很简单。我想把个人环境里的 OpenClaw 从 5.22 升到一个稳一点的版本。出于稳定考虑，我没追最新 beta，特意选了 2026.5.26。
升完，命令行里主程版本是正常的：
OpenClaw 2026.5.26 (10ad3aa)
看着是成了。但真发一条消息，立刻蹦出这个报错：
[plugins] codex failed to load from
/Users/skillmelody/.openclaw/npm/node_modules/@openclaw/codex/dist/index.js:
Error: Cannot find module ‘/usr/local/lib/node_modules/openclaw/dist/plugin-sdk/root-alias.cjs/exec-approvals-runtime’
第一眼看，这报错”长得像”三件事：依赖装漏了、Node 版本不对、或者插件缓存没清干净。这三个方向，后来证明全是错的。
二、排查：两步定位，问题不在 Node
与其乱试，不如先把两个版本号摆到一起看。
第一步：确认主程版本
openclaw –version
npm ls -g openclaw –depth=0
输出确认主程没问题：
openclaw@2026.5.26
第二步：确认 Codex 插件版本
关键的一步——去查 ~/.openclaw/npm 里那个出问题的插件，到底是什么版本：
node -p “require(process.env.HOME+’/.openclaw/npm/node_modules/@openclaw/codex/package.json’).version”
node -p “require(‘/usr/local/lib/node_modules/openclaw/package.json’).version”
结果一摆出来，问题就全清楚了：
# 主程 Host：2026.5.26
# Codex 插件：2026.6.5
插件的版本，比主程还要新。
主程被我切到了 5.26，但 Codex 插件不知什么时候被自动更新到了 6.5。两者不在同一条版本线上——这就是根因。
三、根因：为什么”插件比主程新”反而更危险
打个比方。主程是房子，Codex 这类官方插件是装在房子里的电器，它要插主程预留的那些插座（OpenClaw 的 Plugin SDK / Runtime 接口）。
6.5 的插件，是按”6.5 那栋房子”造的，它要去插一个叫 root-alias.cjs/exec-approvals-runtime 的新插座。可我这栋房子是 5.26，根本没装这个插座。于是插件一上电就报”找不到模块”，直接崩在加载阶段。
💡 一个反直觉但很重要的点
很多人下意识觉得”插件旧了才会出问题”。恰恰相反：插件比主程旧，通常还能降级、还能告警、还能凑合跑；插件比主程新，它会去引用只有新主程才有的接口，结果是硬崩在启动那一刻。方向不一样，危险程度也不一样。
这件事最迷惑的地方在于，所有”主程视角”的检查全是绿的：
openclaw –version → 对的
npm global 里的 openclaw → 对的
~/.openclaw/npm 里的插件 → 不在同一条版本线上
根子上的成因也很朴素：我 pin 死了主程版本，却没有 pin 住官方插件。插件没锁版本，npm 一动，它就自己飘上去了。
所以”只看 openclaw --version“会误判，因为它根本抓不到 ~/.openclaw/npm 里插件的状态。
四、修复：两条路，我选了往回收敛
方案一（我采用的）：把插件降回和主程同版本
先停掉 Gateway：
openclaw gateway stop 2>/dev/null || true
pkill -f “openclaw.*gateway” 2>/dev/null || true
如果端口还被占着，先查、再杀（端口号以你本机为准）：
lsof -nP -iTCP:18789 -sTCP:LISTEN
# 看到占用进程后（示例 pid 35009）：
kill 35009 # 还在就 kill -9 35009
进插件目录，把 Codex 装回对应版本（--save-exact 锁死，别让它再飘）：
cd ~/.openclaw/npm
npm uninstall @openclaw/codex
npm install @openclaw/codex@2026.5.26 –save-exact
清掉插件 runtime 缓存：
rm -rf ~/.openclaw/plugin-runtime-deps
rm -rf ~/.openclaw/npm/node_modules/.cache
再核一遍两个版本，目标是两行都变成 5.26，然后修复并启动：
openclaw doctor –fix
openclaw gateway start
方案二（备选）：把主程升到插件那个版本
反过来也行——让主程追上插件，升到 6.5：
npm uninstall -g openclaw
npm install -g openclaw@2026.6.5
但我没选这条，原因值得说一句
我当初特意选 5.26 是为了稳。如果因为一个”自动更新上去的插件”，就反过来把主程也拽到更高版本，等于让一次意外的版本漂移，替我重新决定了整个环境的版本——这跟我升级的初衷正好相反。升到更高版本还可能引入新的配置迁移和兼容性变化，风险更高。所以方向上，我宁可把插件降回来，也不让插件反向决定主程。
五、邪修一把梭（和它的代价）
如果你只想最快恢复，最省事的”邪修”其实就一行——直接把插件钉回主程版本：
npm –prefix ~/.openclaw/npm install @openclaw/codex@$(node -p “require(‘/usr/local/lib/node_modules/openclaw/package.json’).version”) –save-exact
它读出当前主程版本，再把 Codex 锁到同一版本，一句搞定。但邪修的代价是：你没搞清是哪一层坏的。这次能一把梭，是因为我已经定位到”插件版本错配”。如果你没定位就一把梭，下次插件再飘、或者坏的根本是另一层，你还得从头再来。邪修能用，但别拿它代替”先分层定位”。
插件这层修好后，我对话又撞上了第二层——一个 No API key found 的授权报错。那是另一层问题，和插件版本不是一回事，我在 B-24 里专门写过排查路径，这篇不重复。这里只强调一句：插件加载、授权缺失、记忆超时，要分层看，别看到对话失败就重装 OpenClaw。
六、升级后我现在固定跑的探针
以后指定版本升级完，我会固定跑这几组检查（命令以你本机当前版本的 help 为准）：
# 1) 主程是不是目标版本
openclaw –version
# 2) 跑着的网关是不是新版本进程（不是只看 status）
lsof -nP -iTCP:18789 -sTCP:LISTEN
ps aux | grep -i openclaw | grep -v grep
# 3) 关键插件版本和主程对不对得上
npm –prefix ~/.openclaw/npm ls @openclaw/codex –depth=0
七、把这次教训反哺进升级技能
我手上有一个开源的升级技能（openclaw-verified-upgrade），之前还用花叔的达尔文.skill 评过分、做过加固。它本身写得很扎实，最强的一句是”CLI 版本 ≠ 网关运行版本“——这正是本地 Agent 最容易掉的坑。
但这次事故，恰好打在它的盲区上：它对”版本”的理解，只有主程那一根轴（CLI、服务、进程、网关运行时）。它默认主程那条线收敛了，就收敛了。可 OpenClaw 还有第二根独立的版本轴——外装在 ~/.openclaw/npm 里的官方插件，它会随 npm 操作自己漂移。两根轴会各飘各的。
所以我给技能补的，不是”更多说明”，而是把心智模型补对：
· 升级完成的定义，从”主程收敛”改成”主程 + 插件双轴都收敛”；
· 盘点插件时，不只看名字，还要看版本、来源、有没有锁定；
· 版本错配有方向——插件高于主程，宁可往回降，不要被它反向拽着升主程。
（技能层面更细的改法，我整理成了一份单独的改进清单，这里不展开。）
OpenClaw 升级，不是一次”版本号更新”，
是一次”状态收敛”。
主程收敛、网关收敛、插件收敛、授权收敛、关键链路收敛——五个都过了，才算升完。
💬 你升级 OpenClaw 之后，有没有专门看过那些 @官方插件的版本？
有没有遇到过”主程对了、对话却炸了”的情况？评论区聊聊。
夜猫子弦月 | 白天写代码，晚上写文章，偶尔弹古琴
MeowClaw Lab 出品
#OpenClaw #OpenClaw升级 #插件版本错配 #本地Agent #踩坑实录 #个人开发者