QQ-бот - OpenClaw

QQ Bot подключается к OpenClaw через официальный QQ Bot API (WebSocket gateway). Plugin поддерживает личные C2C-чаты, групповые @сообщения и сообщения в каналах гильдий с мультимедиа (изображения, голос, видео, файлы). Статус: загружаемый Plugin. Личные сообщения, групповые чаты, каналы гильдий и мультимедиа поддерживаются. Реакции и треды не поддерживаются.

Установка

Установите QQ Bot перед настройкой:

openclaw plugins install @openclaw/qqbot

Настройка

Перейдите на QQ Open Platform и отсканируйте QR-код с помощью QQ на телефоне, чтобы зарегистрироваться или войти.
Нажмите Create Bot, чтобы создать нового 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 через 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,
          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 переопределяет эти значения для одной группы. Настройки группы включают:

requireMention: требовать @упоминание перед тем, как бот ответит. По умолчанию: true.
commandLevel: управлять тем, какие встроенные слэш-команды могут выполняться в группах. По умолчанию: all, что сохраняет прежнее поведение групп QQBot, когда настройка опущена.
ignoreOtherMentions: отбрасывать сообщения, в которых упоминают кого-то еще, но не бота.
historyLimit: сохранять последние групповые сообщения без упоминания как контекст для следующего хода с упоминанием. Установите 0, чтобы отключить.
tools: разрешать/запрещать инструменты для всей группы.
toolsBySender: переопределения групповых инструментов для отдельных отправителей; см. Группы.
name: удобная метка, используемая в журналах и контексте группы.
prompt: prompt поведения для отдельной группы, добавляемый к контексту агента.

commandLevel принимает:

all: оставить распознанные встроенные команды доступными, как раньше. Некоторые команды могут оставаться скрытыми из меню, но авторизованные пользователи по-прежнему могут запускать их в группе.
safety: разрешить обычные команды совместной работы, такие как /help, /btw и /stop; попросить пользователей запускать чувствительные команды, такие как /config, /tools и /bash, в личном чате.
strict: разрешить только элементы управления групповой сессией, необходимые для строгой работы группы. /stop по-прежнему остается срочной командой, чтобы авторизованный отправитель мог прервать активный запуск.

Старые записи QQBot toolPolicy выведены из использования. Запустите openclaw doctor --fix, чтобы перенести их в tools. Режимы активации: mention и always. requireMention: true соответствует mention; requireMention: false соответствует always. Переопределение активации на уровне сессии, если оно есть, имеет приоритет над конфигурацией. Входящая очередь ведется отдельно для каждого peer. Групповые peer получают больший лимит очереди, при заполнении сохраняют человеческие сообщения впереди сообщений, написанных ботом, и объединяют всплески обычных групповых сообщений в один атрибутированный ход. Слэш-команды по-прежнему выполняются по одной.

Голос (STT / TTS)

STT и TTS поддерживают двухуровневую конфигурацию с приоритетным fallback:

Настройка	Специфично для Plugin	Fallback фреймворка
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, полученный Bot A, нельзя использовать для отправки сообщений через Bot B.

Слэш-команды

Встроенные команды, перехватываемые перед очередью ИИ:

Команда	Описание
`/bot-ping`	Тест задержки
`/bot-version`	Показать версию фреймворка OpenClaw
`/bot-help`	Перечислить все команды
`/bot-me`	Показать QQ user 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, а затем используют fallback к allowFrom. Запуск административной команды в группе возвращает подсказку, а не молча отбрасывается. Когда одобрения exec в QQ Bot используют стандартный fallback в тот же чат, нажатия нативных кнопок одобрения следуют тому же явному allowlist команд без wildcard. Чтобы предоставить доступ только к одобрениям без более широкого доступа к командам, настройте channels.qqbot.execApprovals.approvers.

Архитектура движка

QQ Bot поставляется как самодостаточный движок внутри Plugin:

Каждый аккаунт владеет изолированным стеком ресурсов (соединение WebSocket, клиент API, кэш токенов, корень хранилища медиа), привязанным к appId. Аккаунты никогда не разделяют входящее/исходящее состояние.
Логгер для нескольких аккаунтов помечает строки журнала аккаунтом-владельцем, чтобы диагностика оставалась разделяемой, когда вы запускаете несколько ботов под одним Gateway.
Входящие, исходящие пути и пути моста Gateway используют один корень медианагрузки в ~/.openclaw/media, поэтому загрузки, скачивания и кэши транскодирования попадают в один защищенный каталог вместо дерева для каждой подсистемы.
Доставка rich 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), отображаются как нативные prompts 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 настроен и провайдер доступен.

​Установка

​Настройка

​Конфигурация

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

​Групповые чаты

​Голос (STT / TTS)

​Целевые форматы

​Слэш-команды

​Архитектура движка

​Онбординг по QR-коду

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

​Связанные материалы