Discord

​

Configurazione rapida

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" },
    },
  },
}
JSON5
openclaw config patch --file ./discord.patch.json5 --dry-run
openclaw config patch --file ./discord.patch.json5
openclaw 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 discord
openclaw pairing approve discord <CODE>

​

Consigliato: configura uno spazio di lavoro nel server

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

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

​

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

• 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.

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

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

​

Componenti interattivi

• 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

• 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

• 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

{
  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

{
  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).

​

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

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

​

Interfaccia utente Components v2

• 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.

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

​

Voce

​

Canali vocali

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.

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

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

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

• 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

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

• 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.

• 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.

• 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.

• 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.

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

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

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

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

• 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.

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

• 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

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.

• 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.

• 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.

​

Messaggi vocali

• 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 doctor
openclaw channels status --probe
openclaw 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

​

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