QQ-бот

QQ Bot підключається до OpenClaw через офіційний QQ Bot API (WebSocket gateway). Plugin підтримує приватні чати C2C, групові @повідомлення та повідомлення в каналах гільдій із мультимедіа (зображення, голос, відео, файли).

Стан: Plugin доступний для завантаження. Підтримуються прямі повідомлення, групові чати, канали гільдій і медіа. Реакції та треди не підтримуються.

Встановлення

Установіть QQ Bot перед налаштуванням:

openclaw plugins install @openclaw/qqbot

Налаштування

1. Перейдіть на QQ Open Platform і відскануйте QR-код за допомогою QQ на телефоні, щоб зареєструватися / увійти.
2. Натисніть Create Bot, щоб створити нового бота QQ.
3. Знайдіть AppID і AppSecret на сторінці налаштувань бота та скопіюйте їх.

AppSecret не зберігається у відкритому тексті — якщо ви залишите сторінку, не зберігши його, доведеться згенерувати новий.

4. Додайте канал:

openclaw channels add --channel qqbot --token "AppID:AppSecret"

5. Перезапустіть Gateway.

Інтерактивні шляхи налаштування:

openclaw channels addopenclaw configure --section channels

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

Мінімальна конфігурація:

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecret: "YOUR_APP_SECRET",    },  },}

Змінні середовища облікового запису за замовчуванням:

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

AppSecret із файлу:

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecretFile: "/path/to/qqbot-secret.txt",    },  },}

AppSecret через SecretRef середовища:

{  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:

{  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:

openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"

Групові чати

Підтримка групових чатів QQ Bot використовує OpenID груп QQ, а не відображувані імена. Додайте бота до групи, а потім згадайте його або налаштуйте групу для роботи без згадки.

{  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: групові перевизначення інструментів для окремих відправників; див. Групи.
• 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 підтримують дворівневу конфігурацію з пріоритетним резервним варіантом:

{  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

Цільові формати

Кожен бот має власний набір OpenID користувачів. OpenID, отриманий ботом A, не можна використовувати для надсилання повідомлень через бота B.

Слеш-команди

Вбудовані команди, що перехоплюються перед чергою AI:

Додайте ? до будь-якої команди, щоб отримати довідку з використання (наприклад, /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 налаштовано, а провайдер доступний.

Пов’язане

• Сполучення
• Групи
• Усунення несправностей каналу