feat: add QQ Bot platform adapter (Official API v2)

Add full QQ Bot integration via the Official QQ Bot API (v2): - WebSocket gateway for inbound events (C2C, group, guild, DM) - REST API for outbound text/markdown/media messages - Voice transcription (Tencent ASR + configurable STT provider) - Attachment processing (images, voice, files) - User authorization (allowlist + allow-all + DM pairing) Integration points: - gateway: Platform.QQ enum, adapter factory, allowlist maps - CLI: setup wizard, gateway config, status display, tools config - tools: send_message cross-platform routing, toolsets - cron: delivery platform support - docs: QQ Bot setup guide
2026-04-25 00:51:20 +00:00 · 2026-04-13 21:56:38 +08:00 · 2026-04-13 21:56:38 +08:00 · 87bfc28e70
commit 87bfc28e70
parent eb44abd6b1
18 changed files with 2679 additions and 5 deletions
--- a/website/docs/user-guide/messaging/index.md
+++ b/website/docs/user-guide/messaging/index.md
@ -6,7 +6,7 @@ description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal,

 # Messaging Gateway

-Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles (iMessage), or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.
+Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles (iMessage), QQ, or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.

 For the full voice feature set — including CLI microphone mode, spoken replies in messaging, and Discord voice-channel conversations — see [Voice Mode](/docs/user-guide/features/voice-mode) and [Use Voice Mode with Hermes](/docs/guides/use-voice-mode-with-hermes).

@ -30,6 +30,7 @@ For the full voice feature set — including CLI microphone mode, spoken replies
 | WeCom Callback | — | — | — | — | — | — | — |
 | Weixin | ✅ | ✅ | ✅ | — | — | ✅ | ✅ |
 | BlueBubbles | — | ✅ | ✅ | — | ✅ | ✅ | — |
+| QQ | ✅ | ✅ | ✅ | — | — | — | — |

 **Voice** = TTS audio replies and/or voice message transcription. **Images** = send/receive images. **Files** = send/receive file attachments. **Threads** = threaded conversations. **Reactions** = emoji reactions on messages. **Typing** = typing indicator while processing. **Streaming** = progressive message updates via editing.

@ -55,6 +56,7 @@ flowchart TB
    wcb[WeCom Callback]
    wx[Weixin]
    bb[BlueBubbles]
+    qq[QQ]
            api["API Server<br/>(OpenAI-compatible)"]
            wh[Webhooks]
        end
@ -369,6 +371,7 @@ Each platform has its own toolset:
 | WeCom Callback | `hermes-wecom-callback` | Full tools including terminal |
 | Weixin | `hermes-weixin` | Full tools including terminal |
 | BlueBubbles | `hermes-bluebubbles` | Full tools including terminal |
+| QQ | `hermes-qq` | Full tools including terminal |
 | API Server | `hermes` (default) | Full tools including terminal |
 | Webhooks | `hermes-webhook` | Full tools including terminal |

@ -390,5 +393,6 @@ Each platform has its own toolset:
 - [WeCom Callback Setup](wecom-callback.md)
 - [Weixin Setup (WeChat)](weixin.md)
 - [BlueBubbles Setup (iMessage)](bluebubbles.md)
+- [QQ Bot Setup](qq.md)
 - [Open WebUI + API Server](open-webui.md)
 - [Webhooks](webhooks.md)
