Regional platforms

QQ бот

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

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

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

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

openclaw plugins install @openclaw/qqbot

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

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

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

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

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

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

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

openclaw channels add
openclaw 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 Env 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,
          historyLimit: 50,
          toolPolicy: "restricted",
        },
        GROUP_OPENID: {
          name: "Release room",
          requireMention: false,
          ignoreOtherMentions: true,
          historyLimit: 20,
          prompt: "Keep replies short and operational.",
        },
      },
    },
  },
}

groups["*"] задає стандартні параметри для кожної групи, а конкретний запис groups.GROUP_OPENID перевизначає ці параметри для однієї групи. Налаштування групи включають:

requireMention: вимагати @згадку перед тим, як бот відповість. За замовчуванням: true.
ignoreOtherMentions: відкидати повідомлення, які згадують когось іншого, але не бота.
historyLimit: зберігати нещодавні групові повідомлення без згадок як контекст для наступного ходу зі згадкою. Установіть 0, щоб вимкнути.
toolPolicy: full, restricted або none для інструментів у межах групи.
name: зрозуміла мітка, що використовується в журналах і контексті групи.
prompt: підказка поведінки для окремої групи, додана до контексту агента.

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

Вхідна черга створюється для кожного однорангового учасника. Групові учасники отримують більший ліміт черги, зберігають людські повідомлення попереду повідомлень, написаних ботом, коли черга заповнена, і об'єднують сплески звичайних групових повідомлень в один атрибутований хід. Slash-команди все одно виконуються по одній.

Голос (STT / TTS)

Підтримка STT і TTS має дворівневу конфігурацію з пріоритетним резервним варіантом:

Параметр	Специфічно для Plugin	Резервний варіант фреймворку
STT	`channels.qqbot.stt`	`tools.media.audio.models[0]`
TTS	`channels.qqbot.tts`, `channels.qqbot.accounts.<id>.tts`	`messages.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

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

Формат	Опис
`qqbot:c2c:OPENID`	Приватний чат (C2C)
`qqbot:group:GROUP_OPENID`	Груповий чат
`qqbot:channel:CHANNEL_ID`	Канал гільдії

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

Slash-команди

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

Команда	Опис
`/bot-ping`	Тест затримки
`/bot-version`	Показати версію фреймворку OpenClaw
`/bot-help`	Перелічити всі команди
`/bot-me`	Показати QQ 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 постачається як самодостатній рушій усередині Plugin:

Кожен обліковий запис володіє ізольованим стеком ресурсів (WebSocket-з'єднання, API-клієнт, кеш токенів, корінь сховища медіа), ключованим за appId. Облікові записи ніколи не спільно використовують вхідний/вихідний стан.
Журналювач для кількох облікових записів позначає рядки журналу обліковим записом-власником, щоб діагностика залишалася роздільною, коли ви запускаєте кілька ботів під одним Gateway.
Вхідні, вихідні та bridge-шляхи Gateway спільно використовують один корінь медіанавантажень у ~/.openclaw/media, тому завантаження, вивантаження та кеші транскодування потрапляють в один захищений каталог замість дерева для кожної підсистеми.
Доставка розширених медіа проходить через один шлях sendMedia для цілей C2C і груп. Локальні файли та буфери, що перевищують поріг великих файлів, використовують chunked upload endpoints QQ, тоді як менші навантаження використовують одноразовий media API.
Облікові дані можна резервно копіювати та відновлювати як частину стандартних знімків облікових даних OpenClaw; рушій повторно приєднує стек ресурсів кожного облікового запису під час відновлення без потреби в новій парі QR-кодом.

Онбординг за QR-кодом

Як альтернативу ручному вставленню AppID:AppSecret, рушій підтримує потік онбордингу за QR-кодом для зв'язування QQ Bot з OpenClaw:

Запустіть шлях налаштування QQ Bot (наприклад, openclaw channels add --channel qqbot) і виберіть потік QR-коду, коли з'явиться запит.
Відскануйте згенерований QR-код телефонним застосунком, прив'язаним до цільового QQ Bot.
Схваліть сполучення на телефоні. OpenClaw зберігає повернуті облікові дані в credentials/ у правильній області облікового запису.

Запити на схвалення, згенеровані самим ботом (наприклад, потоки "дозволити цю дію?", надані 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 налаштовано, а провайдер доступний.

QQ бот

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

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

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

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

Групові чати

Голос (STT / TTS)

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

Slash-команди

Архітектура рушія

Онбординг за QR-кодом

Усунення неполадок

Пов'язане

Ask OpenClaw

# Установлення

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

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

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

# Групові чати

# Голос (STT / TTS)

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

# Slash-команди

# Архітектура рушія

# Онбординг за QR-кодом

# Усунення неполадок

# Пов'язане

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

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

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

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

Групові чати

Голос (STT / TTS)

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

Slash-команди

Архітектура рушія

Онбординг за QR-кодом

Усунення неполадок

Пов'язане