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

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

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

## Вбудований plugin

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

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

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

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

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

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

Установіть `enabled: false` для будь-якого з них, щоб вимкнути його.

Поведінку завантаження/транскодування вихідного аудіо також можна налаштувати через `channels.qqbot.audioFormatPolicy`:

- `sttDirectFormats`
- `uploadDirectFormats`
- `transcodeEnabled`

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

| Формат                     | Опис               |
| -------------------------- | ------------------ |
| `qqbot:c2c:OPENID`         | Приватний чат (C2C) |
| `qqbot:group:GROUP_OPENID` | Груповий чат       |
| `qqbot:channel:CHANNEL_ID` | Канал guild        |

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

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

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

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

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

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

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

- Кожен обліковий запис володіє ізольованим стеком ресурсів (WebSocket-з’єднання, API-клієнт, кеш токенів, корінь медіасховища), прив’язаним до `appId`. Облікові записи ніколи не ділять між собою вхідний/вихідний стан.
- Логер для кількох облікових записів позначає рядки журналу обліковим записом-власником, щоб діагностику можна було розділяти під час запуску кількох ботів під одним Gateway.
- Шляхи вхідних, вихідних повідомлень і мосту Gateway використовують єдиний корінь медіаданих у `~/.openclaw/media`, тож завантаження, вивантаження та кеші транскодування потрапляють в один захищений каталог замість окремого дерева для кожної підсистеми.
- Облікові дані можна резервно копіювати та відновлювати як частину стандартних знімків облікових даних 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/` у межах правильного облікового запису.

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

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

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

## Пов’язане

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