Regional platforms

bot di QQ

QQ Bot si connette a OpenClaw tramite l'API ufficiale QQ Bot (gateway WebSocket). Il Plugin supporta chat private C2C, @messaggi di gruppo e messaggi nei canali guild con contenuti multimediali avanzati (immagini, voce, video, file).

Stato: Plugin scaricabile. Sono supportati messaggi diretti, chat di gruppo, canali guild e contenuti multimediali. Reazioni e thread non sono supportati.

Installazione

Installa QQ Bot prima della configurazione:

openclaw plugins install @openclaw/qqbot

Configurazione iniziale

Vai alla QQ Open Platform e scansiona il codice QR con il tuo QQ sul telefono per registrarti / accedere.
Fai clic su Create Bot per creare un nuovo bot QQ.
Trova AppID e AppSecret nella pagina delle impostazioni del bot e copiali.

AppSecret non viene archiviato in chiaro: se lasci la pagina senza salvarlo, dovrai rigenerarne uno nuovo.

Aggiungi il canale:

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

Riavvia il Gateway.

Percorsi di configurazione interattiva:

openclaw channels add
openclaw configure --section channels

Configurare

Configurazione minima:

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

Variabili d'ambiente per l'account predefinito:

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 Env SecretRef:

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

Note:

Il fallback Env si applica solo all'account QQ Bot predefinito.
openclaw channels add --channel qqbot --token-file ... fornisce solo l'AppSecret; l'AppID deve essere già impostato nella configurazione o in QQBOT_APP_ID.
clientSecret accetta anche input SecretRef, non solo una stringa in chiaro.
Le stringhe marcatore legacy secretref:/... non sono valori clientSecret validi; usa oggetti SecretRef strutturati come nell'esempio sopra.

Configurazione multi-account

Esegui più bot QQ sotto una singola istanza 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 avvia la propria connessione WebSocket e mantiene una cache token indipendente (isolata da appId).

Aggiungi un secondo bot tramite CLI:

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

Chat di gruppo

Il supporto alle chat di gruppo di QQ Bot usa gli OpenID dei gruppi QQ, non i nomi visualizzati. Aggiungi il bot a un gruppo, quindi menzionalo o configura il gruppo per funzionare senza una menzione.

{
  channels: {
    qqbot: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["member_openid"],
      groups: {
        "*": {
          requireMention: true,
          historyLimit: 50,
          toolPolicy: "restricted",
        },
        GROUP_OPENID: {
          name: "Release room",
          requireMention: false,
          ignoreOtherMentions: true,
          historyLimit: 20,
          prompt: "Keep replies short and operational.",
        },
      },
    },
  },
}

groups["*"] imposta i valori predefiniti per ogni gruppo, e una voce concreta groups.GROUP_OPENID sovrascrive quei valori predefiniti per un gruppo. Le impostazioni di gruppo includono:

requireMention: richiede una @menzione prima che il bot risponda. Predefinito: true.
ignoreOtherMentions: scarta i messaggi che menzionano qualcun altro ma non il bot.
historyLimit: conserva i messaggi recenti di gruppo senza menzione come contesto per il turno successivo con menzione. Imposta 0 per disabilitare.
toolPolicy: full, restricted o none per gli strumenti con ambito di gruppo.
name: etichetta descrittiva usata nei log e nel contesto del gruppo.
prompt: prompt di comportamento per gruppo aggiunto al contesto dell'agente.

Le modalità di attivazione sono mention e always. requireMention: true corrisponde a mention; requireMention: false corrisponde a always. Un override di attivazione a livello di sessione, quando presente, prevale sulla configurazione.

La coda in ingresso è per peer. I peer di gruppo hanno un limite di coda più alto, mantengono i messaggi umani prima delle conversazioni generate dal bot quando la coda è piena, e uniscono raffiche di normali messaggi di gruppo in un unico turno attribuito. I comandi slash vengono comunque eseguiti uno alla volta.

Voce (STT / TTS)

Il supporto STT e TTS usa una configurazione a due livelli con fallback prioritario:

