Discord

OpenClaw si connette a Discord come bot tramite il Gateway ufficiale di Discord. Sono supportati i messaggi diretti e i canali dei server.

Configurazione rapida

Crea un'applicazione Discord con un bot, aggiungi il bot al tuo server e associalo a OpenClaw. Se possibile, usa un server privato; se necessario, creane prima uno (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 uno spazio di lavoro nel server

Quando i messaggi diretti funzionano, puoi trasformare il server in uno spazio di lavoro completo in cui ogni canale dispone di una propria sessione dell'agente con un contesto dedicato. Questa soluzione è consigliata per i server privati in cui sono presenti 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 i canali e inizia a chattare. L'agente vede il nome del canale e ogni canale costituisce una sessione isolata: configura #coding, #home, #research o qualsiasi altra suddivisione adatta al tuo flusso di lavoro.

Modello di runtime

• Il Gateway gestisce la connessione a Discord.
• L'instradamento delle risposte è deterministico: le risposte ai messaggi in ingresso da Discord vengono inviate nuovamente a Discord.
• I metadati del server/canale Discord vengono aggiunti al prompt del modello come contesto non attendibile, non come prefisso visibile all'utente nella risposta. Se un modello ricopia tale involucro, OpenClaw rimuove i metadati copiati dalle risposte in uscita e dal contesto delle riproduzioni future.
• Per impostazione predefinita (session.dmScope=main), le chat dirette condividono la sessione principale dell'agente (agent:main:main).
• I canali del server usano chiavi di sessione isolate (agent:<agentId>:discord:channel:<channelId>).
• I messaggi diretti 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 continuando a trasmettere CommandTargetSessionKey alla sessione di conversazione instradata.
• La consegna su Discord degli annunci Cron/Heartbeat di solo testo viene ridotta alla risposta finale visibile dell'assistente, inviata una sola volta. I contenuti multimediali e i payload dei componenti strutturati rimangono composti da più messaggi quando l'agente produce più payload consegnabili.

Canali forum

I canali forum e multimediali di Discord accettano solo post nelle discussioni. OpenClaw supporta due modalità per crearli:

• Invia un messaggio al canale principale del forum (channel:<forumId>) per creare automaticamente una discussione. Il titolo della discussione è la prima riga non vuota del messaggio (troncata al limite di 100 caratteri imposto da Discord per il nome della discussione).
• Usa openclaw message thread create per creare direttamente una discussione. Non passare --message-id per i canali forum.

Invia al canale principale del forum per creare una discussione:

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

Crea esplicitamente una discussione nel forum:

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

I canali principali dei forum non accettano componenti Discord. Se hai bisogno di componenti, inviali alla discussione stessa (channel:<threadId>).

Componenti interattivi

OpenClaw supporta i contenitori dei componenti Discord v2 per i messaggi dell'agente. Usa lo strumento per i messaggi con un payload components. I risultati delle interazioni vengono reindirizzati all'agente come normali messaggi in entrata e rispettano le impostazioni Discord replyToMode esistenti.

Blocchi supportati:

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

Per impostazione predefinita, i componenti possono essere usati una sola volta. Imposta components.reusable=true per consentire l'uso ripetuto di pulsanti, selezioni e moduli fino alla scadenza.

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

Per impostazione predefinita, le callback dei componenti scadono dopo 30 minuti. Imposta channels.discord.agentComponents.ttlMs per modificare la durata del registro delle callback per l'account predefinito oppure channels.discord.accounts.<accountId>.agentComponents.ttlMs per ciascun account. Il valore è espresso in millisecondi, deve essere un numero intero positivo ed è limitato a 86400000 (24 ore). Durate più lunghe sono adatte ai flussi di revisione e approvazione che richiedono pulsanti utilizzabili più a lungo, ma estendono il periodo durante il quale un vecchio messaggio Discord può ancora attivare un'azione. Preferisci la durata più breve adatta allo scopo e mantieni quella predefinita quando callback obsolete potrebbero risultare inattese.

