Discord

Pronto per DM e canali guild tramite il Gateway ufficiale di Discord.

Configurazione rapida

Dovrai creare una nuova applicazione con un bot, aggiungere il bot al tuo server e abbinarlo a OpenClaw. Consigliamo di aggiungere il bot al tuo server privato. Se non ne hai ancora uno, creane prima uno (scegli Create My Own > For me and my friends).

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"cat > discord.patch.json5 <<'JSON5'{channels: {discord: {  enabled: true,  token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },},},}JSON5openclaw config patch --file ./discord.patch.json5 --dry-runopenclaw config patch --file ./discord.patch.json5openclaw gateway

{channels: {discord: {enabled: true,token: {source: "env",provider: "default",id: "DISCORD_BOT_TOKEN",},},},}

DISCORD_BOT_TOKEN=...

{channels: {discord: {enabled: true,accounts: {personal: {  token: { source: "env", provider: "default", id: "DISCORD_PERSONAL_TOKEN" },  applicationId: "111111111111111111",},work: {  token: { source: "env", provider: "default", id: "DISCORD_WORK_TOKEN" },  applicationId: "222222222222222222",},},},},}

openclaw pairing list discordopenclaw pairing approve discord <CODE>

Consigliato: configura un workspace guild

Una volta che i DM funzionano, puoi configurare il server Discord come workspace completo in cui ogni canale ottiene la propria sessione agente con il proprio contesto. È consigliato per server privati in cui ci sei solo tu e il tuo bot.

{channels: {discord: {groupPolicy: "allowlist",guilds: {YOUR_SERVER_ID: {  requireMention: true,  users: ["YOUR_USER_ID"],},},},},}

{channels: {discord: {guilds: {YOUR_SERVER_ID: {  requireMention: false,},},},},}

Ora crea alcuni canali sul tuo server Discord e inizia a chattare. Il tuo agente può vedere il nome del canale e ogni canale ottiene la propria sessione isolata — così puoi configurare #coding, #home, #research o qualsiasi cosa si adatti al tuo flusso di lavoro.

Modello runtime

• Gateway possiede la connessione Discord.
• Il routing delle risposte è deterministico: le risposte in ingresso da Discord tornano a Discord.
• I metadati di server/canale Discord vengono aggiunti al prompt del modello come contesto non attendibile, non come prefisso di risposta visibile all'utente. Se un modello copia quell'involucro nella risposta, OpenClaw rimuove i metadati copiati dalle risposte in uscita e dal contesto di riproduzione futuro.
• Per impostazione predefinita (session.dmScope=main), le chat dirette condividono la sessione principale dell'agente (agent:main:main).
• I canali dei server sono chiavi di sessione isolate (agent:<agentId>:discord:channel:<channelId>).
• I DM di gruppo vengono ignorati per impostazione predefinita (channels.discord.dm.groupEnabled=false).
• I comandi slash nativi vengono eseguiti in sessioni di comando isolate (agent:<agentId>:discord:slash:<userId>), pur trasportando CommandTargetSessionKey verso la sessione di conversazione instradata.
• La consegna di annunci cron/heartbeat solo testo a Discord usa una sola volta la risposta finale visibile all'assistente. I payload multimediali e dei componenti strutturati restano multi-messaggio quando l'agente emette più payload consegnabili.

Canali forum

I canali forum e multimediali di Discord accettano solo post di thread. OpenClaw supporta due modi per crearli:

• Invia un messaggio al forum padre (channel:<forumId>) per creare automaticamente un thread. Il titolo del thread usa la prima riga non vuota del messaggio.
• Usa openclaw message thread create per creare direttamente un thread. Non passare --message-id per i canali forum.

Esempio: inviare al forum padre per creare un thread

openclaw message send --channel discord --target channel:<forumId> \  --message "Topic title\nBody of the post"

Esempio: creare esplicitamente un thread del forum

openclaw message thread create --channel discord --target channel:<forumId> \  --thread-name "Topic title" --message "Body of the post"

I forum padre non accettano componenti Discord. Se hai bisogno di componenti, invia al thread stesso (channel:<threadId>).

Componenti interattivi

OpenClaw supporta contenitori di componenti Discord v2 per i messaggi degli agenti. Usa lo strumento messaggio con un payload components. I risultati delle interazioni vengono instradati di nuovo all'agente come normali messaggi in ingresso e seguono le impostazioni Discord replyToMode esistenti.

Blocchi supportati:

• text, section, separator, actions, media-gallery, file
• Le righe di azioni consentono fino a 5 pulsanti o un singolo menu di selezione
• Tipi di selezione: string, user, role, mentionable, channel

Per impostazione predefinita, i componenti sono monouso. Imposta components.reusable=true per consentire l'uso ripetuto di pulsanti, selezioni e moduli finché non scadono.

Per limitare chi può fare clic su un pulsante, imposta allowedUsers su quel pulsante (ID utente Discord, tag o *). Quando configurato, gli utenti non corrispondenti ricevono un rifiuto effimero.

