QQ-бот

​

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

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

​

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

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecret: "YOUR_APP_SECRET",
    },
  },
}

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecretFile: "/path/to/qqbot-secret.txt",
    },
  },
}

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

​

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

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "111111111",
      clientSecret: "secret-of-bot-1",
      accounts: {
        bot2: {
          enabled: true,
          appId: "222222222",
          clientSecret: "secret-of-bot-2",
        },
      },
    },
  },
}

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

​

Групові чати

{
  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.",
        },
      },
    },
  },
}

​

Голос (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" },
            },
          },
        },
      },
    },
  },
}

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

​

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

​

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

​

Медіафайли та сховище

• Вхідні, вихідні медіафайли та медіафайли мосту 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 налаштовано, а постачальник доступний.

​

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

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