Bot QQ

QQ Bot si connette a OpenClaw tramite l'API ufficiale di QQ Bot (gateway WebSocket). La chat privata C2C e le menzioni @ nei gruppi sono i tipi di chat principali, con contenuti multimediali avanzati (immagini, messaggi vocali, video, file). I messaggi nei canali delle gilde sono supportati solo per testo e immagini tramite URL remoti; messaggi vocali, video, caricamenti di file e immagini locali/Base64 non sono disponibili nei canali delle gilde. Reazioni e thread non sono supportati in alcun contesto.

Stato: plugin ufficiale scaricabile.

Installazione

openclaw plugins install @openclaw/qqbot

Configurazione iniziale

1. Vai alla Piattaforma aperta QQ ed esegui la scansione del codice QR con QQ sul telefono per registrarti o accedere.
2. Fai clic su Create Bot per creare un nuovo bot QQ.
3. Individua AppID e AppSecret nella pagina delle impostazioni del bot e copiali.

4. Aggiungi il canale:

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

5. Riavvia il Gateway.

Configurazione interattiva:

openclaw channels add

La procedura guidata offre anche l'associazione tramite codice QR come alternativa all'inserimento manuale di AppID/AppSecret: esegui la scansione del codice con l'app del telefono collegata al QQ Bot di destinazione per completare l'associazione. OpenClaw salva le credenziali restituite nell'ambito di configurazione dell'account.

Configurazione

Configurazione minima:

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

Variabili d'ambiente dell'account predefinito (solo account di primo livello):

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

AppSecret basato su file:

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

AppSecret SecretRef da variabile d'ambiente:

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

Note:

• 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 in testo normale, un percorso di file (clientSecretFile) oppure un oggetto SecretRef strutturato.
• Le stringhe marcatore obsolete secretref:... / secretref-env:... vengono rifiutate per clientSecret; usa invece un oggetto SecretRef strutturato.

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 passa per impostazione predefinita a allowlist quando allowFrom contiene una voce concreta (non un carattere jolly), altrimenti usa open. groupPolicy passa per impostazione predefinita a allowlist quando groupAllowFrom o allowFrom contiene una voce concreta, altrimenti usa open.
• I comandi slash con "Autorizzazione: elenco consentiti" richiedono una voce esplicita senza caratteri jolly in allowFrom (o in groupAllowFrom per le invocazioni di gruppo), indipendentemente da dmPolicy / groupPolicy: consulta Comandi slash.

Configurazione multi-account

Esegui più bot QQ in una singola istanza di OpenClaw:

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

Ogni account dispone di una connessione WebSocket, un client API e una cache dei token isolati, identificati da appId. Le righe dei log sono contrassegnate con l'ID dell'account proprietario, in modo che la diagnostica rimanga separabile quando esegui più bot sotto un unico Gateway.

Aggiungi un secondo bot tramite CLI:

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

Chat di gruppo

Il supporto dei gruppi utilizza gli OpenID dei gruppi QQ, non i nomi visualizzati. Aggiungi il bot a un gruppo, quindi menzionalo oppure configura il gruppo per funzionare senza menzione.

