🏠 Главная › Документация › Мессенджеры

QQ Bot

Подключите Hermes к QQ через Официальный QQ Bot API (v2) — поддерживает личные (C2C), групповые @-упоминания, гильдии и прямые сообщения с транскрипцией голоса.

Обзор

Адаптер QQ Bot использует Официальный QQ Bot API для:

Предварительные требования

  1. Приложение QQ Bot — Зарегистрируйтесь на q.qq.com:
  2. Создайте новое приложение и запишите ваш App ID и App Secret
  3. Включите необходимые разрешения: C2C-сообщения, групповые @-сообщения, сообщения гильдий

  4. Настройте бота в режиме песочницы для тестирования или опубликуйте для продакшена

  5. Зависимости — Адаптер требует aiohttp и httpx: bash 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 Bot App ID (обязательно) —
QQ_CLIENT_SECRET QQ Bot App Secret (обязательно) —
QQBOT_HOME_CHANNEL OpenID для доставки cron/уведомлений —
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 (Не читается напрямую — вместо этого установите platforms.qqbot.extra.stt.baseUrl в config.yaml) n/a
QQ_STT_MODEL Название модели STT glm-asr

Расширенная настройка

Для тонкой настройки добавьте параметры платформы в ~/.hermes/config.yaml:

platforms:
  qqbot:
    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"

Голосовые сообщения (STT)

Транскрипция голоса работает в два этапа:

  1. Встроенный ASR QQ (бесплатно, всегда пробуется первым) — QQ предоставляет asr_refer_text во вложениях голосовых сообщений, используя собственное распознавание речи Tencent

  2. Настроенный провайдер STT (запасной вариант) — Если ASR QQ не возвращает текст, адаптер вызывает OpenAI-совместимый STT API:

  3. Zhipu/GLM (zai): Провайдер по умолчанию, использует модель glm-asr

  4. OpenAI Whisper: Установите QQ_STT_BASE_URL и QQ_STT_MODEL
  5. Любой OpenAI-совместимый STT-эндпоинт

Диагностика проблем

Бот сразу отключается (быстрое отключение)

Обычно это означает:

Голосовые сообщения не транскрибируются

  1. Проверьте, присутствует ли встроенный asr_refer_text QQ в данных вложения

  2. Если используется пользовательский провайдер STT, убедитесь, что QQ_STT_API_KEY установлен правильно

  3. Проверьте логи gateway на наличие сообщений об ошибках STT

Сообщения не доставляются

Ошибки подключения