Skip to Content
Руководство для пользователейВозможностиКаналыQQ Bot (QQ机器人)

QQ Bot (QQ机器人)

В этом руководстве описывается настройка канала Qwen Code через QQ с использованием официального API QQ Bot Open Platform.

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

  • Учётная запись QQ (мобильное приложение для сканирования QR-кода)

Настройка

Вход по QR-коду

Запустите канал — при первом запуске отобразится QR-код. Отсканируйте его в приложении QQ для активации. Учётная запись разработчика или ручная регистрация не требуются. Учётные данные сохраняются и используются автоматически.

{
  "channels": {
    "my-qq": {
      "type": "qq"
    }
  }
}
qwen channel start my-qq
# Отсканируйте QR-код в терминале с помощью приложения QQ

Ручная настройка (портал разработчика)

Вы также можете использовать учётные данные с портала разработчика QQ Bot Open Platform , если у вас уже зарегистрировано приложение:

{
  "channels": {
    "my-qq": {
      "type": "qq",
      "appID": "YOUR_APP_ID",
      "appSecret": "$QQ_APP_SECRET"
    }
  }
}

Установите секрет как переменную окружения:

export QQ_APP_SECRET=<ваш-секрет-приложения>

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

{
  "channels": {
    "my-qq": {
      "type": "qq",
      "appID": "YOUR_APP_ID",
      "appSecret": "$QQ_APP_SECRET",
      "sandbox": false,
      "senderPolicy": "open",
      "sessionScope": "user",
      "cwd": "/path/to/your/project",
      "instructions": "你是一个通过 QQ Bot 对话的 AI 助手。回复控制在 2000 字符以内。",
      "blockStreaming": "on",
      "groupPolicy": "disabled",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Специфичные для QQ параметры

ПараметрПо умолчаниюОписание
appID—AppID QQ Bot из портала разработчика. Если опущен, используется вход по QR-коду.
appSecret—AppSecret QQ Bot. Поддерживает синтаксис $ENV_VAR. Если опущен, используется вход по QR-коду.
sandboxfalseУстановите true, чтобы использовать тестовое API-окружение QQ (sandbox.api.sgroup.qq.com)

Все стандартные параметры канала (см. Обзор канала) также поддерживаются: senderPolicy, allowedUsers, sessionScope, cwd, instructions, groupPolicy, groups, dispatchMode, blockStreaming, blockStreamingChunk, blockStreamingCoalesce.

Запуск

# Запустить только QQ-канал
qwen channel start my-qq
 
# Или запустить все настроенные каналы вместе
qwen channel start

Откройте QQ и отправьте сообщение вашему боту. Вы должны увидеть ответ в чате.

Групповые чаты

Чтобы использовать бота в группах QQ:

  1. Установите groupPolicy в "allowlist" или "open" в конфигурации канала
  2. Добавьте бота в группу QQ через панель управления QQ Bot Open Platform или попросите администратора группы пригласить его
  3. Участники группы должны упомянуть бота (@mention), чтобы он ответил

QQ Bot API V2 доставляет только те групповые сообщения, в которых упоминается бот — бот не видит все сообщения группы. По умолчанию requireMention имеет значение true, и для QQ это значение следует оставить.

Подробнее о групповых политиках и ограничениях по упоминаниям см. в разделе Групповые чаты.

Поддержка Markdown

Канал QQ Bot поддерживает форматирование Markdown (msg_type=2). Markdown-ответы агента отправляются как есть, и QQ отображает их с богатым форматированием (жирный, курсив, блоки кода, ссылки, списки).

Если сервер QQ отклоняет Markdown-сообщение по какой-либо причине, канал автоматически повторяет отправку как обычный текст — ваши сообщения всегда будут доставлены, даже если Markdown-возможности бота ограничены на стороне сервера.

Это противоположность каналу WeChat, который удаляет всё форматирование Markdown. Вы можете разрешить агенту использовать полный Markdown в канале QQ.

Управление токенами

Токены доступа истекают примерно через 2 часа. Канал автоматически обновляет их при достижении 80% времени жизни (обычно ~1,6 часа). Если обновление не удаётся, оно повторяется через 60 секунд.

Обновление токена продолжается после переподключения WebSocket — канал никогда не отключается из-за просроченного токена, пока AppID и AppSecret остаются действительными.

Устойчивость соединения

  • Автопереподключение: При разрыве WebSocket канал повторяет попытку с экспоненциальной задержкой (до 20 попыток, максимум 30 секунд между попытками)
  • Восстановление сессии: Если WebSocket временно отключается, канал использует команду RESUME QQ для восстановления сессии без потери передаваемых сообщений
  • Продолжение контекста между серверами: Состояние чат-сессий и маршрутизации сохраняется на диск. При перезапуске демона разговоры продолжаются с того же места
  • Мониторинг пульса: Тайм-ауты HEARTBEAT_ACK обнаруживаются и вызывают принудительное переподключение для предотвращения “зомби-соединений”
  • Дедупликация сообщений: Повторно отправленные сообщения после переподключения обнаруживаются и пропускаются

Советы

  • Используйте Markdown свободно — в отличие от WeChat, QQ обрабатывает Markdown нативно. Жирный текст, блоки кода, списки и ссылки работают.
  • Ограничьте ответы 2000 символами — более длинные ответы автоматически разбиваются на части. Добавление подсказки о длине в инструкции поможет агенту быть лаконичным.
  • Песочница для тестирования — установите "sandbox": true, чтобы использовать тестовое API во время разработки. Рабочие сообщения не будут затронуты.
  • Ограничьте доступ — используйте senderPolicy: "allowlist" для фиксированного набора пользователей QQ или "pairing" для подтверждения новых пользователей из CLI. Подробнее см. в DM Pairing.

Ключевые отличия от Telegram

ОбластьQQ-ботTelegram
АутентификацияВход по QR-коду или AppID/AppSecretСтатический токен бота от BotFather
MarkdownНативный QQ Markdown с возвратом к обычному текстуHTML-форматирование из Markdown агента
Жизненный цикл токенаTTL 2 ч, автообновление при 80%Постоянный токен бота
Сообщения в группахБоту доставляются только сообщения с @упоминаниемБот видит все сообщения (если приватный режим выключен)
Индикатор набораНедоступно (ограничение QQ API)Сообщение «Печатает…»
ПесочницаПоддерживается для тестированияНедоступно

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

Бот не отвечает

  • Проверьте вывод терминала на наличие ошибок
  • Убедитесь, что канал запущен (qwen channel status)
  • Если используется senderPolicy: "allowlist", убедитесь, что ваш QQ-идентификатор есть в allowedUsers
  • При первом запуске в терминале появится QR-код — отсканируйте его в приложении QQ

Бот не отвечает в группах

  • Проверьте, что groupPolicy установлено в "allowlist" или "open" (по умолчанию — "disabled")
  • Вы должны @упомянуть бота — QQ доставляет только сообщения, в которых он отмечен
  • Убедитесь, что бот добавлен в группу

Вход по QR-коду завис

  • QR-код отображается в терминале. Отсканируйте его в мобильном приложении QQ (Я → Сканировать)
  • Если QR-код истёк (обычно через несколько минут), перезапустите канал, чтобы получить новый

Сообщения Markdown отображаются как обычный текст

  • Сервер QQ мог отклонить Markdown-сообщение, и канал незаметно вернулся к обычному тексту. Проверьте терминал на наличие сообщений в журнале "Markdown rejected"
  • Это нетипично для открытой платформы QQ Bot, но может произойти, если возможность Markdown у бота ограничена на стороне сервера

Срок действия токена истёк после длительного простоя

  • Если канал был отключён более 2 часов, срок действия токена доступа истечёт. При повторном подключении канал получает новый токен — никаких действий не требуется
  • Если сам AppSecret недействителен (например, изменён на портале разработчика), обновите поле appSecret или удалите ~/.qwen/channels/<name>-credentials.json, чтобы повторно запустить вход по QR-коду
Last updated on
Feishu (Lark)Хуки