bot QQ

QQ Bot connecte OpenClaw via l’API officielle QQ Bot (Gateway WebSocket). Le Plugin prend en charge les chats privés C2C, les @messages de groupe et les messages de canal de guilde avec des médias enrichis (images, voix, vidéo, fichiers).

Statut : Plugin téléchargeable. Les messages directs, les chats de groupe, les canaux de guilde et les médias sont pris en charge. Les réactions et les fils ne sont pas pris en charge.

Installation

Installez QQ Bot avant la configuration :

openclaw plugins install @openclaw/qqbot

Configuration initiale

1. Accédez à la QQ Open Platform et scannez le code QR avec votre téléphone QQ pour vous inscrire / vous connecter.
2. Cliquez sur Create Bot pour créer un nouveau bot QQ.
3. Trouvez AppID et AppSecret sur la page des paramètres du bot et copiez-les.

AppSecret n’est pas stocké en clair — si vous quittez la page sans l’enregistrer, vous devrez en régénérer un nouveau.

4. Ajoutez le canal :

openclaw channels add --channel qqbot --token "AppID:AppSecret"

5. Redémarrez le Gateway.

Chemins de configuration interactive :

openclaw channels addopenclaw configure --section channels

Configurer

Configuration minimale :

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

Variables d’environnement du compte par défaut :

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

AppSecret adossé à un fichier :

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

AppSecret Env SecretRef :

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecret: { source: "env", provider: "default", id: "QQBOT_CLIENT_SECRET" },    },  },}

Notes :

• Le repli vers l’environnement s’applique uniquement au compte QQ Bot par défaut.
• openclaw channels add --channel qqbot --token-file ... fournit uniquement l’AppSecret ; l’AppID doit déjà être défini dans la configuration ou dans QQBOT_APP_ID.
• clientSecret accepte également une entrée SecretRef, pas seulement une chaîne en clair.
• Les anciennes chaînes de marqueur secretref:/... ne sont pas des valeurs clientSecret valides ; utilisez des objets SecretRef structurés comme dans l’exemple ci-dessus.

Configuration multi-compte

Exécutez plusieurs bots QQ sous une seule instance OpenClaw :

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

Chaque compte lance sa propre connexion WebSocket et conserve un cache de jetons indépendant (isolé par appId).

Ajoutez un second bot via la CLI :

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

Chats de groupe

La prise en charge des chats de groupe QQ Bot utilise les OpenIDs de groupe QQ, pas les noms d’affichage. Ajoutez le bot à un groupe, puis mentionnez-le ou configurez le groupe pour s’exécuter sans mention.