I comandi slash /model e /models aprono un selettore interattivo del modello con menu a discesa per provider, modello e runtime compatibili, seguito da un passaggio Submit. /models add è deprecato e restituisce un messaggio di deprecazione invece di registrare modelli dalla chat. La risposta del selettore è effimera e può essere usata solo dall'utente che l'ha richiamato. 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 rilevati dinamicamente solo per provider selezionati, come openai o vllm.

Allegati:

• I blocchi file devono fare riferimento a un allegato (attachment://<filename>)
• Fornisci l'allegato tramite media/path/filePath (file singolo); usa media-gallery per più file
• Usa filename per sovrascrivere il nome del caricamento quando deve corrispondere al riferimento dell'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 instradamento

{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: { enabled: true },        help: { enabled: true, requireMention: true },      },    },  },},},}

Instradamento degli agenti basato sui ruoli

Usa bindings[].match.roles per instradare i membri dei server Discord verso agenti diversi in base all'ID del ruolo. Le associazioni basate sui ruoli accettano solo ID di ruolo e vengono valutate dopo le associazioni tra interlocutori o interlocutori principali e prima delle associazioni basate esclusivamente sul server. Se un'associazione imposta anche altri campi di corrispondenza (ad 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 usa "auto" per impostazione predefinita ed è abilitato per Discord.
• Sostituzione per singolo canale: channels.discord.commands.native.
• commands.native=false evita la registrazione e la pulizia dei comandi slash di Discord durante l'avvio. I comandi registrati in precedenza potrebbero rimanere visibili in Discord finché non vengono rimossi dall'app Discord.
• L'autorizzazione dei comandi nativi usa gli stessi elenchi consentiti e le stesse policy di Discord usati per la normale gestione dei messaggi.
• I comandi potrebbero comunque essere visibili nell'interfaccia di Discord agli utenti non autorizzati; durante l'esecuzione viene applicata l'autorizzazione di OpenClaw e viene restituita la risposta "non autorizzato".
• Impostazioni predefinite dei comandi slash: ephemeral: true (channels.discord.slashCommand.ephemeral).

Consulta Comandi slash per il catalogo e il comportamento dei comandi.

Dettagli delle 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_...", // facoltativo; necessario per i sistemi privati  },},},}

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

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

{channels: {discord: {  activity: "Tempo di concentrazione",  activityType: 4,},},}

{channels: {discord: {  activity: "Programmazione in diretta",  activityType: 1,  activityUrl: "https://twitch.tv/openclaw",},},}

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

Strumenti e controlli delle azioni

Le azioni dei messaggi Discord comprendono messaggistica, amministrazione dei canali, moderazione, presenza e 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 un file locale) per impostare l'immagine di copertina dell'evento programmato.

I controlli delle azioni si trovano in channels.discord.actions.*.

Comportamento predefinito dei controlli:

Interfaccia utente Components v2

OpenClaw usa Components v2 di Discord per le approvazioni delle esecuzioni e gli indicatori tra contesti. Le azioni dei messaggi Discord possono anche accettare components per un'interfaccia utente personalizzata (funzionalità avanzata; richiede la creazione di un payload di componenti tramite lo strumento Discord), mentre i precedenti embeds rimangono disponibili ma non sono consigliati.

• channels.discord.ui.components.accentColor imposta il colore di accento usato dai contenitori dei componenti Discord (esadecimale). Per account: channels.discord.accounts.<id>.ui.components.accentColor.
• channels.discord.agentComponents.ttlMs controlla per quanto tempo le callback dei componenti Discord inviati rimangono registrate (valore predefinito 1800000, massimo 86400000). Per account: channels.discord.accounts.<id>.agentComponents.ttlMs.
• Gli embeds vengono ignorati quando sono presenti Components v2.
• Le anteprime degli URL semplici vengono soppresse per impostazione predefinita. Imposta suppressEmbeds: false in un'azione di messaggio quando deve essere espanso un singolo collegamento in uscita.

