QQ 机器人

通过官方 QQ 机器人 API（v2） 将 Hermes 连接到 QQ —— 支持私聊（C2C）、群组 @提及、频道以及带语音转录的直接消息。

概述

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

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

前置条件

QQ 机器人应用 —— 在 q.qq.com 注册：
- 创建新应用，记录您的 App ID 和 App Secret
- 启用所需意图（Intent）：C2C 消息、群组 @消息、频道消息
- 在沙盒模式下配置机器人进行测试，或发布到生产环境
依赖项 —— 适配器需要 aiohttp 和 httpx：
```
pip install aiohttp httpx
```

配置

交互式配置

hermes gateway setup

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

手动配置

在 ~/.hermes/.env 中设置必要的环境变量：

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

环境变量

变量	说明	默认值
`QQ_APP_ID`	QQ 机器人 App ID（必填）	—
`QQ_CLIENT_SECRET`	QQ 机器人 App Secret（必填）	—
`QQBOT_HOME_CHANNEL`	定时任务/通知投递的 OpenID	—
`QQBOT_HOME_CHANNEL_NAME`	主频道显示名称	`Home`
`QQ_ALLOWED_USERS`	允许私聊的用户 OpenID，逗号分隔	开放（所有用户）
`QQ_GROUP_ALLOWED_USERS`	允许的群组 OpenID，逗号分隔	—
`QQ_ALLOW_ALL_USERS`	设为 `true` 允许所有私聊	`false`
`QQ_PORTAL_HOST`	覆盖 QQ 门户主机（沙盒路由设为 `sandbox.q.qq.com`）	`q.qq.com`
`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       # 启用 QQ markdown（msg_type 2），仅支持配置文件，无对应环境变量
      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) 等
        baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4"
        apiKey: "your-stt-key"
        model: "glm-asr"

语音消息（STT）

语音转录分两个阶段进行：

QQ 内置 ASR（免费，始终优先尝试）—— QQ 在语音消息附件中提供 asr_refer_text，使用腾讯自有语音识别
已配置的 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 仔细检查您的凭据
缺少权限 —— 确保机器人已启用所需意图
仅限沙盒的机器人 —— 如果机器人处于沙盒模式，只能接收来自 QQ 沙盒测试频道的消息

语音消息未转录

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

消息未投递

在 q.qq.com 验证机器人的意图是否已启用
如果私聊访问受限，检查 QQ_ALLOWED_USERS
对于群组消息，确保机器人被 @提及（群组策略可能需要加入允许列表）
检查定时任务/通知投递的 QQBOT_HOME_CHANNEL

连接错误

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

概述​

前置条件​

配置​

交互式配置​

手动配置​

环境变量​

高级配置​

语音消息（STT）​

故障排查​

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

语音消息未转录​

消息未投递​

连接错误​

概述