QQ-бот

Команды установки Python-зависимостей на этой странице рассчитаны на чекаут исходников, подготовленный через PM. После изменения зависимостей заново активируйте чекаут и перезапустите Hermes.

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

Обзор

Адаптер QQ-бота работает поверх официального QQ Bot API и умеет:

принимать сообщения через постоянное WebSocket-соединение со шлюзом QQ;
отправлять ответы текстом и в формате markdown через REST API;
скачивать и обрабатывать изображения, голосовые сообщения и вложенные файлы;
расшифровывать голосовые сообщения встроенным ASR от Tencent либо настраиваемым STT-провайдером.

Что понадобится заранее

Приложение QQ-бота — зарегистрируйте его на q.qq.com:
- создайте новое приложение и запишите свои App ID и App Secret;
- включите нужные intent’ы: сообщения C2C, упоминания через @ в группах, сообщения гильдий;
- для тестов настройте бота в режиме песочницы (sandbox), а для боевого использования — опубликуйте.
Зависимости — адаптеру нужны aiohttp и httpx:
```
python -c "import pm; pm.sync_venv(['messaging'], explicit=True)"
```

Конфигурация

Интерактивная настройка

hermes gateway setup

Выберите в списке платформ QQ Bot и отвечайте на вопросы мастера.

Ручная настройка

Задайте обязательные переменные окружения в ~/.hermes/.env:

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

Переменные окружения

Переменная	Описание	По умолчанию
`QQ_APP_ID`	App ID QQ-бота (обязательно)	—
`QQ_CLIENT_SECRET`	App Secret QQ-бота (обязательно)	—
`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       # включает markdown QQ (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"
        timeout: 60              # seconds per transcription request (default 60)

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

Расшифровка голоса идёт в два этапа:

Встроенный ASR от QQ (бесплатно, пробуется всегда первым) — QQ кладёт в вложение голосового сообщения поле asr_refer_text, полученное собственным распознаванием речи Tencent.
Настроенный STT-провайдер (запасной вариант) — если ASR от QQ не вернул текст, адаптер обращается к STT-API, совместимому с OpenAI:
- Zhipu/GLM (zai): провайдер по умолчанию, использует модель glm-asr;
- OpenAI Whisper: задайте QQ_STT_BASE_URL и QQ_STT_MODEL;
- любой STT-эндпоинт, совместимый с OpenAI.

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

Бот сразу отваливается (мгновенный разрыв соединения)

Обычно причина в одном из трёх:

Неверные App ID / Secret — перепроверьте учётные данные на q.qq.com.
Не хватает прав — убедитесь, что у бота включены нужные intent’ы.
Бот только в песочнице — бот в режиме sandbox принимает сообщения только из тестового канала песочницы QQ.

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

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

Сообщения не доходят

Проверьте, что intent’ы бота включены на q.qq.com.
Загляните в QQ_ALLOWED_USERS, если доступ к личке ограничен.
Для групповых сообщений бот должен быть упомянут через @ (политика группы может требовать списка разрешений).
Проверьте QQBOT_HOME_CHANNEL для доставки cron-задач и уведомлений.

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

Убедитесь, что установлены aiohttp и httpx: python -c "import pm; pm.sync_venv(['messaging'], explicit=True)".
Проверьте сетевую доступность api.sgroup.qq.com и WebSocket-шлюза.
Посмотрите логи шлюза — там детальные сообщения об ошибках и поведение при переподключении.