I callback dei componenti scadono dopo 30 minuti per impostazione predefinita. Imposta channels.discord.agentComponents.ttlMs per modificare la durata del registro dei callback per l'account Discord predefinito, oppure channels.discord.accounts.<accountId>.agentComponents.ttlMs per sovrascrivere un account in una configurazione multi-account. Il valore è in millisecondi, deve essere un numero intero positivo ed è limitato a 86400000 (24 ore). TTL più lunghi sono utili per flussi di revisione o approvazione che richiedono che i pulsanti restino utilizzabili, ma estendono anche la finestra in cui un vecchio messaggio Discord può ancora attivare un'azione. Preferisci il TTL più breve adatto al flusso di lavoro e mantieni il valore predefinito quando callback obsoleti risulterebbero sorprendenti.

I comandi slash /model e /models aprono un selettore di modelli interattivo con menu a discesa per provider, modello e runtime compatibile, più un passaggio di invio. /models add è deprecato e ora restituisce un messaggio di deprecazione invece di registrare modelli dalla chat. La risposta del selettore è effimera e solo l'utente che l'ha invocata può usarla. I menu di selezione Discord sono limitati a 25 opzioni, quindi aggiungi voci provider/* a agents.defaults.models quando vuoi che il selettore mostri i modelli scoperti dinamicamente solo per provider selezionati come openai o vllm.

Allegati file:

• I blocchi file devono puntare a un riferimento allegato (attachment://<filename>)
• Fornisci l'allegato tramite media/path/filePath (singolo file); usa media-gallery per più file
• Usa filename per sovrascrivere il nome di caricamento quando deve corrispondere al riferimento allegato

Moduli modali:

• Aggiungi components.modal con un massimo di 5 campi
• Tipi di campo: text, checkbox, radio, select, role-select, user-select
• OpenClaw aggiunge automaticamente un pulsante di attivazione

Esempio:

{  channel: "discord",  action: "send",  to: "channel:123456789012345678",  message: "Optional fallback text",  components: {    reusable: true,    text: "Choose a path",    blocks: [      {        type: "actions",        buttons: [          {            label: "Approve",            style: "success",            allowedUsers: ["123456789012345678"],          },          { label: "Decline", style: "danger" },        ],      },      {        type: "actions",        select: {          type: "string",          placeholder: "Pick an option",          options: [            { label: "Option A", value: "a" },            { label: "Option B", value: "b" },          ],        },      },    ],    modal: {      title: "Details",      triggerLabel: "Open form",      fields: [        { type: "text", label: "Requester" },        {          type: "select",          label: "Priority",          options: [            { label: "Low", value: "low" },            { label: "High", value: "high" },          ],        },      ],    },  },}

Controllo degli accessi e routing

{accessGroups: {operators: {  type: "message.senders",  members: {    "*": ["global-owner-id"],    discord: ["discord:123456789012345678"],    telegram: ["987654321"],  },},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:operators"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",  membership: "canViewChannel",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers", "discord:123456789012345678"],},},}

{channels: {discord: {  groupPolicy: "allowlist",  guilds: {    "123456789012345678": {      requireMention: true,      ignoreOtherMentions: true,      users: ["987654321098765432"],      roles: ["123456789012345678"],      channels: {        general: { allow: true },        help: { allow: true, requireMention: true },      },    },  },},},}

Routing degli agenti basato sui ruoli

Usa bindings[].match.roles per instradare i membri della guild Discord verso agenti diversi in base all'ID del ruolo. I binding basati sui ruoli accettano solo ID ruolo e vengono valutati dopo i binding peer o parent-peer e prima dei binding solo guild. Se un binding imposta anche altri campi di corrispondenza (per esempio peer + guildId + roles), tutti i campi configurati devono corrispondere.

{  bindings: [    {      agentId: "opus",      match: {        channel: "discord",        guildId: "123456789012345678",        roles: ["111111111111111111"],      },    },    {      agentId: "sonnet",      match: {        channel: "discord",        guildId: "123456789012345678",      },    },  ],}

Comandi nativi e autorizzazione dei comandi

• commands.native è impostato per impostazione predefinita su "auto" ed è abilitato per Discord.
• Override per canale: channels.discord.commands.native.
• commands.native=false salta la registrazione e la pulizia degli slash command Discord durante l'avvio. I comandi registrati in precedenza potrebbero rimanere visibili in Discord finché non li rimuovi dall'app Discord.
• L'autorizzazione dei comandi nativi usa le stesse liste consentite/policy Discord della normale gestione dei messaggi.
• I comandi potrebbero essere ancora visibili nell'interfaccia utente Discord per gli utenti non autorizzati; l'esecuzione applica comunque l'autorizzazione OpenClaw e restituisce "non autorizzato".

Vedi Slash command per il catalogo e il comportamento dei comandi.

Impostazioni predefinite degli slash command:

• ephemeral: true

Dettagli della funzionalità

{channels: {discord: {  suppressEmbeds: false,},},}

{channels: {discord: {  streaming: {    mode: "progress",    progress: {      label: "auto",      maxLines: 8,      maxLineChars: 120,      toolProgress: true,      commentary: false,    },  },},},}

{  "channels": {    "discord": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

{session: {threadBindings: {  enabled: true,  idleHours: 24,  maxAgeHours: 0,},},channels: {discord: {  threadBindings: {    enabled: true,    idleHours: 24,    maxAgeHours: 0,    spawnSessions: true,    defaultSpawnContext: "fork",  },},},}

{agents: {list: [  {    id: "codex",    runtime: {      type: "acp",      acp: {        agent: "codex",        backend: "acpx",        mode: "persistent",        cwd: "/workspace/openclaw",      },    },  },],},bindings: [{  type: "acp",  agentId: "codex",  match: {    channel: "discord",    accountId: "default",    peer: { kind: "channel", id: "222222222222222222" },  },  acp: { label: "codex-main" },},],channels: {discord: {  guilds: {    "111111111111111111": {      channels: {        "222222222222222222": {          requireMention: false,        },      },    },  },},},}

{channels: {discord: {  configWrites: false,},},}

{channels: {discord: {  proxy: "http://proxy.example:8080",},},}

{channels: {discord: {  accounts: {    primary: {      proxy: "http://proxy.example:8080",    },  },},},}

{channels: {discord: {  pluralkit: {    enabled: true,    token: "pk_live_...", // optional; needed for private systems  },},},}

{channels: {discord: {  mentionAliases: {    Vladislava: "123456789012345678",  },  accounts: {    ops: {      mentionAliases: {        OpsLead: "234567890123456789",      },    },  },},},}

{channels: {discord: {  status: "idle",},},}

{channels: {discord: {  activity: "Focus time",  activityType: 4,},},}

{channels: {discord: {  activity: "Live coding",  activityType: 1,  activityUrl: "https://twitch.tv/openclaw",},},}

{channels: {discord: {  autoPresence: {    enabled: true,    intervalMs: 30000,    minUpdateIntervalMs: 15000,    exhaustedText: "token exhausted",  },},},}

Strumenti e gate di azione

Le azioni dei messaggi Discord includono messaggistica, amministrazione dei canali, moderazione, presenza e azioni sui metadati.

Esempi principali:

• messaggistica: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• reazioni: react, reactions, emojiList
• moderazione: timeout, kick, ban
• presenza: setPresence

L'azione event-create accetta un parametro facoltativo image (URL o percorso di file locale) per impostare l'immagine di copertina dell'evento programmato.

I gate di azione si trovano sotto channels.discord.actions.*.

Comportamento predefinito dei gate:

UI componenti v2

OpenClaw usa i componenti Discord v2 per le approvazioni exec e i marcatori tra contesti. Le azioni dei messaggi Discord possono anche accettare components per UI personalizzate (avanzato; richiede di costruire un payload componente tramite lo strumento discord), mentre gli embeds legacy restano disponibili ma non sono consigliati.

• channels.discord.ui.components.accentColor imposta il colore di accento usato dai contenitori dei componenti Discord (hex).
• Impostalo per account con channels.discord.accounts.<id>.ui.components.accentColor.
• channels.discord.agentComponents.ttlMs controlla per quanto tempo i callback dei componenti Discord inviati restano registrati (predefinito 1800000, massimo 86400000). Impostalo per account con channels.discord.accounts.<id>.agentComponents.ttlMs.
• Gli embeds vengono ignorati quando sono presenti componenti v2.
• Le anteprime degli URL semplici sono soppresse per impostazione predefinita. Imposta suppressEmbeds: false su un'azione messaggio quando un singolo link in uscita deve espandersi.

Esempio:

{  channels: {    discord: {      ui: {        components: {          accentColor: "#5865F2",        },      },    },  },}

Voce

Discord ha due superfici voce distinte: canali vocali realtime (conversazioni continue) e allegati di messaggi vocali (il formato di anteprima con forma d'onda). Il gateway supporta entrambe.

Canali vocali

Checklist di configurazione:

1. Abilita Message Content Intent nel Discord Developer Portal.
2. Abilita Server Members Intent quando vengono usati allowlist di ruoli/utenti.
3. Invita il bot con gli ambiti bot e applications.commands.
4. Concedi Connect, Speak, Send Messages e Read Message History nel canale vocale di destinazione.
5. Abilita i comandi nativi (commands.native o channels.discord.commands.native).
6. Configura channels.discord.voice.

Usa /vc join|leave|status per controllare le sessioni. Il comando usa l'agente predefinito dell'account e segue le stesse regole di allowlist e policy di gruppo degli altri comandi Discord.

/vc join channel:<voice-channel-id>/vc status/vc leave

Per esaminare le autorizzazioni effettive del bot prima dell'accesso, esegui:

openclaw channels capabilities --channel discord --target channel:<voice-channel-id>

Esempio di accesso automatico:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.5",        autoJoin: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],        daveEncryption: true,        decryptionFailureTolerance: 24,        connectTimeoutMs: 30000,        reconnectGraceMs: 15000,        realtime: {          provider: "openai",          model: "gpt-realtime-2",          speakerVoice: "cedar",        },      },    },  },}

Note:

• voice.tts sovrascrive messages.tts solo per la riproduzione vocale stt-tts. Le modalità realtime usano voice.realtime.speakerVoice.
• voice.mode controlla il percorso della conversazione. Il valore predefinito è agent-proxy: un front end vocale realtime gestisce la temporizzazione dei turni, l'interruzione e la riproduzione, delega il lavoro sostanziale all'agente OpenClaw instradato tramite openclaw_agent_consult e tratta il risultato come un prompt Discord digitato da quello speaker. stt-tts mantiene il vecchio flusso batch STT più TTS. bidi consente al modello realtime di conversare direttamente esponendo openclaw_agent_consult per il cervello OpenClaw.
• voice.agentSession controlla quale conversazione OpenClaw riceve i turni vocali. Lascialo non impostato per la sessione del canale vocale stesso, oppure imposta { mode: "target", target: "channel:<text-channel-id>" } per fare in modo che il canale vocale agisca come estensione microfono/speaker di una sessione esistente di un canale testuale Discord, ad esempio #maintainers.
• voice.model sovrascrive il cervello dell'agente OpenClaw per le risposte vocali Discord e le consultazioni realtime. Lascialo non impostato per ereditare il modello dell'agente instradato. È separato da voice.realtime.model.
• voice.followUsers consente al bot di entrare, spostarsi e uscire dalla voce Discord con utenti selezionati. Vedi Segui utenti in voce per regole di comportamento ed esempi.
• agent-proxy instrada il parlato tramite discord-voice, che preserva la normale autorizzazione proprietario/strumenti per lo speaker e la sessione di destinazione ma nasconde lo strumento agente tts perché la voce Discord possiede la riproduzione. Per impostazione predefinita, agent-proxy concede alla consultazione accesso completo agli strumenti equivalente al proprietario per gli speaker proprietari (voice.realtime.toolPolicy: "owner") e preferisce fortemente consultare l'agente OpenClaw prima delle risposte sostanziali (voice.realtime.consultPolicy: "always"). In quella modalità predefinita always, il livello realtime non pronuncia automaticamente riempitivi prima della risposta della consultazione; cattura e trascrive il parlato, poi pronuncia la risposta OpenClaw instradata. Se più risposte di consultazione forzata terminano mentre Discord sta ancora riproducendo la prima risposta, le risposte vocali esatte successive vengono accodate fino a quando la riproduzione è inattiva invece di sostituire il parlato a metà frase.
• In modalità stt-tts, STT usa tools.media.audio; voice.model non influisce sulla trascrizione.
• Nelle modalità realtime, voice.realtime.provider, voice.realtime.model e voice.realtime.speakerVoice configurano la sessione audio realtime. Per OpenAI Realtime 2 più il cervello Codex, usa voice.realtime.model: "gpt-realtime-2" e voice.model: "openai/gpt-5.5".
• Le modalità vocali realtime includono per impostazione predefinita piccoli file profilo IDENTITY.md, USER.md e SOUL.md nelle istruzioni del provider realtime, così i turni diretti rapidi mantengono la stessa identità, lo stesso radicamento utente e la stessa persona dell'agente OpenClaw instradato. Imposta voice.realtime.bootstrapContextFiles su un sottoinsieme per personalizzarlo, oppure [] per disabilitarlo. I file di bootstrap realtime supportati sono limitati a quei file profilo; AGENTS.md resta nel normale contesto dell'agente. Il contesto profilo iniettato non sostituisce openclaw_agent_consult per lavoro nell'area di lavoro, fatti correnti, consultazione della memoria o azioni basate su strumenti.
• Nella modalità realtime OpenAI agent-proxy, imposta voice.realtime.requireWakeName: true per mantenere silenziosa la voce realtime Discord finché una trascrizione non inizia o finisce con un nome di attivazione. I nomi di attivazione configurati devono essere di una o due parole. Se voice.realtime.wakeNames non è impostato, OpenClaw usa il name dell'agente instradato più OpenClaw, con fallback all'id dell'agente più OpenClaw. Il gate tramite nome di attivazione disabilita la risposta automatica del provider realtime, instrada i turni accettati attraverso il percorso di consultazione dell'agente OpenClaw e dà un breve riconoscimento parlato quando un nome di attivazione iniziale viene riconosciuto dalla trascrizione parziale prima dell'arrivo della trascrizione finale.
• Il provider realtime OpenAI accetta i nomi evento correnti di Realtime 2 e gli alias legacy compatibili con Codex per eventi audio di output e trascrizione, così gli snapshot del provider compatibili possono divergere senza perdere l'audio dell'assistente.
• voice.realtime.bargeIn controlla se gli eventi di inizio parlato dello speaker Discord interrompono la riproduzione realtime attiva. Se non impostato, segue l'impostazione di interruzione audio di input del provider realtime.
• voice.realtime.minBargeInAudioEndMs controlla la durata minima della riproduzione dell'assistente prima che un barge-in realtime OpenAI tronchi l'audio. Valore predefinito: 250. Imposta 0 per interruzione immediata in stanze con poca eco, oppure aumentalo per configurazioni speaker con molta eco.
• Per una voce OpenAI sulla riproduzione Discord, imposta voice.tts.provider: "openai" e scegli una voce Text-to-speech sotto voice.tts.providers.openai.speakerVoice. cedar è una buona scelta dal suono maschile sull'attuale modello TTS OpenAI.
• Le sovrascritture Discord systemPrompt per canale si applicano ai turni di trascrizione vocale per quel canale vocale.
• I turni di trascrizione vocale derivano lo stato di proprietario da Discord allowFrom (o dm.allowFrom) per comandi protetti da proprietario e azioni del canale. La visibilità degli strumenti agente segue la policy strumenti configurata per la sessione instradata.
• La voce Discord è opt-in per le configurazioni solo testo; imposta channels.discord.voice.enabled=true (oppure mantieni un blocco channels.discord.voice esistente) per abilitare i comandi /vc, il runtime vocale e l'intent Gateway GuildVoiceStates.
• channels.discord.intents.voiceStates può sovrascrivere esplicitamente la sottoscrizione all'intent dello stato vocale. Lascialo non impostato perché l'intent segua l'abilitazione effettiva della voce.
• Se voice.autoJoin ha più voci per la stessa guild, OpenClaw entra nell'ultimo canale configurato per quella guild.
• voice.allowedChannels è una allowlist di permanenza opzionale. Lasciala non impostata per consentire /vc join in qualsiasi canale vocale Discord autorizzato. Quando è impostata, /vc join, l'auto-join all'avvio e gli spostamenti dello stato vocale del bot sono limitati alle voci { guildId, channelId } elencate. Impostala su un array vuoto per negare tutti gli ingressi vocali Discord. Se Discord sposta il bot fuori dalla allowlist, OpenClaw lascia quel canale e rientra nella destinazione di auto-join configurata quando disponibile.
• voice.daveEncryption e voice.decryptionFailureTolerance vengono passati alle opzioni di join di @discordjs/voice.
• I valori predefiniti di @discordjs/voice sono daveEncryption=true e decryptionFailureTolerance=24 se non impostati.
• OpenClaw usa il codec libopus-wasm incluso per la ricezione vocale Discord e la riproduzione PCM grezza realtime. Distribuisce una build WebAssembly libopus fissata e non richiede addon opus nativi.
• voice.connectTimeoutMs controlla l'attesa iniziale Ready di @discordjs/voice per /vc join e i tentativi di auto-join. Valore predefinito: 30000.
• voice.reconnectGraceMs controlla per quanto tempo OpenClaw attende che una sessione vocale disconnessa inizi la riconnessione prima di distruggerla. Valore predefinito: 15000.
• In modalità stt-tts, la riproduzione vocale non si ferma solo perché un altro utente inizia a parlare. Per evitare loop di feedback, OpenClaw ignora la nuova cattura vocale mentre TTS è in riproduzione; parla dopo la fine della riproduzione per il turno successivo. Le modalità realtime inoltrano gli inizi parlato degli speaker come segnali di barge-in al provider realtime.
• Nelle modalità realtime, l'eco dagli speaker verso un microfono aperto può sembrare un barge-in e interrompere la riproduzione. Per stanze Discord con molta eco, imposta voice.realtime.providers.openai.interruptResponseOnInputAudio: false per impedire a OpenAI di interrompere automaticamente sull'audio di input. Aggiungi voice.realtime.bargeIn: true se vuoi comunque che gli eventi di inizio parlato degli speaker Discord interrompano la riproduzione attiva. Il bridge realtime OpenAI ignora i troncamenti di riproduzione più brevi di voice.realtime.minBargeInAudioEndMs come probabile eco/rumore e li registra come saltati invece di cancellare la riproduzione Discord.
• voice.captureSilenceGraceMs controlla per quanto tempo OpenClaw attende dopo che Discord segnala che uno speaker ha smesso prima di finalizzare quel segmento audio per STT. Valore predefinito: 2000; aumentalo se Discord divide pause normali in trascrizioni parziali frammentate.
• Quando ElevenLabs è il provider TTS selezionato, la riproduzione vocale Discord usa TTS in streaming e parte dallo stream di risposta del provider. I provider senza supporto streaming ripiegano sul percorso del file temporaneo sintetizzato.
• OpenClaw monitora anche gli errori di decrittazione in ricezione e recupera automaticamente uscendo e rientrando nel canale vocale dopo errori ripetuti in una finestra breve.
• Se i log di ricezione mostrano ripetutamente DecryptionFailed(UnencryptedWhenPassthroughDisabled) dopo l'aggiornamento, raccogli un report delle dipendenze e i log. La linea @discordjs/voice inclusa include la correzione upstream del padding dalla PR discord.js #11449, che ha chiuso l'issue discord.js #11419.
• Gli eventi di ricezione The operation was aborted sono attesi quando OpenClaw finalizza un segmento speaker catturato; sono diagnostica dettagliata, non avvisi.
• I log dettagliati della voce Discord includono un'anteprima limitata a una riga della trascrizione STT per ogni segmento speaker accettato, così il debug mostra sia il lato utente sia il lato risposta dell'agente senza scaricare testo di trascrizione illimitato.
• In modalità agent-proxy, il fallback della consultazione forzata salta frammenti di trascrizione probabilmente incompleti, ad esempio testo che termina in ... o un connettore finale come and, più chiusure ovviamente non azionabili come “torno subito” o “ciao”. I log mostrano forced agent consult skipped reason=... quando questo impedisce una risposta accodata obsoleta.

Segui utenti in voce

Usa voice.followUsers quando vuoi che il bot vocale Discord resti con uno o più utenti Discord noti invece di entrare in un canale fisso all'avvio o attendere /vc join.

{  channels: {    discord: {      voice: {        enabled: true,        followUsersEnabled: true,        followUsers: ["discord:123456789012345678"],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],      },    },  },}

Comportamento:

• followUsers accetta ID utente Discord grezzi e valori discord:<id>. OpenClaw normalizza entrambe le forme prima di confrontare gli eventi di stato vocale.
• followUsersEnabled è predefinito a true quando followUsers è configurato. Impostalo su false per mantenere l'elenco salvato ma interrompere il seguito vocale automatico.
• Quando un utente seguito entra in un canale vocale consentito, OpenClaw entra in quel canale. Quando l'utente si sposta, OpenClaw si sposta con lui. Quando l'utente seguito attivo si disconnette, OpenClaw esce.
• Se più utenti seguiti sono nella stessa guild e l'utente seguito attivo esce, OpenClaw si sposta nel canale di un altro utente seguito tracciato prima di uscire dalla guild. Se più utenti seguiti si spostano contemporaneamente, vince l'ultimo evento di stato vocale osservato.
• allowedChannels si applica comunque. Un utente seguito in un canale non consentito viene ignorato, e una sessione posseduta dal seguito si sposta a un altro utente seguito o esce.
• OpenClaw riconcilia gli eventi di stato vocale mancati all'avvio e a un intervallo limitato. La riconciliazione campiona le guild configurate e limita le ricerche REST per esecuzione, quindi elenchi followUsers molto grandi possono richiedere più di un intervallo per convergere.
• Se Discord o un amministratore sposta il bot mentre sta seguendo un utente, OpenClaw ricostruisce la sessione vocale e preserva la proprietà del seguito quando la destinazione è consentita. Se il bot viene spostato fuori da allowedChannels, OpenClaw esce e rientra nella destinazione configurata quando ne esiste una.
• Il recupero ricezione DAVE può uscire e rientrare nello stesso canale dopo errori di decrittazione ripetuti. Le sessioni possedute dal seguito mantengono la loro proprietà del seguito attraverso quel percorso di recupero, quindi una successiva disconnessione dell'utente seguito lascia comunque il canale.

Scegli tra le modalità di ingresso:

• Usa followUsers per configurazioni personali o operative in cui il bot dovrebbe essere automaticamente in voce quando lo sei tu.
• Usa autoJoin per bot di stanze fisse che dovrebbero essere presenti anche quando nessun utente tracciato è in voce.
• Usa /vc join per ingressi una tantum o stanze in cui la presenza vocale automatica sarebbe sorprendente.

Codec vocale Discord:

• I log di ricezione vocale mostrano discord voice: opus decoder: libopus-wasm.
• La riproduzione in tempo reale codifica PCM stereo grezzo a 48 kHz in Opus con lo stesso pacchetto libopus-wasm incluso prima di passare i pacchetti a @discordjs/voice.
• La riproduzione di file e stream del provider transcodifica in PCM stereo grezzo a 48 kHz con ffmpeg, poi usa libopus-wasm per lo stream di pacchetti Opus inviato a Discord.

Pipeline STT più TTS:

• L'acquisizione PCM di Discord viene convertita in un file temporaneo WAV.
• tools.media.audio gestisce STT, per esempio openai/gpt-4o-mini-transcribe.
• La trascrizione viene inviata tramite ingresso e routing Discord mentre l'LLM di risposta viene eseguito con una policy di output vocale che nasconde lo strumento tts dell'agente e richiede testo restituito, perché Discord voice possiede la riproduzione TTS finale.
• voice.model, quando impostato, sovrascrive solo l'LLM di risposta per questo turno del canale vocale.
• voice.tts viene unito sopra messages.tts; i provider con supporto allo streaming alimentano direttamente il player, altrimenti il file audio risultante viene riprodotto nel canale a cui si è uniti.

Esempio di sessione del canale vocale agent-proxy predefinita:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.5",        followUsersEnabled: true,        followUsers: ["123456789012345678"],        realtime: {          provider: "openai",          model: "gpt-realtime-2",          speakerVoice: "cedar",        },      },    },  },}

Senza un blocco voice.agentSession, ogni canale vocale ottiene la propria sessione OpenClaw instradata. Per esempio, /vc join channel:234567890123456789 parla con la sessione per quel canale vocale Discord. Il modello in tempo reale è solo il front end vocale; le richieste sostanziali vengono passate all'agente OpenClaw configurato. Se il modello in tempo reale produce una trascrizione finale senza chiamare lo strumento di consultazione, OpenClaw forza la consultazione come fallback, così il comportamento predefinito resta quello di parlare con l'agente.

Esempio legacy STT più TTS:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "stt-tts",        model: "openai/gpt-5.4-mini",        tts: {          provider: "openai",          providers: {            openai: {              model: "gpt-4o-mini-tts",              speakerVoice: "cedar",            },          },        },      },    },  },}

Esempio bidi in tempo reale:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai/gpt-5.5",        realtime: {          provider: "openai",          model: "gpt-realtime-2",          speakerVoice: "cedar",          toolPolicy: "safe-read-only",          consultPolicy: "always",        },      },    },  },}

Voce come estensione di una sessione di canale Discord esistente:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "agent-proxy",        model: "openai/gpt-5.5",        agentSession: {          mode: "target",          target: "channel:123456789012345678",        },        realtime: {          provider: "openai",          model: "gpt-realtime-2",          speakerVoice: "cedar",        },      },    },  },}

In modalità agent-proxy, il bot entra nel canale vocale configurato, ma i turni dell'agente OpenClaw usano la sessione instradata normale del canale di destinazione e il relativo agente. La sessione vocale in tempo reale pronuncia il risultato restituito nel canale vocale. L'agente supervisore può comunque usare i normali strumenti di messaggistica secondo la propria policy degli strumenti, incluso l'invio di un messaggio Discord separato se questa è l'azione corretta.

Mentre è attiva un'esecuzione OpenClaw delegata, le nuove trascrizioni vocali Discord vengono trattate come controllo dell'esecuzione live prima di avviare un altro turno dell'agente. Frasi come "status", "cancel that", "use the smaller fix" o "when you're done also check tests" vengono classificate come input di stato, annullamento, guida o follow-up per la sessione attiva. Gli esiti di stato, annullamento, guida accettata e follow-up vengono pronunciati nel canale vocale, così chi chiama sa se OpenClaw ha gestito la richiesta.

Forme di destinazione utili:

• target: "channel:123456789012345678" instrada tramite una sessione di canale testuale Discord.
• target: "123456789012345678" viene trattato come destinazione di canale.
• target: "dm:123456789012345678" o target: "user:123456789012345678" instrada tramite quella sessione di messaggio diretto.

Esempio OpenAI Realtime con molto eco:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai/gpt-5.5",        realtime: {          provider: "openai",          model: "gpt-realtime-2",          speakerVoice: "cedar",          bargeIn: true,          minBargeInAudioEndMs: 500,          consultPolicy: "always",          providers: {            openai: {              interruptResponseOnInputAudio: false,            },          },        },      },    },  },}

Usalo quando il modello sente la propria riproduzione Discord attraverso un microfono aperto, ma vuoi comunque interromperlo parlando. OpenClaw impedisce a OpenAI di interrompere automaticamente sull'audio di input grezzo, mentre bargeIn: true consente agli eventi di avvio parlante Discord e all'audio di un parlante già attivo di annullare le risposte in tempo reale attive prima che il turno acquisito successivo raggiunga OpenAI. I segnali di interruzione molto precoci con audioEndMs inferiore a minBargeInAudioEndMs vengono trattati come probabile eco/rumore e ignorati, così il modello non si interrompe al primo frame di riproduzione.

Log vocali attesi:

• All'ingresso: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• All'avvio in tempo reale: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• Sull'audio del parlante: discord voice: realtime speaker turn opened ..., discord voice: realtime input audio started ... outputAudioMs=... outputActive=... e discord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=...
• Sul parlato obsoleto saltato: discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... o reason=non-actionable-closing ...
• Al completamento della risposta in tempo reale: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• All'arresto/ripristino della riproduzione: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• Sulla consultazione in tempo reale: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• Alla risposta dell'agente: discord voice: agent turn answer ...
• Sul parlato esatto accodato: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=..., seguito da discord voice: realtime exact speech dequeued reason=player-idle ...
• Al rilevamento di interruzione: discord voice: realtime barge-in detected source=speaker-start ... o discord voice: realtime barge-in detected source=active-speaker-audio ..., seguito da discord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=...
• All'interruzione in tempo reale: discord voice: realtime model interrupt requested client:response.cancel reason=barge-in, seguito da discord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=... oppure discord voice: realtime model interrupt confirmed server:response.done status=cancelled ...
• Su eco/rumore ignorati: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• Con interruzione disabilitata: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• Con riproduzione inattiva: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

Per eseguire il debug di audio tagliato, leggi i log vocali in tempo reale come una cronologia:

1. realtime audio playback started significa che Discord ha iniziato a riprodurre l'audio dell'assistente. Da questo punto il bridge inizia a contare i chunk di output dell'assistente, i byte PCM Discord, i byte in tempo reale del provider e la durata dell'audio sintetizzato.
2. realtime speaker turn opened indica che un parlante Discord diventa attivo. Se la riproduzione è già attiva e bargeIn è abilitato, questo può essere seguito da barge-in detected source=speaker-start.
3. realtime input audio started indica il primo frame audio effettivo ricevuto per quel turno del parlante. outputActive=true o un outputAudioMs diverso da zero qui significa che il microfono sta inviando input mentre la riproduzione dell'assistente è ancora attiva.
4. barge-in detected source=active-speaker-audio significa che OpenClaw ha visto audio live del parlante mentre la riproduzione dell'assistente era attiva. Questo è utile per distinguere una vera interruzione da un evento Discord di avvio parlante senza audio utile.
5. barge-in requested reason=... significa che OpenClaw ha chiesto al provider in tempo reale di annullare o troncare la risposta attiva. Include outputAudioMs, outputActive e playbackChunks così puoi vedere quanto audio dell'assistente era stato effettivamente riprodotto prima dell'interruzione.
6. realtime audio playback stopped reason=... è il punto locale di ripristino della riproduzione Discord. Il motivo dice chi ha fermato la riproduzione: barge-in, player-idle, provider-clear-audio, forced-agent-consult, stream-close o session-close.
7. realtime speaker turn closed riepiloga il turno di input acquisito. chunks=0 o hasAudio=false significa che il turno del parlante si è aperto ma nessun audio utilizzabile ha raggiunto il bridge in tempo reale. interruptedPlayback=true significa che quel turno di input si è sovrapposto all'output dell'assistente e ha attivato la logica di interruzione.

Campi utili:

• outputAudioMs: durata dell'audio dell'assistente generato dal provider in tempo reale prima della riga di log.
• audioMs: durata dell'audio dell'assistente conteggiata da OpenClaw prima che la riproduzione si fermasse.
• elapsedMs: tempo wall-clock tra l'apertura e la chiusura dello stream di riproduzione o del turno del parlante.
• discordBytes: byte PCM stereo a 48 kHz inviati a o ricevuti da Discord voice.
• realtimeBytes: byte PCM nel formato del provider inviati a o ricevuti dal provider in tempo reale.
• playbackChunks: chunk audio dell'assistente inoltrati a Discord per la risposta attiva.
• sinceLastAudioMs: intervallo tra l'ultimo frame audio acquisito del parlante e la chiusura del turno del parlante.

Pattern comuni:

• Taglio immediato con source=active-speaker-audio, outputAudioMs piccolo e lo stesso utente nelle vicinanze di solito indica eco dell'altoparlante che entra nel microfono. Aumenta voice.realtime.minBargeInAudioEndMs, abbassa il volume dell'altoparlante, usa cuffie oppure imposta voice.realtime.providers.openai.interruptResponseOnInputAudio: false.
• source=speaker-start seguito da speaker turn closed ... hasAudio=false significa che Discord ha segnalato l'avvio di un parlante ma nessun audio ha raggiunto OpenClaw. Può trattarsi di un evento vocale Discord transitorio, del comportamento del noise gate o di un client che attiva brevemente il microfono.
• audio playback stopped reason=stream-close senza una vicina interruzione o provider-clear-audio significa che lo stream di riproduzione Discord locale è terminato in modo imprevisto. Controlla i log precedenti del provider e del player Discord.
• capture ignored during playback (barge-in disabled) significa che OpenClaw ha scartato intenzionalmente l'input mentre l'audio dell'assistente era attivo. Abilita voice.realtime.bargeIn se vuoi che il parlato interrompa la riproduzione.
• barge-in ignored ... outputActive=false significa che Discord o il VAD del provider ha segnalato parlato, ma OpenClaw non aveva alcuna riproduzione attiva da interrompere. Questo non dovrebbe tagliare l'audio.

Le credenziali vengono risolte per componente: autenticazione del route LLM per voice.model, autenticazione STT per tools.media.audio, autenticazione TTS per messages.tts/voice.tts e autenticazione del provider in tempo reale per voice.realtime.providers o la normale configurazione di autenticazione del provider.

Messaggi vocali

I messaggi vocali Discord mostrano un'anteprima della forma d'onda e richiedono audio OGG/Opus. OpenClaw genera automaticamente la forma d'onda, ma ha bisogno di ffmpeg e ffprobe sull'host del Gateway per ispezionare e convertire.

• Fornisci un percorso file locale (gli URL vengono rifiutati).
• Ometti il contenuto testuale (Discord rifiuta testo + messaggio vocale nello stesso payload).
• Qualsiasi formato audio è accettato; OpenClaw converte in OGG/Opus secondo necessità.

message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)

Risoluzione dei problemi

openclaw doctoropenclaw channels status --probeopenclaw logs --follow

{channels: {discord: {  accounts: {    default: {      eventQueue: {        listenerTimeout: 120000,      },    },  },},},}

{channels: {defaults: {  botLoopProtection: {    maxEventsPerWindow: 20,    windowSeconds: 60,    cooldownSeconds: 60,  },},discord: {  // Optional Discord-wide override. Account blocks override individual  // fields and inherit omitted fields from here.  botLoopProtection: {    maxEventsPerWindow: 4,  },  accounts: {    mantis: {      // Mantis listens to other bots only when they mention her.      allowBots: "mentions",    },    molty: {      // Molty listens to all bot-authored Discord messages.      allowBots: true,      mentionAliases: {        // Lets Molty write a Mantis Discord mention with the configured user id.        Mantis: "MANTIS_DISCORD_USER_ID",      },      botLoopProtection: {        // Allow up to five messages per minute before suppressing the pair.        maxEventsPerWindow: 5,        windowSeconds: 60,        cooldownSeconds: 90,      },    },  },},},}

Riferimento di configurazione

Riferimento principale: Riferimento di configurazione - Discord.

Sicurezza e operazioni

• Tratta i token bot come segreti (DISCORD_BOT_TOKEN preferito in ambienti supervisionati).
• Concedi i permessi Discord con privilegio minimo.
• Se deploy/stato dei comandi è obsoleto, riavvia il Gateway e ricontrolla con openclaw channels status --probe.

Correlati