QQ-бот

QQ Bot підключається до OpenClaw через офіційний API QQ Bot (WebSocket Gateway). Основними типами чатів є приватні чати 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 через 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.

Політика доступу

• allowFrom / groupAllowFrom визначають, хто може спілкуватися з ботом у контекстах C2C / груп. dmPolicy / groupPolicy (open | allowlist | disabled) керують режимом застосування обмежень. Стандартним значенням dmPolicy стає allowlist, щойно allowFrom містить конкретний запис (не шаблон), інакше використовується open. Стандартним значенням groupPolicy стає allowlist, щойно groupAllowFrom або allowFrom містить конкретний запис, інакше використовується open.
• Команди зі скісною рискою з «Автентифікація: список дозволених» потребують явного запису без шаблону в 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 MiB або більше використовують кінцеві точки QQ для завантаження частинами; менші дані та джерела у вигляді віддалених URL/Base64 використовують API одноразового завантаження.
• Якщо гаряче оновлення перерве роботу Gateway до завершення запису openclaw.json, під час наступного запуску Plugin відновить останні відомі appId / clientSecret для цього облікового запису з внутрішнього знімка (ніколи не перезаписуючи навмисну зміну конфігурації), тому повторно сканувати QR-код не потрібно.

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

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

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

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