Esempio:

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

Voce

Discord dispone di due superfici vocali distinte: i canali vocali in tempo reale (conversazioni continue) e gli allegati di messaggi vocali (il formato di anteprima con forma d'onda). Il Gateway supporta entrambe.

Canali vocali

Elenco di controllo per la configurazione:

1. Abilita Message Content Intent nel Discord Developer Portal.
2. Abilita Server Members Intent quando vengono usate liste di ruoli/utenti consentiti.
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 relative alle liste di elementi consentiti e ai criteri di gruppo degli altri comandi Discord.

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

Per verificare le autorizzazioni effettive del bot prima dell'accesso:

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

Esempio di accesso automatico:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.6-sol",        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.1",          speakerVoice: "cedar",        },      },    },  },}

Note:

• La voce di Discord è facoltativa per le configurazioni di 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ò sostituire esplicitamente la sottoscrizione all'intent; lascialo non impostato per seguire l'abilitazione vocale effettiva.
• voice.mode controlla il percorso della conversazione. Il valore predefinito è agent-proxy: un front-end vocale in tempo reale gestisce la temporizzazione dei turni, le interruzioni 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 quell'interlocutore. stt-tts mantiene il precedente flusso STT in batch più TTS. bidi consente al modello in tempo reale di conversare direttamente, esponendo al contempo openclaw_agent_consult per il cervello OpenClaw.
• voice.agentSession controlla quale conversazione OpenClaw riceve i turni vocali. Lascialo non impostato per usare la sessione propria del canale vocale, oppure imposta { mode: "target", target: "channel:<text-channel-id>" } affinché il canale vocale agisca come estensione microfono/altoparlante della sessione di un canale di testo Discord esistente, come #maintainers.
• voice.model sostituisce il cervello dell'agente OpenClaw per le risposte vocali Discord e le consultazioni in tempo reale. Lascialo non impostato per ereditare il modello dell'agente instradato. È distinto da voice.realtime.model.
• voice.followUsers consente al bot di entrare, spostarsi e uscire dai canali vocali Discord insieme agli utenti selezionati. Consulta Seguire gli utenti nei canali vocali.
• agent-proxy instrada il parlato tramite discord-voice, che conserva la normale autorizzazione del proprietario e degli strumenti per l'interlocutore e la sessione di destinazione, ma nasconde lo strumento tts dell'agente perché la riproduzione è gestita dalla voce Discord. Per impostazione predefinita, agent-proxy concede alla consultazione un accesso agli strumenti completo ed equivalente a quello del proprietario per gli interlocutori proprietari (voice.realtime.toolPolicy: "owner") e privilegia fortemente la consultazione dell'agente OpenClaw prima delle risposte sostanziali (voice.realtime.consultPolicy: "always"). In questa modalità always predefinita, il livello in tempo reale non pronuncia automaticamente frasi riempitive prima della risposta della consultazione; acquisisce e trascrive il parlato, quindi pronuncia la risposta OpenClaw instradata. Se più risposte di consultazioni forzate terminano mentre Discord sta ancora riproducendo la prima risposta, le successive risposte con parlato esatto vengono accodate fino a quando la riproduzione non è inattiva, anziché sostituire il parlato a metà frase.
• In modalità stt-tts, STT usa tools.media.audio; voice.model non influisce sulla trascrizione.
• Nelle modalità in tempo reale, voice.realtime.provider, voice.realtime.model e voice.realtime.speakerVoice configurano la sessione audio in tempo reale. Per OpenAI Realtime 2.1 con il cervello Codex, usa voice.realtime.model: "gpt-realtime-2.1" e voice.model: "openai/gpt-5.6-sol".
• Per impostazione predefinita, le modalità vocali in tempo reale includono piccoli file di profilo IDENTITY.md, USER.md e SOUL.md nelle istruzioni del fornitore in tempo reale, affinché i turni diretti rapidi mantengano la stessa identità, lo stesso ancoraggio all'utente e la stessa persona dell'agente OpenClaw instradato. Imposta voice.realtime.bootstrapContextFiles su un sottoinsieme per personalizzare questo comportamento, oppure su [] per disabilitarlo. Sono supportati solo questi file di profilo; AGENTS.md rimane nel normale contesto dell'agente. Il contesto di profilo inserito non sostituisce openclaw_agent_consult per il lavoro nell'area di lavoro, i fatti correnti, la ricerca nella memoria o le azioni supportate da strumenti.
• Nella modalità in tempo reale agent-proxy di OpenAI, imposta voice.realtime.requireWakeName: true per mantenere silenziosa la voce Discord in tempo reale finché una trascrizione non inizia o termina con un nome di attivazione. I nomi di attivazione configurati devono essere composti da una o due parole. Se voice.realtime.wakeNames non è impostato, OpenClaw usa il name dell'agente instradato più OpenClaw, ripiegando sull'ID dell'agente più OpenClaw. Il controllo tramite nome di attivazione disabilita la risposta automatica del fornitore in tempo reale, instrada i turni accettati attraverso il percorso di consultazione dell'agente OpenClaw e fornisce un breve riscontro vocale quando un nome di attivazione iniziale viene riconosciuto dalla trascrizione parziale prima dell'arrivo della trascrizione finale.
• Il fornitore in tempo reale OpenAI accetta i nomi degli eventi Realtime 2 correnti e gli alias legacy compatibili con Codex per gli eventi dell'audio di output e della trascrizione, consentendo alle istantanee compatibili del fornitore di divergere senza perdere l'audio dell'assistente.
• voice.realtime.bargeIn controlla se gli eventi di inizio parlato di un interlocutore Discord interrompono la riproduzione in tempo reale attiva. Se non impostato, segue l'impostazione di interruzione tramite audio di input del fornitore in tempo reale.
• voice.realtime.minBargeInAudioEndMs controlla la durata minima della riproduzione dell'assistente prima che un'interruzione in tempo reale OpenAI tronchi l'audio. Valore predefinito: 250. Imposta 0 per l'interruzione immediata in ambienti con poco eco, oppure aumenta il valore per configurazioni con altoparlanti soggette a forte eco.
• voice.tts sostituisce messages.tts solo per la riproduzione vocale stt-tts; le modalità in tempo reale usano invece voice.realtime.speakerVoice. Per una voce OpenAI nella riproduzione Discord, imposta voice.tts.provider: "openai" e scegli una voce di sintesi vocale in voice.tts.providers.openai.speakerVoice. cedar è una valida scelta dal timbro maschile con l'attuale modello TTS di OpenAI.
• Le sostituzioni systemPrompt Discord specifiche per canale si applicano ai turni delle trascrizioni vocali di quel canale vocale.
• I turni delle trascrizioni vocali derivano lo stato di proprietario da allowFrom (o dm.allowFrom) di Discord per i comandi e le azioni del canale riservati al proprietario. La visibilità degli strumenti dell'agente segue la politica degli strumenti configurata per la sessione instradata.
• Se voice.autoJoin contiene più voci per lo stesso server, OpenClaw entra nell'ultimo canale configurato per quel server.
• voice.allowedChannels è una lista consentita facoltativa per la permanenza. Lascialo non impostato per consentire a /vc join di entrare in qualsiasi canale vocale Discord autorizzato. Quando è impostato, /vc join, l'ingresso automatico all'avvio e gli spostamenti dello stato vocale del bot sono limitati alle voci { guildId, channelId } elencate. Impostalo su un array vuoto per impedire tutti gli ingressi nei canali vocali Discord. Se Discord sposta il bot al di fuori della lista consentita, OpenClaw lascia quel canale e rientra nella destinazione di ingresso automatico configurata, se disponibile.
• voice.daveEncryption e voice.decryptionFailureTolerance vengono passati alle opzioni di ingresso di @discordjs/voice; i valori predefiniti a monte sono daveEncryption=true e decryptionFailureTolerance=24.
• OpenClaw usa il codec libopus-wasm incluso per la ricezione vocale Discord e la riproduzione PCM grezza in tempo reale. Include una build WebAssembly di libopus con versione bloccata e non richiede componenti aggiuntivi opus nativi.
• voice.connectTimeoutMs controlla l'attesa iniziale dello stato Ready di @discordjs/voice per /vc join e i tentativi di ingresso automatico. Valore predefinito: 30000.
• voice.reconnectGraceMs controlla per quanto tempo OpenClaw attende che una sessione vocale disconnessa inizi a riconnettersi prima di eliminarla. Valore predefinito: 15000.
• In modalità stt-tts, la riproduzione vocale non si interrompe solo perché un altro utente inizia a parlare. Per evitare cicli di feedback, OpenClaw ignora le nuove acquisizioni vocali durante la riproduzione TTS; per il turno successivo, parla al termine della riproduzione. Le modalità in tempo reale inoltrano gli inizi del parlato come segnali di interruzione al fornitore in tempo reale.
• Nelle modalità in tempo reale, l'eco degli altoparlanti captato da un microfono aperto può essere interpretato come un'interruzione e fermare la riproduzione. Per le stanze Discord con forte eco, imposta voice.realtime.providers.openai.interruptResponseOnInputAudio: false per impedire a OpenAI di interrompersi automaticamente in presenza di audio di input. Aggiungi voice.realtime.bargeIn: true se vuoi comunque che gli eventi di inizio parlato di Discord interrompano la riproduzione attiva. Il bridge in tempo reale OpenAI ignora i troncamenti della riproduzione più brevi di voice.realtime.minBargeInAudioEndMs, considerandoli probabile eco o rumore, e li registra come ignorati anziché cancellare la riproduzione Discord.
• voice.captureSilenceGraceMs controlla per quanto tempo OpenClaw attende dopo che Discord segnala che un interlocutore ha smesso di parlare, prima di finalizzare quel segmento audio per STT. Valore predefinito: 2000; aumentalo se Discord suddivide le pause normali in trascrizioni parziali frammentarie.
• Quando ElevenLabs è il fornitore TTS selezionato, la riproduzione vocale Discord usa il TTS in streaming e inizia dal flusso di risposta del fornitore. I fornitori senza supporto per lo streaming ripiegano sul percorso del file temporaneo sintetizzato.
• OpenClaw monitora gli errori di decrittazione in ricezione e si ripristina automaticamente uscendo e rientrando nel canale vocale dopo errori ripetuti in un breve intervallo.
• Se, dopo un aggiornamento, i registri di ricezione mostrano ripetutamente DecryptionFailed(UnencryptedWhenPassthroughDisabled), raccogli un rapporto sulle dipendenze e i registri. La versione inclusa di @discordjs/voice comprende la correzione a monte del padding dalla PR #11449 di discord.js, che ha chiuso il problema #11419 di discord.js.
• Gli eventi di ricezione The operation was aborted sono previsti quando OpenClaw finalizza un segmento acquisito dell'interlocutore; sono informazioni diagnostiche dettagliate, non avvisi.
• I registri vocali dettagliati di Discord includono un'anteprima delimitata su una riga della trascrizione STT per ogni segmento accettato dell'interlocutore, così il debug mostra sia il lato dell'utente sia quello della risposta dell'agente senza riversare testo di trascrizione senza limiti.
• In modalità agent-proxy, il ripiego della consultazione forzata ignora i frammenti di trascrizione probabilmente incompleti, come il testo che termina con ... o con un connettivo finale come "e", oltre alle ovvie chiusure che non richiedono azioni, come "torno subito" o "ciao". I registri mostrano forced agent consult skipped reason=... quando ciò impedisce una risposta obsoleta in coda.

