🏠 Главная › user guide › qqbot

QQ-бот

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

Обзор

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

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

  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 (обязательно) —
QQ_CLIENT_SECRET App Secret QQ Bot (обязательно) —
QQBOT_HOME_CHANNEL OpenID для доставки cron/уведомлений —
QQBOT_HOME_CHANNEL_NAME Отражаемое имя для канала дома Дом
QQ_ALLOWED_USERS Разделённые запятыми OpenID пользователи для доступа к ЛС открыть (все пользователи)
QQ_GROUP_ALLOWED_USERS Разделённые запятыми группы OpenID для доступа к группам —
QQ_ALLOW_ALL_USERS Установите true, чтобы разрешить все ЛС ложь
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) н/д
QQ_STT_MODEL Имя модели STT глм-аср

Дополнительные расширения

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

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

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

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

  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-конечная точка

Устранение неполадок

Бот мгновенно отключается (быстрое отключение)

Обычно это означает: - Неверный App ID / Secret — Перепроверьте свои учётные данные на q.qq.com - Отсутствуют разрешения — Убедитесь, что в бота включены необходимые намерения - Бот только в песочнице — Если бот в режиме песочницы, он может получать сообщения только из тестового канала песочницы QQ

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

  1. Проверьте, присутствует ли встроенный asr_refer_text QQ в данных вложения
  2. Если используется пользовательский STT-провайдер, убедитесь, что QQ_STT_API_KEY установлен правильно.
  3. Проверить наличие логиков шлюза на сообщениях об ошибках STT.

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

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