--- read_when: - Вы хотите подключить OpenClaw к QQ - Необходимо настроить учётные данные QQ Bot - Вам нужна поддержка групповых или личных чатов QQ Bot summary: Настройка, конфигурация и использование QQ Bot title: Бот QQ x-i18n: generated_at: "2026-07-13T17:56:01Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 71b0909e28e28d7f88e93b6f022f9aa2a4421d1381bb1ab4b706f381585ba476 source_path: channels/qqbot.md workflow: 16 --- QQ Bot подключается к OpenClaw через официальный API QQ Bot (Gateway WebSocket). Основными типами чатов являются личные чаты C2C и `@`-упоминания в группах; поддерживаются различные медиафайлы (изображения, голосовые сообщения, видео, файлы). Для сообщений в каналах гильдий поддерживаются только текст и изображения по удалённым URL; голосовые сообщения, видео, загрузка файлов и локальные изображения или изображения в формате Base64 в каналах гильдий недоступны. Реакции и ветки не поддерживаются нигде. Статус: официальный загружаемый плагин. ## Установка ```bash openclaw plugins install @openclaw/qqbot ``` ## Настройка 1. Перейдите на [открытую платформу QQ](https://q.qq.com/) и отсканируйте QR-код с помощью приложения QQ на телефоне, чтобы зарегистрироваться или войти. 2. Нажмите **Create Bot**, чтобы создать нового бота QQ. 3. Найдите **AppID** и **AppSecret** на странице настроек бота и скопируйте их. AppSecret не хранится в виде открытого текста. Если вы покинете страницу, не сохранив его, потребуется создать новый. 4. Добавьте канал: ```bash openclaw channels add --channel qqbot --token "AppID:AppSecret" ``` 5. Перезапустите Gateway. Интерактивная настройка: ```bash openclaw channels add ``` Вместо ручного ввода AppID/AppSecret мастер также предлагает привязку по QR-коду: отсканируйте код в мобильном приложении, связанном с нужным QQ Bot, чтобы завершить привязку. OpenClaw сохраняет полученные учётные данные в области конфигурации учётной записи. ## Конфигурация Минимальная конфигурация: ```json5 { channels: { qqbot: { enabled: true, appId: "YOUR_APP_ID", clientSecret: "YOUR_APP_SECRET", }, }, } ``` Переменные среды учётной записи по умолчанию (только учётная запись верхнего уровня): - `QQBOT_APP_ID` - `QQBOT_CLIENT_SECRET` AppSecret из файла: ```json5 { channels: { qqbot: { enabled: true, appId: "YOUR_APP_ID", clientSecretFile: "/path/to/qqbot-secret.txt", }, }, } ``` AppSecret через SecretRef из переменной среды: ```json5 { channels: { qqbot: { enabled: true, appId: "YOUR_APP_ID", clientSecret: { source: "env", provider: "default", id: "QQBOT_CLIENT_SECRET" }, }, }, } ``` Примечания: - `openclaw channels add --channel qqbot --token-file ...` задаёт только AppSecret; `appId` должен быть уже задан в конфигурации или `QQBOT_APP_ID`. - `clientSecret` принимает строку с открытым текстом, путь к файлу (`clientSecretFile`) или структурированный объект SecretRef. - Устаревшие строки-маркеры `secretref:...` / `secretref-env:...` отклоняются для `clientSecret`; вместо них используйте структурированный объект SecretRef. ### Потоковая передача ```json5 { channels: { qqbot: { streaming: { mode: "partial", // потоковая передача блоков: "partial" (по умолчанию) или "off" nativeTransport: true, // использовать официальный API stream_messages QQ для личных сообщений C2C }, }, }, } ``` - `streaming.mode: "off"` отключает потоковую передачу блоков для учётной записи. - `streaming.nativeTransport: true` передаёт ответы C2C (личные сообщения) потоково через официальный API `stream_messages` QQ; групповые цели и цели каналов не затрагиваются. - Устаревшие скалярные значения `streaming: true|false` и ключ `streaming.c2cStreamApi` переносятся в эту структуру через `openclaw doctor --fix`. - `/bot-streaming on|off` переключает ту же конфигурацию из личного сообщения. ### Политика доступа - `allowFrom` / `groupAllowFrom` определяют, кто может общаться с ботом в контекстах C2C / групп. `dmPolicy` / `groupPolicy` (`open` | `allowlist` | `disabled`) управляют режимом применения ограничений. По умолчанию `dmPolicy` имеет значение `allowlist`, если `allowFrom` содержит конкретную запись (без подстановочного знака), иначе — `open`. По умолчанию `groupPolicy` имеет значение `allowlist`, если `groupAllowFrom` или `allowFrom` содержит конкретную запись, иначе — `open`. - Для слеш-команд «Auth: allowlist» требуется явная запись без подстановочного знака в `allowFrom` (или `groupAllowFrom` для вызовов из группы) независимо от `dmPolicy` / `groupPolicy` — см. [Слеш-команды](#slash-commands). ### Настройка нескольких учётных записей Запустите несколько ботов QQ в одном экземпляре OpenClaw: ```json5 { channels: { qqbot: { enabled: true, appId: "111111111", clientSecret: "secret-of-bot-1", accounts: { bot2: { enabled: true, appId: "222222222", clientSecret: "secret-of-bot-2", }, }, }, }, } ``` Каждая учётная запись имеет отдельное WebSocket-соединение, клиент API и кеш токенов, идентифицируемые по `appId`. Строки журнала помечаются идентификатором соответствующей учётной записи, чтобы диагностические данные оставались разделёнными при запуске нескольких ботов через один Gateway. Добавьте второго бота через CLI: ```bash openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2" ``` ### Групповые чаты Для поддержки групп используются OpenID групп QQ, а не отображаемые имена. Добавьте бота в группу, затем упомяните его или настройте группу для работы без упоминания. ```json5 { channels: { qqbot: { groupPolicy: "allowlist", groupAllowFrom: ["member_openid"], groups: { "*": { requireMention: true, commandLevel: "all", historyLimit: 50, tools: { deny: ["exec", "read", "write"] }, }, GROUP_OPENID: { name: "Release room", requireMention: false, ignoreOtherMentions: true, commandLevel: "safety", historyLimit: 20, prompt: "Keep replies short and operational.", }, }, }, }, } ``` `groups["*"]` задаёт значения по умолчанию для каждой группы; конкретная запись `groups.GROUP_OPENID` переопределяет эти значения для одной группы. Настройки группы: | Поле | Значение по умолчанию | Описание | | --------------------- | --------------------- | ----------------------------------------------------------------------------------------------------- | | `requireMention` | `true` | Требовать `@`-упоминание, прежде чем бот ответит. | | `commandLevel` | `all` | Какие встроенные слеш-команды могут выполняться в группе (см. ниже). | | `ignoreOtherMentions` | `false` | Отбрасывать сообщения, в которых упомянут кто-то другой, но не бот. | | `historyLimit` | `50` | Недавние сообщения без упоминания, сохраняемые как контекст для следующего обращения с упоминанием. `0` отключает историю. | | `tools` | — | Разрешить или запретить инструменты для всей группы. | | `toolsBySender` | — | Переопределения инструментов для отдельных отправителей; см. [Группы](/ru/channels/groups#groupchannel-tool-restrictions-optional). | | `name` | префикс openid | Понятная метка, используемая в журналах и контексте группы. | | `prompt` | встроенное значение по умолчанию | Инструкция по поведению для отдельной группы, добавляемая в контекст агента. | `commandLevel` принимает: | Уровень | Поведение | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `all` | Существующие встроенные команды остаются доступными. Некоторые из них скрыты в меню, но авторизованные пользователи по-прежнему могут выполнять их в группе. | | `safety` | `/help`, `/btw`, `/stop` остаются видимыми в группе; конфиденциальные команды (`/config`, `/tools`, `/bash` и т. д.) необходимо выполнять в личном чате. | | `strict` | Разрешены только элементы управления групповым сеансом, необходимые для строгого режима работы. `/stop` продолжает работать, чтобы авторизованный отправитель мог прервать активный запуск. | Старые записи QQBot `toolPolicy` больше не используются. Выполните `openclaw doctor --fix`, чтобы перенести их в `tools`. Режимы активации: `mention` и `always`. `requireMention: true` соответствует `mention`; `requireMention: false` соответствует `always`. Переопределение активации на уровне сеанса, если оно задано, имеет приоритет над конфигурацией. Входящая очередь создаётся отдельно для каждого собеседника. Для групповых собеседников установлен больший предел очереди (50 вместо 20 для прямых собеседников); при заполнении сообщения бота удаляются раньше сообщений людей, а серии обычных групповых сообщений объединяются в один ход с указанием авторов. Слеш- команды выполняются по одной независимо от пакетов объединения. ### Голос (STT / TTS) STT и TTS поддерживают двухуровневую конфигурацию с резервным переходом по приоритету: | Настройка | Для плагина | Резервное значение фреймворка | | --------- | -------------------------------------------------------- | ----------------------------- | | STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` | | TTS | `channels.qqbot.tts`, `channels.qqbot.accounts..tts` | `messages.tts` | ```json5 { channels: { qqbot: { stt: { provider: "your-provider", model: "your-stt-model", }, tts: { provider: "your-provider", model: "your-tts-model", voice: "your-voice", }, accounts: { "qq-main": { tts: { providers: { openai: { voice: "shimmer" }, }, }, }, }, }, }, } ``` Установите `enabled: false` для любого из них, чтобы отключить его. Переопределения TTS на уровне учётной записи используют ту же структуру, что и `messages.tts`, и глубоко объединяются с конфигурацией TTS канала или глобальной конфигурацией. По умолчанию время ожидания запросов STT истекает через 60 секунд. STT плагина использует выбранное переопределение `models.providers..timeoutSeconds`. STT аудио на уровне фреймворка сначала использует `tools.media.audio.models[0].timeoutSeconds`, затем `tools.media.audio.timeoutSeconds`, а затем переопределение выбранного провайдера. Входящие голосовые вложения QQ предоставляются агентам как метаданные аудиоматериалов, при этом необработанные голосовые файлы не попадают в общий `MediaPaths`. `[[audio_as_voice]]` в ответе с обычным текстом синтезирует TTS и отправляет нативное голосовое сообщение QQ, если TTS настроен. Поведение загрузки и перекодирования исходящего аудио также можно настроить с помощью `channels.qqbot.audioFormatPolicy`: - `sttDirectFormats` - `uploadDirectFormats` - `transcodeEnabled` ## Форматы целей | Формат | Описание | | -------------------------- | ------------------ | | `qqbot:c2c:OPENID` | Личный чат (C2C) | | `qqbot:group:GROUP_OPENID` | Групповой чат | | `qqbot:channel:CHANNEL_ID` | Канал гильдии | У каждого бота есть собственный набор OpenID пользователей. OpenID, полученный ботом A, **нельзя** использовать для отправки сообщений через бота B. ## Слеш-команды Встроенные команды, перехватываемые до очереди ИИ: | Команда | Авторизация | Область действия | Описание | | -------------------- | --------- | ------------ | ------------------------------------------------------------------------------ | | `/bot-ping` | — | любая | Проверка задержки | | `/bot-help` | — | любая | Вывести все команды | | `/bot-me` | — | только личные чаты | Показать идентификатор пользователя QQ (openid) отправителя для настройки `allowFrom` / `groupAllowFrom` | | `/bot-version` | — | только личные чаты | Показать версию платформы OpenClaw и версию плагина | | `/bot-upgrade` | — | только личные чаты | Показать ссылку на руководство по обновлению QQBot | | `/bot-approve` | список разрешений | только личные чаты | Управлять конфигурацией подтверждения выполнения команд (вкл. / выкл. / всегда / сброс / состояние) | | `/bot-logs` | список разрешений | только личные чаты | Экспортировать последние журналы Gateway в виде файла | | `/bot-clear-storage` | список разрешений | только личные чаты | Удалить кэшированные загрузки из каталога мультимедиа QQBot | | `/bot-streaming` | список разрешений | только личные чаты | Включить или отключить потоковые ответы C2C | | `/bot-group-allways` | список разрешений | только личные чаты | Переключить режим активации группы по умолчанию (требуется упоминание или всегда активен) | Добавьте `?` к любой команде, чтобы получить справку по её использованию (например, `/bot-upgrade ?`). Команды с «Авторизация: список разрешений» дополнительно требуют, чтобы openid отправителя находился в явном списке `allowFrom` без подстановочного знака (`groupAllowFrom` имеет приоритет для команд, отправленных из группы; иначе используется `allowFrom`). Подстановочный знак `allowFrom: ["*"]` разрешает общение в чате, но не выполнение этих команд. При запуске одной из них вне личного чата или без авторизации возвращается подсказка, а сообщение не отбрасывается без уведомления. `/bot-me`, `/bot-version` и `/bot-upgrade` доступны только в личных чатах, но не требуют списка разрешений — их может выполнить любой отправитель C2C. Когда для подтверждений выполнения команд QQ Bot используется стандартный резервный вариант в том же чате, нажатия встроенных кнопок подтверждения подчиняются тому же явному списку разрешённых команд без подстановочного знака. Чтобы предоставить доступ только к подтверждениям без расширенного доступа к командам, настройте `channels.qqbot.execApprovals.approvers`. Встроенные подтверждения выполнения команд включены по умолчанию. ## Мультимедиа и хранилище - Входящие, исходящие и передаваемые через мост Gateway мультимедиа используют единый корневой каталог данных `~/.openclaw/media/qqbot` (с учётом `OPENCLAW_HOME`, если он задан), поэтому отправленные, загруженные файлы и кэши перекодирования находятся в одном защищённом каталоге. - Доставка мультимедийного содержимого для адресатов C2C и групп выполняется через единый путь `sendMedia`. Для локальных файлов и буферов в памяти размером 5 MiB или более используются конечные точки QQ для загрузки по частям; для данных меньшего размера и источников в виде удалённых URL или Base64 используется API однократной загрузки. - Если горячее обновление прерывает работу Gateway до завершения записи `openclaw.json`, при следующем запуске плагин восстанавливает последние известные `appId` / `clientSecret` для этой учётной записи из внутреннего снимка (никогда не перезаписывая намеренное изменение конфигурации), поэтому повторное сканирование QR-кода не требуется. ## Устранение неполадок - **Gateway не запускается / нет входящих сообщений:** убедитесь, что `appId` и `clientSecret` указаны верно, а бот включён на платформе QQ Open Platform. При отсутствии учётных данных отображается сообщение «QQBot не настроен (отсутствует appId или clientSecret)». - **После настройки с помощью `--token-file` по-прежнему отображается состояние «не настроено»:** `--token-file` задаёт только AppSecret. `appId` всё равно необходимо указать в конфигурации или `QQBOT_APP_ID`. - **Пакетные ответы в группе конфликтуют:** при заполнении очереди участника очередь входящих сообщений удаляет сообщения от ботов раньше сообщений от людей и объединяет серии обычных групповых сообщений (не команд) в один ход с указанием авторства, поэтому поток сообщений от ботов не должен лишать сообщения людей возможности обработки. - **Проактивные сообщения не доставляются:** QQ может блокировать сообщения, инициированные ботом, если пользователь давно с ним не взаимодействовал. - **Голосовые сообщения не расшифровываются:** убедитесь, что STT настроено, а провайдер доступен. ## См. также - [Сопряжение](/ru/channels/pairing) - [Группы](/ru/channels/groups) - [Устранение неполадок каналов](/ru/channels/troubleshooting)