Seguire gli utenti nei canali vocali

Usa voice.followUsers quando vuoi che il bot vocale Discord rimanga con uno o più utenti Discord noti, anziché 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 dello stato vocale.
• followUsersEnabled assume come valore predefinito true quando followUsers è configurato. Impostalo su false per conservare 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 si trovano nello stesso server e l'utente seguito attivo esce, OpenClaw si sposta nel canale di un altro utente seguito monitorato prima di lasciare il server. Se più utenti seguiti si spostano contemporaneamente, prevale l'ultimo evento dello stato vocale osservato.
• allowedChannels continua ad applicarsi. Un utente seguito in un canale non consentito viene ignorato e una sessione appartenente alla funzione di seguito si sposta presso un altro utente seguito oppure esce.
• OpenClaw riconcilia gli eventi dello stato vocale persi all'avvio e a intervalli limitati. La riconciliazione campiona i server configurati e limita le ricerche REST per esecuzione, quindi elenchi followUsers molto grandi potrebbero richiedere più di un intervallo per convergere.
• Se Discord o un amministratore sposta il bot mentre sta seguendo un utente, OpenClaw ricrea la sessione vocale e conserva la titolarità del seguito quando la destinazione è consentita. Se il bot viene spostato al di fuori di allowedChannels, OpenClaw esce e rientra nella destinazione configurata, se esiste.
• Il ripristino della ricezione DAVE può uscire e rientrare nello stesso canale dopo ripetuti errori di decrittazione. Le sessioni appartenenti alla funzione di seguito mantengono tale titolarità durante questo percorso di ripristino, quindi una successiva disconnessione dell'utente seguito provoca comunque l'uscita dal canale.

