Бот 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 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 настроено, а провайдер доступен.

​

См. также

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