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=<your-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 для использования sandbox-среды API QQ (sandbox.api.sgroup.qq.com)

Также поддерживаются все стандартные параметры канала (см. Channel Overview): 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. Участники группы должны @упомянуть бота, чтобы вызвать ответ.

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

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

Поддержка Markdown

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

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

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

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

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

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

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

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

Советы

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

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

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

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

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

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

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

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

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

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

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

  • Возможно, сервер QQ отклонил сообщение в Markdown, и канал незаметно переключился на обычный текст. Проверьте терминал на наличие логов "Markdown rejected".
  • На платформе QQ Bot Open Platform это редкость, но может произойти, если возможность использования Markdown ограничена на стороне сервера.

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

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