Scegli tra le modalità di ingresso:

• Usa followUsers per configurazioni personali o operative in cui il bot deve trovarsi automaticamente nel canale vocale quando ci sei tu.
• Usa autoJoin per bot destinati a stanze fisse, che devono essere presenti anche quando nessun utente monitorato si trova in un canale vocale.
• Usa /vc join per ingressi occasionali o stanze in cui una presenza vocale automatica sarebbe inattesa.

Codec vocale Discord:

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

Pipeline STT più TTS:

• L'acquisizione PCM di Discord viene convertita in un file WAV temporaneo.
• tools.media.audio gestisce la conversione da voce a testo, ad esempio openai/gpt-4o-mini-transcribe.
• La trascrizione viene inviata attraverso l'ingresso e l'instradamento di Discord mentre il modello linguistico di risposta viene eseguito con una politica di output vocale che nasconde lo strumento tts dell'agente e richiede la restituzione di testo, poiché la voce Discord gestisce la riproduzione finale della sintesi vocale.
• voice.model, quando impostato, sostituisce solo il modello linguistico di risposta per questo turno del canale vocale.
• voice.tts viene sovrapposto a messages.tts; i provider che supportano lo streaming alimentano direttamente il lettore, altrimenti il file audio risultante viene riprodotto nel canale a cui il bot si è unito.