Impostazione	Specifico del Plugin	Fallback del framework
STT	`channels.qqbot.stt`	`tools.media.audio.models[0]`
TTS	`channels.qqbot.tts`, `channels.qqbot.accounts.<id>.tts`	`messages.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" },
            },
          },
        },
      },
    },
  },
}

Imposta enabled: false su uno dei due per disabilitarlo. Gli override TTS a livello di account usano la stessa forma di messages.tts ed eseguono un deep-merge sulla configurazione TTS del canale/globale.

Gli allegati vocali QQ in ingresso vengono esposti agli agenti come metadati multimediali audio, mantenendo i file vocali grezzi fuori dai MediaPaths generici. Le risposte in testo semplice [[audio_as_voice]] sintetizzano TTS e inviano un messaggio vocale QQ nativo quando TTS è configurato.

Il comportamento di upload/transcodifica audio in uscita può essere regolato anche con channels.qqbot.audioFormatPolicy:

sttDirectFormats
uploadDirectFormats
transcodeEnabled

Formati di destinazione

Formato	Descrizione
`qqbot:c2c:OPENID`	Chat privata (C2C)
`qqbot:group:GROUP_OPENID`	Chat di gruppo
`qqbot:channel:CHANNEL_ID`	Canale guild

Ogni bot ha il proprio insieme di OpenID utente. Un OpenID ricevuto dal Bot A non può essere usato per inviare messaggi tramite il Bot B.

Comandi slash

Comandi integrati intercettati prima della coda IA:

Comando	Descrizione
`/bot-ping`	Test di latenza
`/bot-version`	Mostra la versione del framework OpenClaw
`/bot-help`	Elenca tutti i comandi
`/bot-me`	Mostra l'ID utente QQ (openid) del mittente per la configurazione di `allowFrom`/`groupAllowFrom`
`/bot-upgrade`	Mostra il link alla guida di aggiornamento di QQBot
`/bot-logs`	Esporta i log recenti del gateway come file
`/bot-approve`	Approva un'azione QQ Bot in sospeso (ad esempio, la conferma di un upload C2C o di gruppo) tramite il flusso nativo.

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

I comandi amministratore (/bot-me, /bot-upgrade, /bot-logs, /bot-clear-storage, /bot-streaming, /bot-approve) sono disponibili solo nei messaggi diretti e richiedono l'openid del mittente in un elenco allowFrom esplicito e senza wildcard. Una wildcard allowFrom: ["*"] consente la chat ma non concede l'accesso ai comandi amministratore. I messaggi di gruppo vengono confrontati prima con groupAllowFrom e poi ripiegano su allowFrom. L'esecuzione di un comando amministratore in un gruppo restituisce un suggerimento invece di scartarlo silenziosamente.

Architettura del motore

QQ Bot viene fornito come motore autonomo all'interno del Plugin:

Ogni account possiede uno stack di risorse isolato (connessione WebSocket, client API, cache token, root di archiviazione media) indicizzato da appId. Gli account non condividono mai stato in ingresso/in uscita.
Il logger multi-account contrassegna le righe di log con l'account proprietario, così la diagnostica resta separabile quando esegui più bot sotto un solo gateway.
I percorsi in ingresso, in uscita e bridge del gateway condividono una singola root del payload multimediale sotto ~/.openclaw/media, quindi upload, download e cache di transcodifica finiscono sotto un'unica directory protetta invece che in un albero per sottosistema.
La consegna di contenuti multimediali avanzati passa attraverso un unico percorso sendMedia per destinazioni C2C e di gruppo. I file locali e i buffer sopra la soglia per file grandi usano gli endpoint di upload a blocchi di QQ, mentre i payload più piccoli usano l'API media one-shot.
Le credenziali possono essere salvate e ripristinate come parte degli snapshot standard delle credenziali OpenClaw; il motore ricollega lo stack di risorse di ogni account al ripristino senza richiedere una nuova coppia tramite codice QR.

Onboarding con codice QR

Come alternativa all'incollare manualmente AppID:AppSecret, il motore supporta un flusso di onboarding con codice QR per collegare un QQ Bot a OpenClaw:

Esegui il percorso di configurazione di QQ Bot (ad esempio openclaw channels add --channel qqbot) e scegli il flusso con codice QR quando richiesto.
Scansiona il codice QR generato con l'app del telefono associata al QQ Bot di destinazione.
Approva l'abbinamento sul telefono. OpenClaw persiste le credenziali restituite in credentials/ sotto l'ambito dell'account corretto.

I prompt di approvazione generati dal bot stesso (ad esempio, i flussi "consentire questa azione?" esposti dall'API QQ Bot) vengono mostrati come prompt OpenClaw nativi che puoi accettare con /bot-approve invece di rispondere tramite il client QQ grezzo.

Risoluzione dei problemi

Il bot risponde "gone to Mars": credenziali non configurate o Gateway non avviato.
Nessun messaggio in ingresso: verifica che appId e clientSecret siano corretti, e che il bot sia abilitato nella QQ Open Platform.
Autorisposte ripetute: OpenClaw registra gli indici ref in uscita di QQ come generati dal bot e ignora gli eventi in ingresso il cui msgIdx corrente corrisponde allo stesso account bot. Questo previene loop di eco della piattaforma consentendo comunque agli utenti di citare o rispondere a messaggi precedenti del bot.
La configurazione con --token-file risulta ancora non configurata: --token-file imposta solo l'AppSecret. Ti serve comunque appId nella configurazione o in QQBOT_APP_ID.
I messaggi proattivi non arrivano: QQ potrebbe intercettare 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 provider sia raggiungibile.

bot di QQ

Installazione

Configurazione iniziale

Configurare

Configurazione multi-account

Chat di gruppo

Voce (STT / TTS)

Formati di destinazione

Comandi slash

Architettura del motore

Onboarding con codice QR

Risoluzione dei problemi

Correlati

Ask OpenClaw

# Installazione

# Configurazione iniziale

# Configurare

# Configurazione multi-account

# Chat di gruppo

# Voce (STT / TTS)

# Formati di destinazione

# Comandi slash

# Architettura del motore

# Onboarding con codice QR

# Risoluzione dei problemi

# Correlati

Installazione

Configurazione iniziale

Configurare

Configurazione multi-account

Chat di gruppo

Voce (STT / TTS)

Formati di destinazione

Comandi slash

Architettura del motore

Onboarding con codice QR

Risoluzione dei problemi

Correlati