--- read_when: - Вы хотите подключить OpenClaw к QQ - Требуется настройка учетных данных QQ Bot - Вам нужна поддержка групповых или личных чатов QQ Bot summary: Настройка, конфигурация и использование бота QQ title: QQ-бот x-i18n: generated_at: "2026-06-28T22:36:36Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: eb452e331ce196d1517af2f87a5187cb4b2cb53aee2bbff47cbdf73e2b3e7dee source_path: channels/qqbot.md workflow: 16 --- QQ Bot подключается к OpenClaw через официальный QQ Bot API (WebSocket gateway). Plugin поддерживает личные C2C-чаты, групповые @сообщения и сообщения в каналах гильдий с мультимедиа (изображения, голос, видео, файлы). Статус: загружаемый Plugin. Личные сообщения, групповые чаты, каналы гильдий и мультимедиа поддерживаются. Реакции и треды не поддерживаются. ## Установка Установите QQ Bot перед настройкой: ```bash openclaw plugins install @openclaw/qqbot ``` ## Настройка 1. Перейдите на [QQ Open Platform](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 openclaw configure --section channels ``` ## Конфигурация Минимальная конфигурация: ```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" }, }, }, } ``` Примечания: - Резервное использование переменных окружения применяется только к учетной записи QQ Bot по умолчанию. - `openclaw channels add --channel qqbot --token-file ...` предоставляет только AppSecret; AppID уже должен быть задан в конфигурации или `QQBOT_APP_ID`. - `clientSecret` также принимает ввод SecretRef, а не только строку в открытом виде. - Устаревшие строки-маркеры `secretref:/...` не являются допустимыми значениями `clientSecret`; используйте структурированные объекты SecretRef, как в примере выше. ### Настройка нескольких учетных записей Запустите несколько 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-соединение и поддерживает независимый кеш токенов (изолированный по `appId`). Добавьте второго бота через CLI: ```bash openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2" ``` ### Групповые чаты Поддержка групповых чатов QQ Bot использует 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`, что сохраняет прежнее поведение групп QQBot, когда настройка опущена. - `ignoreOtherMentions`: отбрасывать сообщения, в которых упоминают кого-то еще, но не бота. - `historyLimit`: сохранять последние групповые сообщения без упоминания как контекст для следующего хода с упоминанием. Установите `0`, чтобы отключить. - `tools`: разрешать/запрещать инструменты для всей группы. - `toolsBySender`: переопределения групповых инструментов для отдельных отправителей; см. [Группы](/ru/channels/groups#groupchannel-tool-restrictions-optional). - `name`: удобная метка, используемая в журналах и контексте группы. - `prompt`: 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`. Переопределение активации на уровне сессии, если оно есть, имеет приоритет над конфигурацией. Входящая очередь ведется отдельно для каждого peer. Групповые peer получают больший лимит очереди, при заполнении сохраняют человеческие сообщения впереди сообщений, написанных ботом, и объединяют всплески обычных групповых сообщений в один атрибутированный ход. Слэш-команды по-прежнему выполняются по одной. ### Голос (STT / TTS) STT и TTS поддерживают двухуровневую конфигурацию с приоритетным fallback: | Настройка | Специфично для Plugin | Fallback фреймворка | | ------- | -------------------------------------------------------- | ----------------------------- | | 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 канала/глобальной конфигурации. Входящие голосовые вложения 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, полученный Bot A, **нельзя** > использовать для отправки сообщений через Bot B. ## Слэш-команды Встроенные команды, перехватываемые перед очередью ИИ: | Команда | Описание | | -------------- | -------------------------------------------------------------------------------------------------------- | | `/bot-ping` | Тест задержки | | `/bot-version` | Показать версию фреймворка OpenClaw | | `/bot-help` | Перечислить все команды | | `/bot-me` | Показать QQ user ID отправителя (openid) для настройки `allowFrom`/`groupAllowFrom` | | `/bot-upgrade` | Показать ссылку на руководство по обновлению QQBot | | `/bot-logs` | Экспортировать последние журналы Gateway как файл | | `/bot-approve` | Одобрить ожидающее действие QQ Bot (например, подтверждение загрузки в C2C или группу) через нативный поток. | Добавьте `?` к любой команде, чтобы получить справку по использованию (например, `/bot-upgrade ?`). Административные команды (`/bot-me`, `/bot-upgrade`, `/bot-logs`, `/bot-clear-storage`, `/bot-streaming`, `/bot-approve`) доступны только в личных сообщениях и требуют, чтобы openid отправителя был в явном списке `allowFrom` без wildcard. Wildcard `allowFrom: ["*"]` разрешает чат, но не дает доступ к административным командам. Групповые сообщения сначала сопоставляются с `groupAllowFrom`, а затем используют fallback к `allowFrom`. Запуск административной команды в группе возвращает подсказку, а не молча отбрасывается. Когда одобрения exec в QQ Bot используют стандартный fallback в тот же чат, нажатия нативных кнопок одобрения следуют тому же явному allowlist команд без wildcard. Чтобы предоставить доступ только к одобрениям без более широкого доступа к командам, настройте `channels.qqbot.execApprovals.approvers`. ## Архитектура движка QQ Bot поставляется как самодостаточный движок внутри Plugin: - Каждый аккаунт владеет изолированным стеком ресурсов (соединение WebSocket, клиент API, кэш токенов, корень хранилища медиа), привязанным к `appId`. Аккаунты никогда не разделяют входящее/исходящее состояние. - Логгер для нескольких аккаунтов помечает строки журнала аккаунтом-владельцем, чтобы диагностика оставалась разделяемой, когда вы запускаете несколько ботов под одним Gateway. - Входящие, исходящие пути и пути моста Gateway используют один корень медианагрузки в `~/.openclaw/media`, поэтому загрузки, скачивания и кэши транскодирования попадают в один защищенный каталог вместо дерева для каждой подсистемы. - Доставка rich media проходит через один путь `sendMedia` для целей C2C и групп. Локальные файлы и буферы выше порога большого файла используют chunked upload endpoints QQ, а меньшие нагрузки используют одноразовый media API. - Учетные данные можно сохранять в резервной копии и восстанавливать как часть стандартных снимков учетных данных OpenClaw; движок повторно подключает стек ресурсов каждого аккаунта при восстановлении без необходимости новой пары QR-кода. ## Онбординг по QR-коду В качестве альтернативы ручной вставке `AppID:AppSecret` движок поддерживает поток онбординга по QR-коду для привязки QQ Bot к OpenClaw: 1. Запустите путь настройки QQ Bot (например, `openclaw channels add --channel qqbot`) и выберите поток QR-кода при запросе. 2. Отсканируйте сгенерированный QR-код телефонным приложением, привязанным к целевому QQ Bot. 3. Одобрите сопряжение на телефоне. OpenClaw сохраняет возвращенные учетные данные в `credentials/` в правильной области аккаунта. Запросы одобрения, созданные самим ботом (например, потоки "разрешить это действие?", предоставляемые QQ Bot API), отображаются как нативные prompts OpenClaw, которые можно принять с помощью `/bot-approve`, а не отвечая через сырой клиент QQ. ## Устранение неполадок - **Бот отвечает «gone to Mars»:** учетные данные не настроены или Gateway не запущен. - **Нет входящих сообщений:** проверьте, что `appId` и `clientSecret` указаны правильно, а бот включен на QQ Open Platform. - **Повторяющиеся автоответы:** OpenClaw записывает индексы исходящих ссылок QQ как созданные ботом и игнорирует входящие события, у которых текущий `msgIdx` совпадает с той же учетной записью бота. Это предотвращает петли эха платформы, но при этом позволяет пользователям цитировать предыдущие сообщения бота или отвечать на них. - **Настройка с `--token-file` по-прежнему показывает, что конфигурация не выполнена:** `--token-file` задает только AppSecret. Вам все еще нужен `appId` в конфигурации или `QQBOT_APP_ID`. - **Проактивные сообщения не приходят:** QQ может перехватывать сообщения, инициированные ботом, если пользователь давно не взаимодействовал с ним. - **Голос не транскрибируется:** убедитесь, что STT настроен и провайдер доступен. ## Связанные материалы - [Сопряжение](/ru/channels/pairing) - [Группы](/ru/channels/groups) - [Устранение неполадок канала](/ru/channels/troubleshooting)