Esempio di sessione del canale vocale con proxy dell'agente predefinito:

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

Senza un blocco voice.agentSession, ogni canale vocale dispone di una propria sessione OpenClaw instradata. Ad esempio, /vc join channel:234567890123456789 comunica con la sessione di quel canale vocale Discord. Il modello in tempo reale costituisce soltanto l'interfaccia 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 ripiego, affinché il comportamento predefinito rimanga equivalente a parlare con l'agente.

Esempio di riconoscimento vocale più sintesi vocale precedente:

{  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 bidirezionale in tempo reale:

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

Voce come estensione della sessione di un canale Discord esistente:

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

In modalità agent-proxy, il bot si unisce al canale vocale configurato, ma i turni dell'agente OpenClaw utilizzano l'agente e la normale sessione instradata del canale di destinazione. La sessione vocale in tempo reale pronuncia il risultato restituito nel canale vocale. L'agente supervisore può comunque utilizzare i normali strumenti di messaggistica in base alla propria politica degli strumenti, compreso l'invio di un messaggio Discord separato se questa è l'azione appropriata.

Mentre è attiva un'esecuzione OpenClaw delegata, le nuove trascrizioni vocali di Discord vengono trattate come controllo in tempo reale dell'esecuzione prima di avviare un altro turno dell'agente. Frasi come "stato", "annulla", "usa la correzione più piccola" o "quando hai finito controlla anche i test" vengono classificate come input di stato, annullamento, guida o follow-up per la sessione attiva. Gli esiti relativi a stato, annullamento, guida accettata e follow-up vengono pronunciati nel canale vocale, in modo che il chiamante sappia se OpenClaw ha gestito la richiesta.

Forme di destinazione utili:

• target: "channel:123456789012345678" instrada attraverso la sessione di un canale testuale Discord.
• target: "123456789012345678" viene considerato come destinazione di un canale.
• target: "dm:123456789012345678" o target: "user:123456789012345678" instrada attraverso la sessione di messaggistica diretta corrispondente.

Esempio di OpenAI Realtime con forte presenza di eco:

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

Utilizzare questa configurazione quando il modello sente la propria riproduzione Discord attraverso un microfono aperto, ma si desidera comunque interromperlo parlando. OpenClaw impedisce a OpenAI di interrompersi automaticamente sull'audio di ingresso grezzo, mentre bargeIn: true consente agli eventi di inizio intervento di Discord e all'audio di un interlocutore 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 considerati probabile eco o rumore e ignorati, affinché il modello non si interrompa al primo fotogramma di riproduzione.

Log vocali previsti:

• 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 dell'interlocutore: 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=...
• Quando viene ignorato un parlato obsoleto: 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 o alla reimpostazione della riproduzione: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• Alla consultazione in tempo reale: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• Alla risposta dell'agente: discord voice: agent turn answer ...
• Quando viene accodato il parlato esatto: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=..., seguito da discord voice: realtime exact speech dequeued reason=player-idle ...
• Al rilevamento dell'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 ...
• Quando vengono ignorati eco o rumore: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• Quando l'interruzione è disabilitata: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• Durante la riproduzione inattiva: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

Per eseguire il debug dell'audio interrotto, leggere i log vocali in tempo reale come una sequenza cronologica:

1. realtime audio playback started indica che Discord ha iniziato a riprodurre l'audio dell'assistente. Da questo momento, il bridge inizia a contare i segmenti di output dell'assistente, i byte PCM di Discord, i byte in tempo reale del provider e la durata dell'audio sintetizzato.
2. realtime speaker turn opened indica che un interlocutore Discord è diventato attivo. Se la riproduzione è già attiva e bargeIn è abilitato, può essere seguito da barge-in detected source=speaker-start.
3. realtime input audio started indica il primo fotogramma audio effettivo ricevuto per il turno di quell'interlocutore. outputActive=true o un valore outputAudioMs diverso da zero indica che il microfono sta inviando input mentre la riproduzione dell'assistente è ancora attiva.
4. barge-in detected source=active-speaker-audio indica che OpenClaw ha rilevato audio in tempo reale dell'interlocutore mentre era attiva la riproduzione dell'assistente. Ciò è utile per distinguere un'interruzione reale da un evento di inizio intervento di Discord privo di audio utile.
5. barge-in requested reason=... indica che OpenClaw ha chiesto al provider in tempo reale di annullare o troncare la risposta attiva. Include outputAudioMs, outputActive e playbackChunks, consentendo di vedere quanto audio dell'assistente fosse stato effettivamente riprodotto prima dell'interruzione.
6. realtime audio playback stopped reason=... è il punto di reimpostazione della riproduzione locale di Discord. Il motivo indica chi ha arrestato 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 indica che il turno dell'interlocutore è stato aperto, ma nessun audio utilizzabile ha raggiunto il bridge in tempo reale. interruptedPlayback=true indica 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 dell'arresto della riproduzione.
• elapsedMs: tempo trascorso effettivo tra l'apertura e la chiusura del flusso di riproduzione o del turno dell'interlocutore.
• discordBytes: byte PCM stereo a 48 kHz inviati alla voce Discord o ricevuti da essa.
• realtimeBytes: byte PCM nel formato del provider inviati al provider in tempo reale o ricevuti da esso.
• playbackChunks: segmenti audio dell'assistente inoltrati a Discord per la risposta attiva.
• sinceLastAudioMs: intervallo tra l'ultimo fotogramma audio acquisito dell'interlocutore e la chiusura del suo turno.

Schemi comuni:

• Un'interruzione immediata con source=active-speaker-audio, un valore outputAudioMs ridotto e lo stesso utente nelle vicinanze indica generalmente che l'eco degli altoparlanti entra nel microfono. Aumentare voice.realtime.minBargeInAudioEndMs, ridurre il volume degli altoparlanti, utilizzare cuffie oppure impostare voice.realtime.providers.openai.interruptResponseOnInputAudio: false.
• source=speaker-start seguito da speaker turn closed ... hasAudio=false indica che Discord ha segnalato l'inizio di un intervento, ma nessun audio ha raggiunto OpenClaw. Può trattarsi di un evento vocale transitorio di Discord, del comportamento della soglia del rumore o di un client che attiva brevemente il microfono.
• audio playback stopped reason=stream-close senza un'interruzione o un evento provider-clear-audio nelle vicinanze indica che il flusso di riproduzione locale di Discord è terminato inaspettatamente. Controllare i log precedenti del provider e del lettore Discord.
• capture ignored during playback (barge-in disabled) indica che OpenClaw ha intenzionalmente scartato l'input mentre l'audio dell'assistente era attivo. Abilitare voice.realtime.bargeIn se si desidera che il parlato interrompa la riproduzione.
• barge-in ignored ... outputActive=false indica che Discord o il rilevamento dell'attività vocale del provider ha segnalato del parlato, ma OpenClaw non disponeva di una riproduzione attiva da interrompere. Ciò non dovrebbe interrompere l'audio.

Le credenziali vengono risolte separatamente per ciascun componente: autenticazione dell'instradamento del modello linguistico per voice.model, autenticazione del riconoscimento vocale per tools.media.audio, autenticazione della sintesi vocale per messages.tts/voice.tts e autenticazione del provider in tempo reale per voice.realtime.providers o per 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 necessita di ffmpeg e ffprobe sull'host del Gateway per eseguire l'analisi e la conversione.

• Fornire un percorso di file locale (gli URL vengono rifiutati).
• Omettere il contenuto testuale (Discord rifiuta testo e messaggio vocale nello stesso payload).
• È accettato qualsiasi formato audio; OpenClaw lo 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: {    alpha: {      // Alpha listens to other bots only when they mention it.      allowBots: "mentions",    },    bravo: {      // Bravo listens to all bot-authored Discord messages.      allowBots: true,      mentionAliases: {        // Lets Bravo write an Alpha Discord mention with the configured user id.        Alpha: "ALPHA_DISCORD_USER_ID",      },      botLoopProtection: {        // Allow up to five messages per minute before suppressing the pair.        maxEventsPerWindow: 5,        windowSeconds: 60,        cooldownSeconds: 90,      },    },  },},},}

Riferimento della configurazione

Riferimento principale: Riferimento della configurazione - Discord.

Sicurezza e operazioni

• Tratta i token dei bot come segreti (DISCORD_BOT_TOKEN è preferibile negli ambienti supervisionati).
• Concedi a Discord autorizzazioni con privilegi minimi.
• Se la distribuzione o lo stato dei comandi non è aggiornato, riavvia il Gateway e ricontrolla con openclaw channels status --probe.

Argomenti correlati