二、整体架构：Hermes + QQ Bot 是怎么工作的？

先讲清楚架构，不然你只是“照着做”，不知道为什么。

1. 核心组件

Hermes QQ Bot 其实是三层结构：

QQ用户 → QQ官方Bot → Hermes Gateway → Hermes Agent → LLM

详细拆解：

1. QQ 官方 Bot API
   • 负责接收消息（WebSocket）
   • 发送消息（HTTP REST）
2. Hermes Messaging Gateway
   • Hermes 的“中间层”
   • 把 QQ 消息转成 Agent 可理解的输入
3. Hermes Agent
   • 处理逻辑、调用工具、记忆上下文
4. LLM（模型）
   • GPT / Claude / GLM / 本地模型等

2. 数据流

整个链路是这样的：

用户发消息 → QQ Gateway →
Hermes Gateway（解析） →
Hermes Agent（思考 + 工具调用） →
返回结果 →
QQ Bot API →
用户看到回复

3. Hermes 的关键优势

和普通 QQ Bot 最大区别：

三、官方能力解析（重点）

根据文档，QQ Bot Adapter 提供以下能力：

1. 消息能力

支持：

• 私聊（C2C）
• 群 @ 消息
• 频道消息（Guild）
• Direct Message

也就是说：可以做企业级客服 / 社群助手

2. 多媒体能力

Hermes 能处理：

• 图片
• 语音（自动转文字）
• 文件

语音识别流程：

1. QQ 自带 ASR（优先）
2. fallback 到外部 STT（如 Whisper）

3. 通信机制

• WebSocket（收消息）
• HTTP（发消息）

这点很关键：说明是实时通信，不是轮询

四、接入前准备

1. 注册 QQ Bot

去官方：https://q.qq.com

你需要：

• App ID
• App Secret
• 开启权限（intents）

必须开启：

• 私聊消息
• 群 @ 消息
• Guild 消息

2. 安装 Hermes

3. 安装依赖

（这是 QQ adapter 必需的）

五、核心接入步骤（重点）

Step 1：启动 Gateway 配置

选择：

QQ Bot

Step 2：填写配置

你会输入：

QQ_APP_ID=xxx
QQ_CLIENT_SECRET=xxx

或者手动写入：

Step 3：启动服务

Step 4：测试

在 QQ 里：

• 私聊机器人
• 群里 @机器人

如果正常，会直接回复

六、高级配置（真正拉开差距的地方）

基础接入只是开始，真正牛的是“调教 Hermes”。

1. config.yaml 配置

路径：

示例：

2. 权限控制

做白名单系统

3. 群控制

只允许指定群使用

4. 语音识别增强

默认：

• 腾讯 ASR

高级玩法：

接入 OpenAI Whisper

七、实战案例：做一个“QQ AI 助手”

这里给你一个真实可用场景

场景：社群运营助手

功能：

• 自动回复问题
• 总结聊天内容
• 定时推送

实现方式

1. 使用 Hermes cron

2. 使用技能（skills）

Hermes 会自动创建技能：

• FAQ回答
• 数据分析
• 自动回复

3. 群聊触发

用户：

@机器人 总结今天内容

Hermes：

自动分析历史上下文
输出总结

八、进阶玩法（核心价值）

1. 多平台统一

Hermes 支持：

• Telegram
• Discord
• QQ
• 微信（可扩展）

一个 Agent，多入口

2. Agent 自动工作

你可以让它：

• 自动写日报
• 自动爬数据
• 自动分析

3. 子 Agent

Hermes 支持：

• 多 Agent 并行
• 任务分解

这才是“真正 AI 助手”

九、常见问题（踩坑总结）

1. 机器人连不上

原因：

• App ID 错
• Secret 错

2. 收不到消息

检查：

• intents 是否开启
• 群是否 @ 机器人

3. 语音不识别

检查：

• 是否有 asr_refer_text
• STT API 是否配置

4. 只能沙盒用

没发布应用

十、架构升级建议（非常重要）

如果你想做“商业级”，建议：

1. 部署在服务器

推荐：

• VPS（$5/月就够）
• Docker

2. 使用 OpenRouter

优点：

• 多模型切换
• 成本低

3. 加一层 API

结构升级：QQ → Hermes → 你自己的API → LLM

控制成本 + 做缓存

十一、总结

一句话总结：

Hermes + QQ Bot = 一个真正能干活的 AI 员工

核心价值：

• 不是聊天机器人
• 是自动化执行系统

十二、未来扩展

你可以继续做：

• 接入微信（企业级）
• 接入飞书
• 做 SaaS 平台
• 做 AI 中台

最后一句（重点）

如果你只是接入 QQ：那只是“机器人”

如果你用好 Hermes：那是“数字员工”