Бот QQ

QQ Bot подключается к OpenClaw через официальный API QQ Bot (Gateway WebSocket). Основными типами чатов являются личные чаты C2C и @-упоминания в группах; поддерживаются различные медиафайлы (изображения, голосовые сообщения, видео, файлы). Для сообщений в каналах гильдий поддерживаются только текст и изображения по удалённым URL; голосовые сообщения, видео, загрузка файлов и локальные изображения или изображения в формате Base64 в каналах гильдий недоступны. Реакции и ветки не поддерживаются нигде.

Статус: официальный загружаемый плагин.

Установка

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

Вместо ручного ввода AppID/AppSecret мастер также предлагает привязку по QR-коду: отсканируйте код в мобильном приложении, связанном с нужным 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.

Потоковая передача

{  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 — см. Слеш-команды.

Настройка нескольких учётных записей

Запустите несколько ботов 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 секунд. 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, при следующем запуске плагин восстанавливает последние известные appId / clientSecret для этой учётной записи из внутреннего снимка (никогда не перезаписывая намеренное изменение конфигурации), поэтому повторное сканирование QR-кода не требуется.

Устранение неполадок

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

См. также

• Сопряжение
• Группы
• Устранение неполадок каналов