Перейти к основному содержимому

QQ Bot

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

Обзор​

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

  • Получения сообщений через постоянное WebSocket-соединение с QQ Gateway
  • Отправки текстовых и markdown-ответов через REST API
  • Загрузки и обработки изображений, голосовых сообщений и вложений файлов
  • Транскрипции голосовых сообщений с помощью встроенного ASR от Tencent или настраиваемого STT-провайдера

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

  1. Приложение QQ Bot — Зарегистрируйтесь на q.qq.com:

    • Создайте новое приложение и запишите App ID и App Secret
    • Включите необходимые интенты: C2C-сообщения, @-сообщения в группах, сообщения гильдий
    • Настройте бота в режиме песочницы для тестирования или опубликуйте для продакшена

  2. Зависимости — Адаптеру требуются aiohttp и httpx:

    pip install aiohttp httpx

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

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

vibeos gateway setup

Выберите QQ Bot из списка платформ и следуйте инструкциям.

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

Установите необходимые переменные окружения в ~/.vibeos/.env:

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

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

ПеременнаяОписаниеПо умолчанию
QQ_APP_IDApp ID приложения QQ Bot (обязательно)—
QQ_CLIENT_SECRETApp Secret приложения QQ Bot (обязательно)—
QQBOT_HOME_CHANNELOpenID для доставки cron/уведомлений—
QQBOT_HOME_CHANNEL_NAMEОтображаемое имя домашнего каналаHome
QQ_ALLOWED_USERSРазделённые запятыми OpenID пользователей для доступа к ЛСopen (все пользователи)
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_KEYAPI-ключ для провайдера преобразования речи в текст—
QQ_STT_BASE_URL(Не читается напрямую — вместо этого установите platforms.qqbot.extra.stt.baseUrl в config.yaml)н/д
QQ_STT_MODELНазвание STT-моделиglm-asr

Расширенная конфигурация​

Для тонкой настройки добавьте настройки платформы в ~/.vibeos/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"

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

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

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

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

    • Zhipu/GLM (zai): Провайдер по умолчанию, использует модель glm-asr
    • OpenAI Whisper: Установите QQ_STT_BASE_URL и QQ_STT_MODEL
    • Любая OpenAI-совместимая STT-конечная точка

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

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

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

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

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

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

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

  • Убедитесь, что интенты бота включены на q.qq.com
  • Проверьте QQ_ALLOWED_USERS, если доступ к ЛС ограничен
  • Для групповых сообщений убедитесь, что бот @упомянут (политика группы может требовать внесения в белый список)
  • Проверьте QQBOT_HOME_CHANNEL для доставки cron/уведомлений

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

  • Убедитесь, что aiohttp и httpx установлены: pip install aiohttp httpx
  • Проверьте сетевое подключение к api.sgroup.qq.com и WebSocket-шлюзу
  • Просмотрите логи шлюза для получения подробных сообщений об ошибках и поведении при переподключении