QQ Bot
通过 官方 QQ Bot API（v2） 将 Hermes 接入 QQ，支持私聊（C2C）、群 @ 提及、频道（guild）以及 direct message，并支持语音转写。
概览
QQ Bot 适配器基于 官方 QQ Bot API 提供以下能力：
- 通过持久化 WebSocket 连接到 QQ Gateway 接收消息
- 通过 REST API 发送文本与 Markdown 回复
- 下载并处理图片、语音消息和文件附件
- 使用腾讯内建 ASR 或可配置的 STT 大模型提供商（provider）转写语音消息
前提条件
- QQ Bot Application：前往 q.qq.com 注册
- 依赖：该适配器需要
aiohttp和httpx
pip install aiohttp httpx
配置
交互式设置
hermes gateway setup
在平台列表中选择 QQ Bot，按提示完成配置。
手动配置
QQ_APP_ID=your-app-id
QQ_CLIENT_SECRET=your-app-secret
环境变量
| Variable | Description | Default |
|---|---|---|
QQ_APP_ID | QQ Bot App ID（必填） | — |
QQ_CLIENT_SECRET | QQ Bot App Secret（必填） | — |
QQBOT_HOME_CHANNEL | 用于 cron/通知投递的 OpenID | — |
QQBOT_HOME_CHANNEL_NAME | Home channel 的显示名 | Home |
QQ_ALLOWED_USERS | 允许私聊访问的用户 OpenID，逗号分隔 | open（所有用户） |
QQ_ALLOW_ALL_USERS | 设为 true 时允许所有私聊用户 | false |
QQ_SANDBOX | 将请求发送到 QQ sandbox 网关，便于开发测试 | false |
QQ_STT_API_KEY | 语音转文本大模型提供商（provider）的 API key | — |
QQ_STT_BASE_URL | STT 大模型提供商（provider）的基础 URL | https://open.bigmodel.cn/api/coding/paas/v4 |
QQ_STT_MODEL | STT 模型名 | glm-asr |
语音消息（STT）
语音转写分两层处理：
- QQ 内建 ASR：优先尝试
asr_refer_text - 配置的 STT 大模型提供商（provider）：当 QQ 未返回文本时作为兜底
故障排除
- 一连上就断开：检查 App ID / Secret、intents 和 sandbox 设置
- 语音未转写：检查
QQ_STT_API_KEY和 gateway 日志 - 消息未送达：检查 intents、
QQ_ALLOWED_USERS、群 @ 提及以及QQBOT_HOME_CHANNEL