--- read_when: - Ви хочете підключити OpenClaw до QQ - Вам потрібно налаштувати облікові дані QQ Bot - Вам потрібна підтримка QQ Bot у групових або приватних чатах summary: Налаштування, конфігурація та використання QQ Bot title: QQ-бот x-i18n: generated_at: "2026-06-27T17:13:04Z" 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`: групові перевизначення інструментів для окремих відправників; див. [Групи](/uk/channels/groups#groupchannel-tool-restrictions-optional). - `name`: зручна мітка, що використовується в журналах і контексті групи. - `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`. Перевизначення активації на рівні сесії, якщо воно є, має пріоритет над конфігурацією. Вхідна черга є окремою для кожного співрозмовника. Для групових співрозмовників діє більший ліміт черги, людські повідомлення зберігаються попереду повідомлень від ботів, коли черга заповнена, а сплески звичайних групових повідомлень об'єднуються в один атрибутований хід. Слеш-команди все одно виконуються по одній. ### Голос (STT / TTS) STT і TTS підтримують дворівневу конфігурацію з пріоритетним резервним варіантом: | Параметр | Специфічний для Plugin | Резервний варіант framework | | ------- | -------------------------------------------------------- | ----------------------------- | | 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, отриманий ботом A, **не можна** > використовувати для надсилання повідомлень через бота B. ## Слеш-команди Вбудовані команди, що перехоплюються перед чергою AI: | Команда | Опис | | -------------- | -------------------------------------------------------------------------------------------------------- | | `/bot-ping` | Тест затримки | | `/bot-version` | Показати версію framework 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`, а потім повертаються до `allowFrom`. Запуск адміністративної команди в групі повертає підказку, а не мовчки відкидає її. Коли схвалення виконання QQ Bot використовують стандартний резервний варіант у тому самому чаті, натискання нативних кнопок схвалення дотримуються того самого явного списку дозволених команд без wildcard. Щоб надати доступ лише для схвалення без ширшого доступу до команд, налаштуйте `channels.qqbot.execApprovals.approvers`. ## Архітектура рушія QQ Bot постачається як самодостатній рушій усередині Plugin: - Кожен обліковий запис володіє ізольованим стеком ресурсів (WebSocket-з'єднання, API-клієнт, кеш токенів, корінь медіасховища), прив'язаним до `appId`. Облікові записи ніколи не спільно використовують вхідний/вихідний стан. - Логер для кількох облікових записів позначає рядки журналу обліковим записом-власником, щоб діагностика залишалася розділеною, коли ви запускаєте кілька ботів під одним gateway. - Вхідні, вихідні та bridge-шляхи gateway спільно використовують один корінь медіанавантажень у `~/.openclaw/media`, тож завантаження, вивантаження та кеші транскодування потрапляють до одного захищеного каталогу замість дерева для кожної підсистеми. - Доставка мультимедіа проходить через один шлях `sendMedia` для цілей C2C і груп. Локальні файли та буфери, що перевищують поріг великих файлів, використовують chunked upload endpoints QQ, тоді як менші навантаження використовують one-shot media API. - Облікові дані можна резервно копіювати й відновлювати як частину стандартних snapshots облікових даних OpenClaw; рушій повторно приєднує стек ресурсів кожного облікового запису під час відновлення без потреби в новій парі QR-коду. ## Онбординг через QR-код Як альтернативу ручному вставленню `AppID:AppSecret`, рушій підтримує потік онбордингу через QR-код для прив'язування QQ Bot до OpenClaw: 1. Запустіть шлях налаштування QQ Bot (наприклад, `openclaw channels add --channel qqbot`) і виберіть потік QR-коду, коли з'явиться запит. 2. Відскануйте згенерований QR-код за допомогою телефонного застосунку, прив'язаного до цільового QQ Bot. 3. Схваліть pairing на телефоні. OpenClaw зберігає повернені облікові дані в `credentials/` у правильній області облікового запису. Запити на схвалення, згенеровані самим ботом (наприклад, потоки "allow this action?", надані QQ Bot API), відображаються як нативні запити 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 налаштовано, а провайдер доступний. ## Пов’язане - [Сполучення](/uk/channels/pairing) - [Групи](/uk/channels/groups) - [Усунення несправностей каналу](/uk/channels/troubleshooting)