QQ Bot

通过 官方 QQ Bot API (v2) 将 Hermes 与 QQ 连接 — 支持私聊（C2C）、群组 @ 提及、频道消息以及直接消息，并支持语音转写功能。

概述

QQ Bot 适配器使用官方 QQ Bot API 实现以下功能：

通过持久的 WebSocket 连接接收来自 QQ 网关的消息
通过 REST API 发送文本和 Markdown 回复
下载并处理图片、语音消息及文件附件
使用腾讯内置的 ASR 或可配置的 STT 服务对语音消息进行转写

前置条件

QQ Bot 应用 — 在 q.qq.com 上注册：
- 创建新应用，记下你的 App ID 和 App Secret
- 启用所需权限：私聊消息、群组 @ 消息、频道消息
- 测试阶段请在沙箱模式下配置，生产环境则需发布
依赖项 — 该适配器需要 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`	用于定时任务/通知投递的 OpenID	—
`QQ_HOME_CHANNEL_NAME`	主频道显示名称	`Home`
`QQ_ALLOWED_USERS`	逗号分隔的用户 OpenID 列表，用于允许私聊访问	open（所有用户）
`QQ_ALLOW_ALL_USERS`	设置为 `true` 以允许所有私聊	`false`
`QQ_MARKDOWN_SUPPORT`	启用 QQ Markdown（msg_type 2）	`true`
`QQ_STT_API_KEY`	语音转文字服务提供商的 API 密钥	—
`QQ_STT_BASE_URL`	STT 服务提供商的基础 URL	`https://open.bigmodel.cn/api/coding/paas/v4``
`QQ_STT_MODEL`	STT 模型名称	`glm-asr`

高级配置

如需更精细控制，请在 ~/.hermes/config.yaml 中添加平台相关设置：

platforms:
  qq:
    enabled: true
    extra:
      app_id: "your-app-id"
      client_secret: "your-secret"
      markdown_support: true
      dm_policy: "open"          # open | allowlist | disabled
      allow_from:
        - "user_openid_1"
      group_policy: "open"       # open | allowlist | disabled
      group_allow_from:
        - "group_openid_1"
      stt:
        provider: "zai"          # zai (GLM-ASR), openai (Whisper), etc.
        baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4"
        apiKey: "your-stt-key"
        model: "glm-asr"

语音消息（STT）

语音转写分为两个阶段：

QQ 内置 ASR（免费，优先尝试）—— 语音消息附件中包含腾讯自有的语音识别能力，会自动调用
配置的 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 沙箱测试频道的消息

语音消息未被转写

检查语音消息附件中是否包含 QQ 内置的 asr_refer_text
若使用自定义 STT 提供商，请确认 QQ_STT_API_KEY 配置正确
查看网关日志中的 STT 错误信息

消息未送达

确认机器人在 q.qq.com 上已启用相应 意图（intents）
检查 QQ_ALLOWED_USERS 是否限制了私聊访问
对于群组消息，请确保机器人已被 @ 提及（部分群组策略要求白名单）
检查 QQ_HOME_CHANNEL 是否影响定时任务或通知投递

连接错误

确保已安装 aiohttp 和 httpx：pip install aiohttp httpx
检查网络连通性是否可达 api.sgroup.qq.com 及 WebSocket 网关
查阅网关日志以获取详细错误信息及重连行为记录

概述​

前置条件​

配置方式​

交互式设置​

手动配置​

环境变量​

高级配置​

语音消息（STT）​

故障排查​

机器人立即断开连接（快速断连）​

语音消息未被转写​

消息未送达​

连接错误​

概述