使用Hermes 排查OpenClaw 从 5.12 升级到 6.10 的故障

半年前用 OpenClaw 搭了一套多 Agent 协作系统，跑在 Ubuntu 虚拟机里，接飞书做消息通道，算是半个生产环境。最近抽空从 2026.5.12 升到 2026.6.10，升级完满怀期待地测试，结果发现「龙虾」不吭声了——飞书里发消息过去，已读不回。
打开openclaw ，报了一些故障

翻配置文件、查网络连接、看 API Key，折腾了半天，最终发现问题不在配置，不在网络，也不在 API Key，而是升级中的一个陷阱：核心版本升了，插件版本没跟着升。

这篇文章复盘了完整的排查和修复过程，包括诊断命令、数据库查询、修复步骤，以及 OpenClaw 和 Hermes 两个网关的架构关系。

老规矩先看效果

升级前，给飞书里的「龙虾」发消息，WebSocket 连接正常，日志能看到received message，但就是不回复。查数据库，入站事件表的 count 是 0——消息到了 WebSocket 层，但没进入处理管线。

升级修复后，发什么回什么，一切正常。

整个修复涉及四个层面，逐一排查定位，下面展开来讲。

系统环境交代

这台 Ubuntu 24.04 虚拟机上跑着两套 AI 网关系统。一套是 Hermes Agent，Python 后端，系统级服务，负责日常的飞书对话。另一套是 OpenClaw，Node.js 后端，手动启动，跑着五个 Agent 的多角色协作体系——龙虾（主 Agent）、投资专家、财务总监、技术总监、市场总监。

两套系统共用~/.hermes/目录作为 HOME 路径，但各自的配置、状态库、插件是独立的。

关键点：两套系统用的飞书 App ID 不同，是两条完全独立的 WebSocket 连接。不存在「一个端口被抢了另一个连不上」的情况。

升级方式很简单：npm update -g openclaw，把核心从 2026.5.12 拉到了 2026.6.10。启动 gateway 就开始报 warning。

第一个警告：deepseek 插件缺失

升级后首次启动openclaw gateway --port 18789 --verbose，终端出现 Config warnings：

plugins.entries.deepseek: plugin not installed: deepseek

原因是在 6.10 版本里，deepseek provider 从内置变成了外部插件，需要单独安装。配置文件里还写着plugins.entries.deepseek.enabled: true，但实际的 npm 包不存在。

另外还有 Doctor warnings：Left plugin install index in place because shared SQLite state has conflicting plugin install metadata for: feishu。这是 OpenClaw 启动时读~/.hermes/state.db（Hermes 的会话存档）做迁移检查，发现 Hermes 内置的 feishu 和 OpenClaw npm 安装的 feishu 元数据冲突，选择保留不动。不影响任何功能，先放一边。

执行openclaw plugins install @openclaw/deepseek-provider。npm 安装@openclaw/deepseek-provider@2026.6.10到~/.openclaw/npm/projects/。重启 gateway，deepseek 警告消失。但龙虾还是不回消息。

第二个警告：API Key 没存进去

查openclaw.json，auth.profiles里定义了deepseek:default，模式api_key。框架有了，但去查 agent 工作区的auth-profiles.json——profiles字段是空的。

这里有个容易忽略的点：openclaw.json里的auth.profiles只定义元数据（provider 类型、auth 模式），真正的 API Key 需要存在 agent 的凭证存储里。如果只改了配置文件没存 Key，agent 调 DeepSeek API 时会因为没有凭证而静默失败——SDK 吞掉了这个异常，日志里看不到任何 API 调用错误。

通过管道把 Hermes 那边已在用的 Key 存进去：

openclaw models auth paste-api-key --provider deepseek

执行后openclaw models auth list显示deepseek:default [deepseek/api_key]。重启，龙虾还是没反应。

深入数据库：发现了真正的根因

前两步修的都是「启动时能看到的」问题，但龙虾不响应的根因还没找到。开始做数据层诊断。

