QQ-бот

QQ Bot підключається до OpenClaw через офіційний API QQ Bot (WebSocket-шлюз). Приватні чати C2C та @-згадки в групах є основними типами чатів із мультимедійним вмістом (зображеннями, голосовими повідомленнями, відео та файлами). Повідомлення в каналах гільдій підтримують лише текст і зображення за віддаленими URL; голосові повідомлення, відео, завантаження файлів і локальні/Base64 зображення в каналах гільдій недоступні. Реакції та гілки обговорень ніде не підтримуються.

Статус: офіційний Plugin, доступний для завантаження.

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

openclaw plugins install @openclaw/qqbot

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

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

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

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

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

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

openclaw channels add

Майстер також пропонує прив’язування за допомогою QR-коду як альтернативу ручному введенню AppID/AppSecret: відскануйте код у телефонному застосунку, пов’язаному з цільовим QQ Bot, щоб завершити прив’язування. OpenClaw зберігає отримані облікові дані в області конфігурації облікового запису.

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

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

{  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 як Env SecretRef:

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

Потокове передавання

{  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 — див. Команди зі скісною рискою.

Налаштування кількох облікових записів

Запускайте кількох ботів 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-з’єднання, клієнт API та кеш токенів, пов’язані з appId. Рядки журналу позначаються ідентифікатором облікового запису-власника, щоб діагностичні дані залишалися відокремленими під час запуску кількох ботів через один Gateway.

Додайте другого бота через CLI:

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

Групові чати

Підтримка груп використовує 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 перевизначає ці стандартні значення для однієї групи. Налаштування групи:

commandLevel приймає:

Старі записи QQBot toolPolicy більше не використовуються. Виконайте openclaw doctor --fix, щоб перенести їх до tools.

Режими активації: mention і always. requireMention: true відповідає mention; requireMention: false відповідає always. Перевизначення активації на рівні сеансу, якщо воно є, має пріоритет над конфігурацією.

Вхідна черга створюється окремо для кожного співрозмовника. Для групових співрозмовників установлено більший ліміт черги (50 проти 20 для прямих співрозмовників); коли черга заповнена, повідомлення бота витісняються раніше за повідомлення людей, а серії звичайних групових повідомлень об’єднуються в одне звернення із зазначенням авторів. Команди зі скісною рискою виконуються по черзі незалежно від пакетного об’єднання.

Голос (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 каналу/глобальної конфігурації.

Стандартний час очікування запитів STT становить 60 секунд. Специфічний для Plugin STT використовує вибране перевизначення models.providers.<id>.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

Формати цілей

Команди зі скісною рискою

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

Додайте ? до будь-якої команди, щоб отримати довідку з використання (наприклад, /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 МіБ або більше використовують кінцеві точки QQ для часткового передавання; менші корисні навантаження та джерела у вигляді віддалених URL/Base64 використовують API одноразового передавання.
• Якщо гаряче оновлення перериває роботу Gateway до завершення запису openclaw.json, під час наступного запуску плагін відновлює останні відомі appId / clientSecret для цього облікового запису з внутрішнього знімка (ніколи не перезаписуючи навмисну зміну конфігурації), тому повторне сканування QR-коду не потрібне.

Усунення несправностей

• Gateway не запускається / немає вхідних повідомлень: переконайтеся, що appId і clientSecret правильні, а бот увімкнений на QQ Open Platform. Відсутні облікові дані відображаються як «QQBot not configured (missing appId or clientSecret)».
• Налаштування за допомогою --token-file усе ще відображається як неналаштоване: --token-file лише задає AppSecret. appId усе одно потрібно задати в конфігурації або QQBOT_APP_ID.
• Пакетні відповіді групи конфліктують: коли черга співрозмовника заповнюється, вхідна черга видаляє повідомлення, створені ботом, раніше за повідомлення людей і об’єднує пакети звичайних (не командних) групових повідомлень в один хід із зазначенням авторства, тому потік повідомлень бота не повинен витісняти повідомлення людей.
• Проактивні повідомлення не надходять: QQ може блокувати повідомлення, ініційовані ботом, якщо користувач не взаємодіяв із ним останнім часом.
• Голос не транскрибується: переконайтеся, що STT налаштовано, а постачальник доступний.

Пов’язані матеріали

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