{  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["*"] définit les valeurs par défaut pour chaque groupe, et une entrée groups.GROUP_OPENID concrète remplace ces valeurs par défaut pour un groupe. Les paramètres de groupe comprennent :

• requireMention : exiger une @mention avant que le bot ne réponde. Par défaut : true.
• commandLevel : contrôler quelles commandes slash intégrées peuvent s’exécuter dans les groupes. Par défaut : all, ce qui préserve le comportement de groupe QQBot préexistant lorsque le paramètre est omis.
• ignoreOtherMentions : ignorer les messages qui mentionnent quelqu’un d’autre mais pas le bot.
• historyLimit : conserver les messages de groupe récents sans mention comme contexte pour le prochain tour mentionné. Définissez 0 pour désactiver.
• tools : autoriser/refuser des outils pour l’ensemble du groupe.
• toolsBySender : remplacements d’outils de groupe par expéditeur ; consultez Groupes.
• name : libellé convivial utilisé dans les journaux et le contexte de groupe.
• prompt : invite de comportement par groupe ajoutée au contexte de l’agent.

commandLevel accepte :

• all : garder les commandes intégrées reconnues disponibles comme auparavant. Certaines commandes peuvent rester masquées dans les menus, mais les utilisateurs autorisés peuvent toujours les exécuter dans le groupe.
• safety : autoriser les commandes de collaboration courantes comme /help, /btw et /stop ; demander aux utilisateurs d’exécuter les commandes sensibles comme /config, /tools et /bash dans un chat privé.
• strict : autoriser uniquement les contrôles de session de groupe nécessaires à un fonctionnement strict du groupe. /stop reste urgent afin qu’un expéditeur autorisé puisse interrompre une exécution active.

Les anciennes entrées QQBot toolPolicy sont retirées. Exécutez openclaw doctor --fix pour les migrer vers tools.

Les modes d’activation sont mention et always. requireMention: true correspond à mention ; requireMention: false correspond à always. Un remplacement d’activation au niveau de la session, lorsqu’il est présent, prévaut sur la configuration.

La file entrante est par pair. Les pairs de groupe disposent d’un plafond de file plus élevé, conservent les messages humains avant les bavardages rédigés par le bot lorsque la file est pleine, et fusionnent les rafales de messages de groupe normaux en un seul tour attribué. Les commandes slash s’exécutent toujours une par une.

Voix (STT / TTS)

La prise en charge de STT et TTS utilise une configuration à deux niveaux avec repli prioritaire :

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

Définissez enabled: false sur l’un ou l’autre pour désactiver. Les remplacements TTS au niveau du compte utilisent la même forme que messages.tts et sont fusionnés en profondeur par-dessus la configuration TTS du canal/globale.

Les pièces jointes vocales QQ entrantes sont exposées aux agents comme métadonnées de média audio tout en gardant les fichiers vocaux bruts hors des MediaPaths génériques. Les réponses en texte brut [[audio_as_voice]] synthétisent le TTS et envoient un message vocal QQ natif lorsque TTS est configuré.

Le comportement d’envoi/transcodage audio sortant peut également être ajusté avec channels.qqbot.audioFormatPolicy :

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

Formats cibles

Chaque bot a son propre ensemble d’OpenIDs utilisateur. Un OpenID reçu par le bot A ne peut pas être utilisé pour envoyer des messages via le bot B.

Commandes slash

Commandes intégrées interceptées avant la file d’IA :

Ajoutez ? à n’importe quelle commande pour obtenir l’aide d’utilisation (par exemple /bot-upgrade ?).

Les commandes d’administration (/bot-me, /bot-upgrade, /bot-logs, /bot-clear-storage, /bot-streaming, /bot-approve) sont réservées aux messages directs et exigent que l’openid de l’expéditeur figure dans une liste allowFrom explicite sans joker. Un joker allowFrom: ["*"] autorise le chat mais n’accorde pas l’accès aux commandes d’administration. Les messages de groupe sont d’abord comparés à groupAllowFrom, puis se replient sur allowFrom. L’exécution d’une commande d’administration dans un groupe renvoie une indication au lieu d’être ignorée silencieusement.

Lorsque les approbations exec de QQ Bot utilisent le repli par défaut dans le même chat, les clics sur les boutons d’approbation natifs suivent la même liste d’autorisation de commandes explicite sans joker. Pour accorder un accès limité aux approbations sans accès plus large aux commandes, configurez channels.qqbot.execApprovals.approvers.

Architecture du moteur

QQ Bot est livré comme un moteur autonome à l’intérieur du Plugin :

• Chaque compte possède une pile de ressources isolée (connexion WebSocket, client API, cache de jetons, racine de stockage des médias) indexée par appId. Les comptes ne partagent jamais l’état entrant/sortant.
• Le journaliseur multi-compte étiquette les lignes de journal avec le compte propriétaire afin que les diagnostics restent séparables lorsque vous exécutez plusieurs bots sous un seul Gateway.
• Les chemins entrants, sortants et de pont Gateway partagent une seule racine de charge utile média sous ~/.openclaw/media, de sorte que les envois, téléchargements et caches de transcodage aboutissent dans un répertoire protégé unique au lieu d’un arbre par sous-système.
• La livraison de médias enrichis passe par un seul chemin sendMedia pour les cibles C2C et de groupe. Les fichiers locaux et les tampons au-dessus du seuil de fichier volumineux utilisent les points de terminaison d’envoi fragmenté de QQ, tandis que les charges utiles plus petites utilisent l’API média en une seule opération.
• Les identifiants peuvent être sauvegardés et restaurés dans le cadre des instantanés d’identifiants OpenClaw standard ; le moteur rattache la pile de ressources de chaque compte lors de la restauration sans nécessiter une nouvelle paire de codes QR.

Intégration par code QR

Comme alternative au collage manuel de AppID:AppSecret, le moteur prend en charge un flux d’intégration par code QR pour lier un QQ Bot à OpenClaw :

1. Exécutez le chemin de configuration QQ Bot (par exemple openclaw channels add --channel qqbot) et choisissez le flux par code QR lorsque vous y êtes invité.
2. Scannez le code QR généré avec l’application téléphone liée au QQ Bot cible.
3. Approuvez l’association sur le téléphone. OpenClaw conserve les identifiants renvoyés dans credentials/ sous la bonne portée de compte.

Les invites d’approbation générées par le bot lui-même (par exemple, les flux « autoriser cette action ? » exposés par l’API QQ Bot) apparaissent comme des invites OpenClaw natives que vous pouvez accepter avec /bot-approve plutôt qu’en répondant via le client QQ brut.

Dépannage

• Le bot répond « parti sur Mars » : les identifiants ne sont pas configurés ou le Gateway n’est pas démarré.
• Aucun message entrant : vérifiez que appId et clientSecret sont corrects, et que le bot est activé sur la QQ Open Platform.
• Auto-réponses répétées : OpenClaw enregistre les index de référence sortants QQ comme rédigés par le bot et ignore les événements entrants dont le msgIdx actuel correspond à ce même compte de bot. Cela évite les boucles d’écho de la plateforme tout en permettant aux utilisateurs de citer ou de répondre aux messages précédents du bot.
• La configuration avec --token-file apparaît toujours comme non configurée : --token-file définit uniquement l’AppSecret. Vous avez toujours besoin de appId dans la configuration ou de QQBOT_APP_ID.
• Les messages proactifs n’arrivent pas : QQ peut intercepter les messages initiés par le bot si l’utilisateur n’a pas interagi récemment.
• La voix n’est pas transcrite : assurez-vous que le STT est configuré et que le fournisseur est joignable.

Connexe

• Appairage
• Groupes
• Dépannage des canaux