🏠 Главная › User Guide › qqbot

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 to:

Prerequisites

  1. QQ Bot Application — Register at q.qq.com:
  2. Create a new application and note your App ID and App Secret
  3. Enable the required intents: C2C messages, Group @-messages, Guild messages

  4. Configure your bot in sandbox mode for testing, or publish for production

  5. Dependencies — The adapter requires aiohttp and httpx: bash pip install aiohttp httpx

Configuration

Interactive setup

hermes gateway setup

Select QQ Bot from the platform list and follow the prompts.

Manual configuration

Set the required environment variables in ~/.hermes/.env:

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

Environment Variables

| Variable | Description | Default | || lang: ru

|---| | QQ_APP_ID | Идентификатор приложения QQ Bot (обязательно) | — | | QQ_CLIENT_SECRET | Секрет приложения QQ Bot (обязательно) | — | | QQBOT_HOME_CHANNEL | OpenID для cron/доставки уведомлений | — | | QQBOT_HOME_CHANNEL_NAME | Отображаемое имя домашнего канала | Home | | QQ_ALLOWED_USERS | Открытые идентификаторы пользователей, разделенные запятыми, для доступа к DM | открыть (все пользователи) | | QQ_GROUP_ALLOWED_USERS | Групповые OpenID, разделенные запятыми, для группового доступа | — | | QQ_ALLOW_ALL_USERS | Установите true, чтобы разрешить все DM | false | | QQ_PORTAL_HOST | Переопределить хост портала QQ (установить sandbox.q.qq.com для маршрутизации в песочнице) | q.qq.com | | QQ_STT_API_KEY | API-ключ для провайдера голосовой связи | — | | QQ_STT_BASE_URL | Базовый URL-адрес для провайдера STT | 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:

platforms:
  qq:
    enabled: true
    extra:
      app_id: "your-app-id"
      client_secret: "your-secret"
      markdown_support: true       # enable QQ markdown (msg_type 2). Config-only; no env-var equivalent.
      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:

  3. Zhipu/GLM (zai): Default provider, uses glm-asr model

  4. OpenAI Whisper: Set QQ_STT_BASE_URL and QQ_STT _MODEL
  5. 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

Connection errors