---
read_when:
    - Ви хочете підключити OpenClaw до QQ
    - Вам потрібно налаштувати облікові дані QQ Bot
    - Вам потрібна підтримка групового або приватного чату QQ Bot
summary: Налаштування, конфігурація та використання QQ Bot
title: QQ bot
x-i18n:
    generated_at: "2026-04-28T02:07:56Z"
    model: gpt-5.4
    provider: openai
    source_hash: aefece6b05bb16d5c4f588bf7af4fd710b5f98aab0dbed8221490c46bf3f379c
    source_path: channels/qqbot.md
    workflow: 15
---

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

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

## Вбудований плагін

Поточні випуски OpenClaw постачаються з QQ Bot, тому у звичайних пакетних збірках не потрібен окремий крок `openclaw plugins install`.

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

1. Перейдіть на [QQ Open Platform](https://q.qq.com/) і відскануйте QR-код у QQ на телефоні, щоб зареєструватися / увійти.
2. Натисніть **Create Bot**, щоб створити нового QQ bot.
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",
    },
  },
}
```

Примітки:

- Підстановка зі змінних середовища застосовується лише до облікового запису QQ Bot за замовчуванням.
- `openclaw channels add --channel qqbot --token-file ...` передає лише AppSecret; AppID уже має бути заданий у конфігурації або в `QQBOT_APP_ID`.
- `clientSecret` також приймає вхід SecretRef, а не лише рядок у відкритому вигляді.

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

Запустіть кілька QQ bot в одному екземплярі 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,
          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`. Якщо є перевизначення активації на рівні сесії, воно має пріоритет над конфігурацією.

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

### Голос (STT / TTS)

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

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

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

## Slash commands

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

| Команда        | Опис                                                                                                              |
| -------------- | ----------------------------------------------------------------------------------------------------------------- |
| `/bot-ping`    | Перевірка затримки                                                                                                 |
| `/bot-version` | Показати версію фреймворку OpenClaw                                                                                |
| `/bot-help`    | Показати список усіх команд                                                                                        |
| `/bot-upgrade` | Показати посилання на інструкцію з оновлення QQBot                                                                |
| `/bot-logs`    | Експортувати нещодавні журнали Gateway як файл                                                                    |
| `/bot-approve` | Схвалити очікувану дію QQ Bot (наприклад, підтвердження вивантаження C2C або групи) через нативний потік. |

Додайте `?` до будь-якої команди, щоб отримати довідку з використання (наприклад, `/bot-upgrade ?`).

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

QQ Bot постачається як самодостатній рушій усередині плагіна:

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

## Онбординг через QR-код

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

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

Запити на схвалення, згенеровані самим ботом (наприклад, потоки "allow this action?", які надає API QQ Bot), відображаються як нативні запити OpenClaw, які можна прийняти через `/bot-approve`, а не відповідати через сирий клієнт QQ.

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

- **Бот відповідає "gone to Mars":** облікові дані не налаштовано або Gateway не запущено.
- **Немає вхідних повідомлень:** перевірте, що `appId` і `clientSecret` правильні, і що бот увімкнений на QQ Open Platform.
- **Повторні відповіді самому собі:** OpenClaw записує індекси вихідних QQ ref як створені ботом і ігнорує вхідні події, у яких поточний `msgIdx` збігається з тим самим обліковим записом бота. Це запобігає циклам echo на платформі й водночас дозволяє користувачам цитувати або відповідати на попередні повідомлення бота.
- **Налаштування з `--token-file` усе ще показує, що не налаштовано:** `--token-file` задає лише AppSecret. Вам усе ще потрібен `appId` у конфігурації або `QQBOT_APP_ID`.
- **Проактивні повідомлення не надходять:** QQ може перехоплювати повідомлення, ініційовані ботом, якщо користувач не взаємодіяв нещодавно.
- **Голос не транскрибується:** переконайтеся, що STT налаштовано і провайдер доступний.

## Пов’язане

- [Сполучення](/uk/channels/pairing)
- [Групи](/uk/channels/groups)
- [Усунення несправностей каналу](/uk/channels/troubleshooting)
