bot QQ

​

Installation

openclaw plugins install @openclaw/qqbot

​

Configuration initiale

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

4. Ajoutez le canal :

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

5. Redémarrez le Gateway.

openclaw channels add

​

Configuration

{
  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 ... définit uniquement l’AppSecret ; appId doit déjà être défini dans la configuration ou dans QQBOT_APP_ID.
• clientSecret accepte une chaîne en texte brut, un chemin de fichier (clientSecretFile) ou un objet SecretRef structuré.
• Les anciennes chaînes de marqueur secretref:... / secretref-env:... sont refusées pour clientSecret ; utilisez plutôt un objet SecretRef structuré.

​

Diffusion en continu

{
  channels: {
    qqbot: {
      streaming: {
        mode: "partial", // diffusion par blocs : "partial" (par défaut) ou "off"
        nativeTransport: true, // utiliser l’API C2C stream_messages officielle de QQ pour les messages privés
      },
    },
  },
}

• streaming.mode: "off" désactive la diffusion par blocs pour le compte.
• streaming.nativeTransport: true diffuse les réponses C2C (messages privés) via l’API officielle stream_messages de QQ ; les cibles de groupe et de canal ne sont pas affectées.
• Les anciennes valeurs scalaires streaming: true|false et la clé streaming.c2cStreamApi sont migrées vers cette structure via openclaw doctor --fix.
• /bot-streaming on|off active ou désactive la même configuration depuis un message privé.

​

Politique d’accès

• allowFrom / groupAllowFrom déterminent qui peut converser avec le bot dans les contextes C2C / de groupe. dmPolicy / groupPolicy (open | allowlist | disabled) contrôlent le mode d’application. dmPolicy prend par défaut la valeur allowlist dès que allowFrom contient une entrée concrète (sans caractère générique), sinon open. groupPolicy prend par défaut la valeur allowlist dès que groupAllowFrom ou allowFrom contient une entrée concrète, sinon open.
• Les commandes slash « Auth: allowlist » exigent une entrée explicite sans caractère générique dans allowFrom (ou groupAllowFrom pour les appels depuis un groupe), indépendamment de dmPolicy / groupPolicy — consultez Commandes slash.

​

Configuration multicomptes

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

​

Conversations de groupe

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

​

Voix (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

​

Formats des cibles

​

Commandes slash

​

Médias et stockage

• Les médias entrants, sortants et transmis par le pont du Gateway partagent une même racine de charge utile sous ~/.openclaw/media/qqbot (en respectant OPENCLAW_HOME lorsqu’elle est définie), afin que les téléversements, téléchargements et caches de transcodage restent dans un même répertoire protégé.
• La livraison de médias enrichis vers les cibles C2C et de groupe passe par un même chemin sendMedia. Les fichiers locaux et les tampons en mémoire de 5 MiB ou plus utilisent les points de terminaison de téléversement segmenté de QQ ; les charges utiles plus petites et les sources par URL distante/Base64 utilisent l’API de téléversement en une seule opération.
• Si une mise à niveau à chaud interrompt le Gateway avant la fin de l’écriture de openclaw.json, le Plugin restaure les dernières valeurs connues de appId / clientSecret pour ce compte à partir d’un instantané interne au prochain démarrage (sans jamais écraser une modification intentionnelle de la configuration), de sorte qu’il n’est pas nécessaire de rescanner le code QR.

​

Dépannage

• Le Gateway ne démarre pas / aucun message entrant : vérifiez que appId et clientSecret sont corrects et que le bot est activé sur QQ Open Platform. L’absence d’un identifiant d’authentification produit le message « QQBot non configuré (appId ou clientSecret manquant) ».
• La configuration avec --token-file apparaît toujours comme non configurée : --token-file définit uniquement l’AppSecret. appId doit toujours être défini dans la configuration ou dans QQBOT_APP_ID.
• Les réponses groupées en rafale entrent en collision : lorsque la file d’attente d’un pair est pleine, la file entrante évince les messages rédigés par des bots avant ceux des humains, et fusionne les rafales de messages de groupe normaux (hors commandes) en un seul tour attribué, afin qu’un flot de bavardages de bots ne prive pas les messages humains de traitement.
• Les messages proactifs n’arrivent pas : QQ peut bloquer 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 la STT est configurée et que le fournisseur est accessible.

​

Pages connexes

• Association
• Groupes
• Dépannage des canaux