查 OpenClaw 的 SQLite 状态库（~/.openclaw/state/openclaw.sqlite），三个关键发现：

channel_ingress_events的 count 是 0。从启动到现在，一条入站事件都没收到。但 WebSocket 连接正常（openclaw channels status显示 main agent running），TCP 连接也在。

delivery_queue_entries里 17 条记录全部 failed。错误有两类：Feishu account "default" not configured和card table number over limit（飞书卡片表格数超限，错误码 11310）。时间戳都是 6 月 13 日的旧数据。

current_conversation_bindings是空的。没有任何飞书会话被绑定到 agent。

消息到了 WebSocket 但没进数据库——问题出在 WebSocket 和数据库之间的消息路由环节。

关键发现：feishu 插件版本不匹配

查~/.openclaw/npm/node_modules/@openclaw/feishu/package.json，version 字段是2026.5.12。

OpenClaw 核心 2026.6.10，feishu 插件 2026.5.12——差了将近一个月的版本。

这就是根因。npm update -g openclaw只升级了核心包，不会自动升级通过openclaw plugins install单独安装的外部插件。feishu 是外部 npm 包，有自己的版本管理，不在 bundled extensions 里。

新版核心的 channel adapter 接口变了，消息对象的解析方式也变了。旧版 feishu 插件收到 WebSocket 数据后还是用 5.12 的格式解析，传给核心后路由失败，消息被静默丢弃。

这也解释了日志的矛盾：received message是 feishu 插件自己的 WebSocket 层打的——它代表「WebSocket 收到了原始字节并解析成了消息对象」。但这个消息对象传给核心的 channel adapter 时因为格式不兼容被丢弃了，所以 channel_ingress_events 始终是 0。

执行升级：

openclaw plugins install @openclaw/feishu

install 命令检测到旧版，自动卸载~/.openclaw/npm/node_modules/@openclaw/feishu（5.12 路径），安装新版到~/.openclaw/npm/projects/。验证：feishu plugin: v2026.6.10，与核心版本一致。

模型切换

顺手把模型从 flash 切到 pro：

openclaw models set deepseek/deepseek-v4-pro

四步修复全部完成。重启 gateway，给龙虾发「你是什么模型」，秒回。

修复命令汇总

整个修复用了四条命令：

更新 deepseek 提供者插件，解决plugin not installed警告

openclaw plugins install @openclaw/deepseek-provider

将 DeepSeek API Key 存入 agent 凭证存储。Key 从 Hermes 的环境变量获取，通过管道输入

openclaw models auth paste-api-key --provider deepseek

升级 feishu 通道插件到与核心一致的版本，这是最关键的一步——新旧接口不兼容导致消息路由失败

openclaw plugins install @openclaw/feishu

切换默认模型到 Pro，flash 和 pro 可随时切换

openclaw models set deepseek/deepseek-v4-pro

每次切换模型或升级插件后需要重启 gateway。

SQLite 诊断速查

排查过程中用到的核心 SQL 查询，全是读操作，不改数据：

入站事件总量——这是最高优先级的诊断指标。如果是 0，问题一定在消息接收和路由环节

SELECT COUNT(*) FROM channel_ingress_events;

出站队列状态和失败原因——即使 agent 成功处理了消息，如果回复发不出去，问题就在这里

SELECT id, status, channel, account_id, last_error FROM delivery_queue_entries ORDER BY enqueued_at DESC LIMIT 10;

插件安装索引——查看所有插件的版本号和安装来源。升级后第一时间对比版本，不一致的就是重点怀疑对象

SELECT value_json FROM installed_plugin_index;

Agent 凭证状态——确认 API Key 正确存储，避免因为凭证缺失导致的静默失败

SELECT * FROM auth_profile_state;

一条COUNT(*) = 0的信息量远大于「日志里没有错误」——日志可能因为代码根本没执行到而保持安静，但数据库不会撒谎。

state.db 的那些事

排查过程中有一个持续出现的 warning：Left plugin install index in place because shared SQLite state has conflicting plugin install metadata for: feishu。