{  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["*"] imposta i valori predefiniti per ogni gruppo; una voce concreta groups.GROUP_OPENID sostituisce tali valori predefiniti per un singolo gruppo. Impostazioni dei gruppi:

commandLevel accetta:

Le vecchie voci toolPolicy di QQBot sono state ritirate. Esegui openclaw doctor --fix per migrarle a tools.

Le modalità di attivazione sono mention e always. requireMention: true corrisponde a mention; requireMention: false corrisponde a always. Un'eventuale sostituzione dell'attivazione a livello di sessione ha la precedenza sulla configurazione.

La coda in ingresso è separata per interlocutore. Gli interlocutori di gruppo hanno un limite di coda maggiore (50 rispetto a 20 per gli interlocutori diretti), espellono i messaggi generati dal bot prima di quelli umani quando è piena e uniscono raffiche di normali messaggi di gruppo in un unico turno con attribuzione. I comandi slash vengono eseguiti uno alla volta, indipendentemente da qualsiasi gruppo di messaggi unito.

Voce (STT / TTS)

Il supporto STT e TTS offre una configurazione a due livelli con ripiego in base alla priorità:

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

Imposta enabled: false su uno dei due per disabilitarlo. Le sostituzioni TTS a livello di account usano la stessa struttura di messages.tts e vengono unite in profondità alla configurazione TTS del canale/globale.

Per impostazione predefinita, le richieste STT scadono dopo 60 secondi. Lo STT specifico del Plugin usa il valore sostitutivo models.providers.<id>.timeoutSeconds selezionato. Lo STT audio del framework usa tools.media.audio.models[0].timeoutSeconds, quindi tools.media.audio.timeoutSeconds e infine il valore sostitutivo del fornitore selezionato.

Gli allegati vocali QQ in ingresso vengono esposti agli agenti come metadati multimediali audio, mantenendo al contempo i file vocali non elaborati fuori da MediaPaths generico. [[audio_as_voice]] in una risposta di testo semplice sintetizza il TTS e invia un messaggio vocale QQ nativo quando il TTS è configurato.

Anche il comportamento di caricamento/transcodifica dell'audio in uscita può essere regolato con channels.qqbot.audioFormatPolicy:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

Formati di destinazione

Comandi slash

Comandi integrati intercettati prima della coda dell'IA:

Aggiungi ? a qualsiasi comando per ottenere informazioni sull'utilizzo (ad esempio /bot-upgrade ?).

I comandi con "Autorizzazione: elenco consentiti" richiedono inoltre che l'openid del mittente sia presente in un elenco allowFrom esplicito e senza caratteri jolly (groupAllowFrom ha la precedenza per i comandi impartiti dai gruppi, con ripiego su allowFrom). Un carattere jolly allowFrom: ["*"] consente la chat ma non questi comandi. L'esecuzione di uno di essi al di fuori della chat privata o senza autorizzazione restituisce un suggerimento anziché ignorare silenziosamente il messaggio.

/bot-me, /bot-version e /bot-upgrade sono disponibili solo nelle chat private, ma non richiedono l'elenco consentito: qualsiasi mittente C2C può eseguirli.

Quando le approvazioni di esecuzione di QQ Bot usano il fallback predefinito alla stessa chat, i clic sui pulsanti nativi di approvazione seguono lo stesso elenco consentito esplicito dei comandi senza caratteri jolly. Per concedere l'accesso alle sole approvazioni senza un accesso più ampio ai comandi, configura channels.qqbot.execApprovals.approvers. Le approvazioni native di esecuzione sono abilitate per impostazione predefinita.

Contenuti multimediali e archiviazione

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

Risoluzione dei problemi

• Il Gateway non si avvia / nessun messaggio in entrata: verifica che appId e clientSecret siano corretti e che il bot sia abilitato sulla QQ Open Platform. Una credenziale mancante viene segnalata come "QQBot non configurato (appId o clientSecret mancante)".
• La configurazione con --token-file risulta ancora non configurata: --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 interlocutore si riempie, la coda in entrata elimina i messaggi creati dai bot prima di quelli umani e riunisce le raffiche di normali messaggi di gruppo (non comandi) in un unico turno con attribuzione, quindi un flusso intenso di messaggi dei bot non dovrebbe impedire l'elaborazione dei messaggi umani.
• I messaggi proattivi non arrivano: QQ può bloccare i messaggi avviati dal bot se l'utente non ha interagito di recente.
• La voce non viene trascritta: assicurati che STT sia configurato e che il fornitore sia raggiungibile.

Contenuti correlati

• Associazione
• Gruppi
• Risoluzione dei problemi dei canali