QQ Bot 设置

通过官方 QQ Bot API (v2) 将 Hermes 连接到 QQ — 支持私聊（C2C）、群 @-mention、频道和直接消息，以及语音转录。

概述

QQ Bot 适配器使用 官方 QQ Bot API 实现：

• 通过与 QQ 网关的持久 WebSocket 连接接收消息
• 通过 REST API 发送文本和 markdown 回复
• 下载并处理图片、语音消息和文件附件
• 使用腾讯内置 ASR 或可配置的 STT 提供商转录语音消息

前置要求

1. QQ Bot 应用 — 在 q.qq.com 注册：

   • 创建新应用并记录你的 App ID 和 App Secret
   • 启用所需 intents：C2C 消息、群 @-消息、频道消息
   • 在沙盒模式下配置机器人进行测试，或发布用于生产

2. 依赖项 — 适配器需要 aiohttp 和 httpx：

   pip install aiohttp httpx

配置

交互式设置

hermes setup gateway

从平台列表中选择 QQ Bot 并按照提示操作。

手动配置

在 ~/.hermes/.env 中设置所需环境变量：

QQ_APP_ID=your-app-id
QQ_CLIENT_SECRET=your-app-secret

环境变量

变量	描述	默认值
QQ_APP_ID	QQ Bot App ID（必填）	—
QQ_CLIENT_SECRET	QQ Bot App Secret（必填）	—
QQ_HOME_CHANNEL	用于 cron/通知投递的 OpenID	—
QQ_HOME_CHANNEL_NAME	主频道显示名称	Home
QQ_ALLOWED_USERS	逗号分隔的用户 OpenID 用于 DM 访问	open（所有用户）
QQ_ALLOW_ALL_USERS	设置为 true 以允许所有 DM	false
QQ_MARKDOWN_SUPPORT	启用 QQ markdown（msg_type 2）	true
QQ_STT_API_KEY	语音转文本提供商的 API 密钥	—
QQ_STT_BASE_URL	STT 提供商 base URL	https://open.bigmodel.cn/api/coding/paas/v4
QQ_STT_MODEL	STT 模型名称	glm-asr

语音消息（STT）

语音转录分两个阶段工作：

1. QQ 内置 ASR（免费，始终优先尝试）— QQ 在语音消息附件中提供 asr_refer_text，使用腾讯自己的语音识别

2. 配置的 STT 提供商（备选）— 如果 QQ 的 ASR 未返回文本，适配器调用 OpenAI 兼容的 STT API：

   • 智谱/GLM (zai)：默认提供商，使用 glm-asr 模型
   • OpenAI Whisper：设置 QQ_STT_BASE_URL 和 QQ_STT_MODEL
   • 任何 OpenAI 兼容的 STT 端点

故障排除

机器人立即断开（快速断开）

这通常意味着：

• App ID / Secret 无效 — 在 q.qq.com 双重检查你的凭证
• 缺少权限 — 确保机器人已启用所需 intents
• 沙盒机器人 — 如果机器人在沙盒模式下，只能接收来自 QQ 沙盒测试频道的消息

语音消息未转录

1. 检查 QQ 的内置 asr_refer_text 是否在附件数据中
2. 如果使用自定义 STT 提供商，验证 QQ_STT_API_KEY 设置正确
3. 检查网关日志中的 STT 错误消息

消息未投递

• 验证机器人的 intents 在 q.qq.com 上已启用
• 如果 DM 访问受限，检查 QQ_ALLOWED_USERS
• 对于群消息，确保机器人被 @mention（群策略可能需要白名单）
• 检查 QQ_HOME_CHANNEL 用于 cron/通知投递

连接错误

• 确保已安装 aiohttp 和 httpx：pip install aiohttp httpx
• 检查到 api.sgroup.qq.com 和 WebSocket 网关的网络连接
• 查看网关日志以获取详细错误消息和重连行为