Logo

菜单

Administrator
发布于 2026-05-04 / 2 阅读
0

OpenClaw 更新后 QQ Bot 失联：一次插件打包缺失的排查

#openclaw#问题解决#docker#UNRAID

5月3日下午，我照例更新了 OpenClaw 到 v2026.5.2，然后 QQ Bot 就没动静了。第二天更新到 v2026.5.3，情况依旧。这篇文章记录整个排查过程。

谁杀了我的 QQ Bot

起因很简单——更新完版本，QQ Bot 不回消息了。跑 openclaw status​，Channels 表一片空白，连个「已禁用」的字样都没有，就是空的。

第一反应是配置丢了。去 openclaw.json​ 看，channels.qqbot​ 字段完好，enabled: true​，appId​ 和 clientSecret​ 都在。去看 QQ Bot 的 session 文件，最后连接时间停在 5月3日 13:46，lastSeq​ 只有 1——说明连是连上了，但第一秒就断了。

时间线上有个可疑点：openclaw.json​ 的 lastTouchedAt​ 是 5月3日 13:58，刚好在 session 断连后 12 分钟。很像是 config 被写入触发了某个 reload，然后连接就没了。

再回想一下，5月3日早上 7 点我还在 QQ 上收到了记忆维护的定时推送结果。所以上午是一切正常的，问题出在下午更新 v2026.5.2 之后。v2026.5.3 也修不了，说明是两个版本共有的 bug。

顺着代码往下追

OpenClaw 的频道插件加载链路不短。从 startChannels()​ 出发，遍历 listChannelPlugins()​，对每个插件调用 startChannel()​。QQ Bot 在 getChannelPlugin("qqbot")​ 这一步分两条路：

  1. Loaded 注册表——已安装的外部插件，比如 plugin-runtime-deps 里的

  2. Bundled 内置——Docker 镜像自带的，在 /app/dist/extensions/​ 下面

Loaded 优先，Bundled 兜底。这解释了 v2026.5.2 的一个诡异现象：刚重启时 QQ Bot 是能用的（从旧 plugin-runtime-deps 里加载的），但一旦 config 被写入触发 reload，loaded 注册表清空重建，旧插件没注册回来，就 fallback 到 bundled——而 bundled 是个空壳。

怎么个空壳法？我对比了几个频道插件的 dist 目录：

# Telegram（正常）
/app/dist/extensions/telegram/
  index.js ✅
  channel-plugin-api.js ✅
  ... 共 20+ JS 文件

# QQ Bot（异常）
/app/dist/extensions/qqbot/
  openclaw.plugin.json  ← 只有元数据
  package.json          ← 只有包描述
  skills/               ← 空目录
  零个 JS 文件

入口文件 index.js​ 不存在，所有编译产物全部缺失。TypeScript 源码倒是在 /app/extensions/qqbot/src/​ 里完好无损，但 Docker 镜像里没有 TypeScript 编译器，运行时的 jiti 编译也因为模块路径解析问题失败了——失败后只打了一行 warn 日志就静默跳过，连个错都不报。

验证——对比旧版

去 plugin-runtime-deps​ 里翻旧版（v2026.4.29）：

~/.openclaw/plugin-runtime-deps/openclaw-2026.4.29-*/dist/extensions/qqbot/
  index.js ✅
  api.js ✅
  gateway-njL1PuDD.js ✅
  channel-Ck7cJfVO.js ✅
  ... 共 22 个 JS 文件

完整的一套编译产物，在旧版里一直正常工作。再看 compat 字段：pluginApi: ">=2026.4.27"​，当前 gateway 是 v2026.5.3，兼容没问题。核心依赖 @tencent-connect/qqbot-connector​ v1.1.0 在 gateway 的 node_modules 里也有。

也就是说，旧版的编译 JS 直接拿到新版网关用是可行的——问题纯粹是 Docker 镜像打包时漏掉了。

Workaround

把旧版文件复制过去：

# 备份
cp -r /app/dist/extensions/qqbot /app/dist/extensions/qqbot.bak

# 复制旧版
cp ~/.openclaw/plugin-runtime-deps/openclaw-2026.4.29-*/dist/extensions/qqbot/*.js \
   /app/dist/extensions/qqbot/

然后重启容器，QQ Bot 恢复正常。

为什么出这个 bug

只能推测是构建脚本的问题。QQ Bot 在 package.json​ 里标记了 "compat.pluginApi": ">=2026.5.3"​，也许 v2026.5.2 的 CI 在构建时认为 QQ Bot 插件不兼容就跳过了。但结果是两个版本的 Docker 镜像都没把 QQ Bot 的编译产物打进去。

这篇文章写完时，我已经把旧版文件临时补上去了。等到 OpenClaw 官方修复打包问题，记得清理掉这些手补的 JS 文件，免得被新版本覆盖后出现残留。

不止我一个

查了下 GitHub，果然不是我一个人踩坑。

v2026.5.3-1 的 npm 包有人报了 #77293，install.runtime-*.js​ 缺失导致 qqbot 插件无法更新，同时 plugin API 版本号对比也有 bug（把 2026.5.3-1​ 当 prerelease 拒绝掉了，而实际上它应该是 stable correction release）。ClawSweeper bot 确认了版本比较的问题在修。

另外 v2026.5.2 还有两个 QQ Bot 相关的 regression：77309（短回复不写 session 历史）、77306（消息重复发送），都是更新到 v2026.5.2 后出现的。

翻了下历史，这种版本更新导致的打包/依赖缺失不是第一次了——71730、70096、61686 都是同类问题。

留一个教训

排查这类「静默失败」的问题，记住两条线索：

  1. 对比法——拿一个正常工作的同类东西，逐项对比。我这次翻的是 Telegram 的 dist 目录，一眼就看出 QQ Bot 少了什么

  2. 往前翻——配置出问题时，不仅要看当前状态，还要看 lastTouchedAt​、lastConnectedAt​ 这些时间戳，把时间线拼出来

再好的工具也会出 bug，关键是快速定位和有效 workaround。这次花了一个小时从追踪代码到验证修复，如果没有旧版编译文件兜底，就只能干等官方更新了。

在UNRAID上部署RPlay直播...