Hermes QQ 机器人在聊天中响应指令和人格对话

这两天我把 Hermes 接到 QQ 上，顺手把漫画下载插件、模型切换、长期记忆和人格指令都跑了一遍。最后的状态不是“能回消息”这么简单，而是一个可以在 QQ 聊天窗口里接命令、调用插件、保持固定说话风格、记住一部分本地配置的小机器人。

腾讯官方 QQ 机器人的基本思路很清楚：先在 QQ 开放平台创建机器人应用，配置 AppID、Token、Secret 这类身份信息；再按需要申请或打开消息事件权限；开发侧通过网关长连接接收事件，再调用发送消息、发送文件等接口把结果回到 QQ。Hermes 做的事情，就是把这一层网关和本地 Agent/插件系统接起来。

先把 QQBot 当成一个网关

我自己的经验是，不要一开始就纠结人格、记忆和复杂插件。先确认三件事：

  1. QQ 开放平台里机器人应用已经创建，沙箱或正式环境能收到消息事件。
  2. Hermes 的 QQBot 网关进程确实连上了，而不是只看到一个旧状态。
  3. gateway.log 里能看到真实的 C2C message 或群消息事件。

前面排查时我发现，静态配置看起来正确并不等于机器人真的在线。更可靠的判断是同时看 gateway_state.json、网关日志和 QQ 里实际发出的消息。Hermes 的 CLI 状态命令在 Windows 沙箱里有时会出现启动 Python 子进程失败之类的噪声，所以最终还是日志和真实消息最可信。

Hermes 里的配置层

Hermes 这类本地 Agent 壳一般有几层配置：

  • 模型提供商：比如我这次用过 Micu、火山引擎 Coding Plan，以及几个自定义 OpenAI-compatible 入口。
  • 默认模型：决定普通聊天和插件调用时走哪个模型。
  • QQBot 身份：保存 QQ 开放平台分配的机器人身份、令牌和网关参数。
  • 插件目录：决定 /jm、/jmfind、/jmzip 这类命令是否能被发现。
  • 指令和记忆：决定机器人“是谁”、如何称呼用户、哪些事实需要长期保留。

这里最容易踩坑的是模型配置和运行态不同步。我之前把火山引擎模型列表修好后，如果不重启相关 Hermes worker，旧会话仍可能继续拿旧模型 ID 或旧 provider 去请求。我的做法是：改 D:\Hermes\config.yaml 后马上做配置加载检查，再重启桌面端和网关，然后从日志里确认新的 base URL 和模型名真的生效。

插件命令要能独立验证

截图里的 /jmhelp、/jmfind、/jm、/jmzip 就是一个很好的分界线。机器人能聊天，只说明 LLM 链路通了；插件命令能跑通，才说明 QQ 事件、Hermes 调度、插件依赖、文件发送全部串起来了。

这次 jm-comic 插件最典型的问题是：下载图片成功，但 PDF 没生成。最后不是 QQBot 发送坏了，也不是漫画下载坏了，而是 PDF 路径缺少 img2pdf 依赖。修好依赖并写进 manifest.toml 后，再看 send_document 路径是否触发，才算验证完成。

所以我现在会把 QQ 机器人插件分成四步验收：

  1. 插件被 Hermes 启动时发现。
  2. QQ 消息能触发插件命令。
  3. 插件在本地生成预期产物。
  4. 产物通过 QQBot 发回聊天窗口。

少任何一步，表面上都可能只是“机器人没反应”，但真实原因完全不同。

记忆不是越多越好

给 QQ 机器人加记忆时，我更倾向于只保存三类内容：

  • 身份记忆：它叫什么、和我是什么关系、说话边界是什么。
  • 工具记忆：哪些命令可用、哪些路径是本机固定路径、哪些插件需要特殊依赖。
  • 偏好记忆：我喜欢怎样的回答风格、要不要直接执行、遇到失败先查哪个日志。

不要把所有聊天都塞进长期记忆。QQ 场景很容易产生大量闲聊，如果全部长期保存，后面机器人会越来越像在复读上下文垃圾。真正有用的记忆应该短、稳定、可验证，比如“真实 QQ 入站消息看 D:\Hermes\logs\gateway.log 里的 C2C message”，这种下次排障真的能省时间。

指令决定它像不像“我的机器人”

指令层我会分成系统指令和人格指令。

系统指令负责边界：不要泄露密钥；不要假装已经执行没有执行的本地操作；插件失败时给出具体失败点；涉及文件发送、下载、外部请求时说明状态。

人格指令负责语气：比如截图里这个 neko 人设，就是把普通问答变成一个固定性格的聊天对象。这里要注意，人格可以可爱，但工具反馈不能含糊。一个能长期用的机器人，最好做到“聊天有性格，办事有日志”。

我最后保留的原则是：人格只影响表达方式，不影响事实判断。它可以撒娇，但不能因为撒娇就把失败说成成功。

一个可复用的搭建顺序

如果重新从零搭，我会按这个顺序走：

  1. 在 QQ 开放平台创建机器人，拿到应用身份信息，打开需要的消息事件权限。
  2. 在 Hermes 写入 QQBot 配置，只先跑最小网关，不接复杂插件。
  3. 用真实 QQ 消息验证日志里出现入站事件。
  4. 接入一个最简单的回复逻辑，确认消息能发回。
  5. 再接 LLM provider，固定默认模型，并验证不会走错旧 provider。
  6. 加插件目录，先跑帮助命令，再跑会生成文件的命令。
  7. 写入短记忆和人格指令，重启后用真实对话确认生效。
  8. 最后再考虑自动启动、桌面快捷方式和长期守护。

这套流程看起来慢，但比一次性把模型、QQ、插件、人格、记忆全堆上去好排障得多。QQ 机器人真正麻烦的地方不是代码，而是每一层都可能“看起来配置好了”，但只有真实消息、真实日志、真实文件发送能证明它活着。