这个 state.db 是 Hermes 的会话存档，存了 103 个 session 和 6780 条消息，带 FTS 全文搜索索引，用于session_search功能。OpenClaw 启动时用它做迁移兼容检查，发现 Hermes 内置 feishu 和 OpenClaw npm feishu 的安装记录冲突，选择保留不动。

用lsof验证：OpenClaw 运行时根本不持有 state.db 的文件句柄。只在启动时读一次，读完就关。两个网关真正的关系是独立配置、独立数据库、独立飞书 App、独立插件。state.db 的共享只是历史遗留的目录结构，没有实际数据耦合，不影响功能。

为什么升级不自动更新插件

这是这次升级踩坑的核心教训。OpenClaw 6.x 做了重大的插件架构调整——provider 和 channel 拆分成了独立的外部包。

Bundled extensions（duckduckgo、searxng 等）在dist/extensions/下，随npm update -g openclaw自动更新。但通过openclaw plugins install单独安装的外部插件有自己独立的安装路径和版本管理。

这导致了一个隐蔽的不一致状态：核心 API 变了，但外部插件还停在旧版本，接口不兼容。轻则功能异常，重则静默失败——消息被丢弃，没有任何错误提示。

升级后的检查清单

基于这次经验，以后版本升级的检查流程：

升级核心后立即用openclaw plugins list对比所有外部插件的版本号，跟核心版本对齐

用openclaw models auth list确认 API Key 还在——某些升级可能重置 auth state

用openclaw doctor扫描所有 warning，逐条分析

SQL 查询 channel_ingress_events 和 delivery_queue_entries 确认消息收发正常

发一条测试消息验证端到端流程

关于飞书卡片消息的限制

delivery_queue 里那些 failed 消息还暴露了另一个细节：飞书 API 对卡片消息有严格的结构限制。卡片里的表格、按钮、图片数量都有上限。错误码 11310 表示 agent 生成的回复里表格超限了。

这是 AI agent 输出格式的一个常见问题：AI 喜欢用表格组织信息，但飞书卡片渲染引擎对表格数量有限制。新版 6.10 的 feishu 插件对卡片渲染做了优化，flatten 了一些嵌套结构，这也是升级插件后 delivery 成功率提高的附带收益。

网络层面的一点验证

排查中还做了网络验证。用ss -tnp看 OpenClaw 进程的 TCP 连接，确认它连到了飞书 WebSocket 服务器。飞书 WebSocket 域名是msg-frontier.feishu.cn，通过 DNS 解析到多个 CDN 边缘节点 IP，OpenClaw 同时维护着 4 到 5 条到这些节点的连接。连接数稳定，没有频繁断连重建——网络层健康，问题确定在应用层。

对其他 Agent 的影响

这次主要修了 main agent（龙虾），但 openclaw.json 里还有四个 agent。升级后 openclaw doctor 显示 cfo、cmo、cto 三个 agent 缺少 message 工具——它们能收消息、能调 LLM，但不能通过飞书发回复。修法是在每个 agent 配置里加 tools.allow 包含 message。暂时不用的可以先放，不影响龙虾正常使用。investor agent 没有这个 warning，配置跟 main 一样完整。

后续维护建议

升级前做状态快照：把 openclaw.json 和插件列表 dump 出来，升级后对比差异。定期查 delivery_queue 的 failed 趋势和 channel_ingress_events 的 count 变化——如果 count 突然变成 0，说明插件或连接出了问题。对于同时跑多套 agent 的场景，可以让 OpenClaw 使用独立的 HOME 目录，彻底消除 state.db 共享，但这个优化可以放到下次大版本升级一起做。

写在最后

排查花了几个小时，修复只用了四条命令。时间主要花在理解问题上——理解新版插件架构，理解消息为什么没进数据库，理解那些 SQLite 表代表什么状态。

工具越来越复杂，出问题时能给你最多信息的往往不是日志，而是安静躺在数据库里的数据。一条COUNT(*) = 0，比任何错误日志都更好地告诉你：消息从来没进来过。