bot QQ

​

Installazione

openclaw plugins install @openclaw/qqbot

​

Configurazione iniziale

1. Accedere alla Piattaforma aperta QQ e scansionare il codice QR con QQ sul telefono per registrarsi o accedere.
2. Fare clic su Create Bot per creare un nuovo bot QQ.
3. Individuare AppID e AppSecret nella pagina delle impostazioni del bot e copiarli.

4. Aggiungere il canale:

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

5. Riavviare il Gateway.

openclaw channels add

​

Configurazione

{
  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 ... imposta solo AppSecret; appId deve essere già impostato nella configurazione o in QQBOT_APP_ID.
• clientSecret accetta una stringa di testo non crittografato, un percorso di file (clientSecretFile) o un oggetto SecretRef strutturato.
• Le stringhe marcatore legacy secretref:... / secretref-env:... vengono rifiutate per clientSecret; utilizzare invece un oggetto SecretRef strutturato.

​

Streaming

{
  channels: {
    qqbot: {
      streaming: {
        mode: "partial", // streaming a blocchi: "partial" (predefinito) oppure "off"
        nativeTransport: true, // usa l'API C2C stream_messages ufficiale di QQ per i messaggi diretti
      },
    },
  },
}

• streaming.mode: "off" disabilita lo streaming a blocchi per l’account.
• streaming.nativeTransport: true trasmette in streaming le risposte C2C (messaggi diretti) tramite l’API ufficiale stream_messages di QQ; le destinazioni di gruppo/canale non sono interessate.
• I valori scalari legacy streaming: true|false e la chiave streaming.c2cStreamApi vengono migrati a questa struttura tramite openclaw doctor --fix.
• /bot-streaming on|off attiva o disattiva la stessa configurazione da un messaggio diretto.

​

Criteri di accesso

• allowFrom / groupAllowFrom determinano chi può comunicare con il bot nei contesti C2C / di gruppo. dmPolicy / groupPolicy (open | allowlist | disabled) controllano la modalità di applicazione. dmPolicy assume come valore predefinito allowlist quando allowFrom contiene una voce concreta (non jolly), altrimenti open. groupPolicy assume come valore predefinito allowlist quando groupAllowFrom o allowFrom contiene una voce concreta, altrimenti open.
• I comandi slash “Auth: allowlist” richiedono una voce esplicita non jolly in allowFrom (o in groupAllowFrom per le invocazioni di gruppo), indipendentemente da dmPolicy / groupPolicy; vedere Comandi slash.

​

Configurazione con più account

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

​

Chat di gruppo

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

​

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

​

Formati di destinazione

​

Comandi slash

​

Contenuti multimediali e archiviazione

• I contenuti multimediali in entrata, in uscita e del bridge del Gateway condividono un’unica radice dei payload in ~/.openclaw/media/qqbot (rispettando OPENCLAW_HOME quando impostato), in modo che caricamenti, download e cache di transcodifica rimangano in un’unica directory protetta.
• La distribuzione di contenuti multimediali avanzati alle destinazioni C2C e di gruppo avviene tramite un unico percorso sendMedia. I file locali e i buffer in memoria di almeno 5 MiB utilizzano gli endpoint di caricamento a blocchi di QQ; i payload più piccoli e le sorgenti URL remote/Base64 utilizzano l’API di caricamento in un’unica operazione.
• Se un aggiornamento a caldo interrompe il Gateway prima che termini la scrittura di openclaw.json, al successivo avvio il plugin ripristina l’ultimo appId / clientSecret noto per quell’account da uno snapshot interno (senza mai sovrascrivere una modifica intenzionale della configurazione), pertanto non è necessario scansionare nuovamente il codice QR.

​

Risoluzione dei problemi

• Il Gateway non si avvia / nessun messaggio in entrata: verificare che appId e clientSecret siano corretti e che il bot sia abilitato sulla QQ Open Platform. Se manca una credenziale, viene visualizzato “QQBot non configurato (appId o clientSecret mancante)”.
• La configurazione con --token-file risulta ancora non completata: --token-file imposta solo l’AppSecret. appId deve comunque essere impostato nella configurazione o in QQBOT_APP_ID.
• Le risposte di gruppo a raffica entrano in conflitto: quando la coda di un peer si riempie, la coda in entrata rimuove i messaggi generati dai bot prima di quelli umani e unisce le raffiche di normali messaggi di gruppo (non comandi) in un unico turno attribuito, pertanto un flusso intenso di messaggi dei bot non dovrebbe impedire l’elaborazione dei messaggi umani.
• I messaggi proattivi non arrivano: QQ potrebbe bloccare i messaggi avviati dal bot se l’utente non ha interagito di recente.
• La voce non viene trascritta: assicurarsi che l’STT sia configurato e che il provider sia raggiungibile.

​

Contenuti correlati

• Associazione
• Gruppi
• Risoluzione dei problemi dei canali