--- a/website/docs/user-guide/messaging/qq.md
+++ b/website/docs/user-guide/messaging/qq.md
@ -0,0 +1,122 @@
+# QQ Bot
+
+Connect Hermes to QQ via the **Official QQ Bot API (v2)** — supporting private (C2C), group @-mentions, guild, and direct messages with voice transcription.
+
+## Overview
+
+The QQ Bot adapter uses the [Official QQ Bot API](https://bot.q.qq.com/wiki/develop/api-v2/) to:
+
+- Receive messages via a persistent **WebSocket** connection to the QQ Gateway
+- Send text and markdown replies via the **REST API**
+- Download and process images, voice messages, and file attachments
+- Transcribe voice messages using Tencent's built-in ASR or a configurable STT provider
+
+## Prerequisites
+
+1. **QQ Bot Application** — Register at [q.qq.com](https://q.qq.com):
+   - Create a new application and note your **App ID** and **App Secret**
+   - Enable the required intents: C2C messages, Group @-messages, Guild messages
+   - Configure your bot in sandbox mode for testing, or publish for production
+
+2. **Dependencies** — The adapter requires `aiohttp` and `httpx`:
+   ```bash
+   pip install aiohttp httpx
+   ```
+
+## Configuration
+
+### Interactive setup
+
+```bash
+hermes setup gateway
+```
+
+Select **QQ Bot** from the platform list and follow the prompts.
+
+### Manual configuration
+
+Set the required environment variables in `~/.hermes/.env`:
+
+```bash
+QQ_APP_ID=your-app-id
+QQ_CLIENT_SECRET=your-app-secret
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `QQ_APP_ID` | QQ Bot App ID (required) | — |
+| `QQ_CLIENT_SECRET` | QQ Bot App Secret (required) | — |
+| `QQ_HOME_CHANNEL` | OpenID for cron/notification delivery | — |
+| `QQ_HOME_CHANNEL_NAME` | Display name for home channel | `Home` |
+| `QQ_ALLOWED_USERS` | Comma-separated user OpenIDs for DM access | open (all users) |
+| `QQ_ALLOW_ALL_USERS` | Set to `true` to allow all DMs | `false` |
+| `QQ_MARKDOWN_SUPPORT` | Enable QQ markdown (msg_type 2) | `true` |
+| `QQ_STT_API_KEY` | API key for voice-to-text provider | — |
+| `QQ_STT_BASE_URL` | Base URL for STT provider | `https://open.bigmodel.cn/api/coding/paas/v4` |
+| `QQ_STT_MODEL` | STT model name | `glm-asr` |
+
+## Advanced Configuration
+
+For fine-grained control, add platform settings to `~/.hermes/config.yaml`:
+
+```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"
+```
+
+## Voice Messages (STT)
+
+Voice transcription works in two stages:
+
+1. **QQ built-in ASR** (free, always tried first) — QQ provides `asr_refer_text` in voice message attachments, which uses Tencent's own speech recognition
+2. **Configured STT provider** (fallback) — If QQ's ASR doesn't return text, the adapter calls an OpenAI-compatible STT API:
+
+   - **Zhipu/GLM (zai)**: Default provider, uses `glm-asr` model
+   - **OpenAI Whisper**: Set `QQ_STT_BASE_URL` and `QQ_STT_MODEL`
+   - Any OpenAI-compatible STT endpoint
+
+## Troubleshooting
+
+### Bot disconnects immediately (quick disconnect)
+
+This usually means:
+- **Invalid App ID / Secret** — Double-check your credentials at q.qq.com
+- **Missing permissions** — Ensure the bot has the required intents enabled
+- **Sandbox-only bot** — If the bot is in sandbox mode, it can only receive messages from QQ's sandbox test channel
+
+### Voice messages not transcribed
+
+1. Check if QQ's built-in `asr_refer_text` is present in the attachment data
+2. If using a custom STT provider, verify `QQ_STT_API_KEY` is set correctly
+3. Check gateway logs for STT error messages
+
+### Messages not delivered
+
+- Verify the bot's **intents** are enabled at q.qq.com
+- Check `QQ_ALLOWED_USERS` if DM access is restricted
+- For group messages, ensure the bot is **@mentioned** (group policy may require allowlisting)
+- Check `QQ_HOME_CHANNEL` for cron/notification delivery
+
+### Connection errors
+
+- Ensure `aiohttp` and `httpx` are installed: `pip install aiohttp httpx`
+- Check network connectivity to `api.sgroup.qq.com` and the WebSocket gateway
+- Review gateway logs for detailed error messages and reconnect behavior