Discord

Klaar voor DM's en guild-kanalen via de officiële Discord Gateway.

Snelle installatie

Je moet een nieuwe applicatie met een bot maken, de bot aan je server toevoegen en deze aan OpenClaw koppelen. We raden aan je bot aan je eigen privéserver toe te voegen. Als je er nog geen hebt, maak er dan eerst een (kies 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>

Aanbevolen: stel een guild-werkruimte in

Zodra DM's werken, kun je je Discord-server instellen als een volledige werkruimte waarin elk kanaal zijn eigen agentsessie met eigen context krijgt. Dit wordt aanbevolen voor privéservers waar alleen jij en je bot aanwezig zijn.

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

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

Maak nu enkele kanalen op je Discord-server en begin met chatten. Je agent kan de kanaalnaam zien, en elk kanaal krijgt zijn eigen geïsoleerde sessie — dus je kunt #coding, #home, #research instellen, of wat ook bij je workflow past.

Runtimemodel

• Gateway beheert de Discord-verbinding.
• Antwoordroutering is deterministisch: inkomende Discord-antwoorden gaan terug naar Discord.
• Discord-guild-/kanaalmetadata wordt toegevoegd aan de modelprompt als niet-vertrouwde context, niet als een voor gebruikers zichtbaar antwoordvoorvoegsel. Als een model die envelop terug kopieert, verwijdert OpenClaw de gekopieerde metadata uit uitgaande antwoorden en uit toekomstige replaycontext.
• Standaard (session.dmScope=main) delen directe chats de hoofdsessie van de agent (agent:main:main).
• Guild-kanalen zijn geisoleerde sessiesleutels (agent:<agentId>:discord:channel:<channelId>).
• Groeps-DM's worden standaard genegeerd (channels.discord.dm.groupEnabled=false).
• Native slash-commando's draaien in geisoleerde commandosessies (agent:<agentId>:discord:slash:<userId>), terwijl ze nog steeds CommandTargetSessionKey meenemen naar de gerouteerde gesprekssessie.
• Alleen-tekst cron-/Heartbeat-aankondigingslevering aan Discord gebruikt eenmaal het uiteindelijke voor de assistent zichtbare antwoord. Media en gestructureerde componentpayloads blijven meerdere berichten wanneer de agent meerdere leverbare payloads uitzendt.

Forumkanalen

Discord-forum- en mediakanalen accepteren alleen threadberichten. OpenClaw ondersteunt twee manieren om ze aan te maken:

• Stuur een bericht naar de forumbovenliggende (channel:<forumId>) om automatisch een thread aan te maken. De threadtitel gebruikt de eerste niet-lege regel van je bericht.
• Gebruik openclaw message thread create om direct een thread aan te maken. Geef geen --message-id door voor forumkanalen.

Voorbeeld: stuur naar forumbovenliggende om een thread aan te maken

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

Voorbeeld: maak expliciet een forumthread aan

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

Forumbovenliggende accepteren geen Discord-componenten. Als je componenten nodig hebt, stuur dan naar de thread zelf (channel:<threadId>).

Interactieve componenten

OpenClaw ondersteunt Discord components v2-containers voor agentberichten. Gebruik de berichttool met een components-payload. Interactieresultaten worden als normale inkomende berichten terug naar de agent gerouteerd en volgen de bestaande Discord-instellingen voor replyToMode.

Ondersteunde blokken:

• text, section, separator, actions, media-gallery, file
• Actierijen staan maximaal 5 knoppen of een enkel selectiemenu toe
• Selectietypen: string, user, role, mentionable, channel

Standaard zijn componenten eenmalig te gebruiken. Stel components.reusable=true in om knoppen, selecties en formulieren meerdere keren te kunnen gebruiken totdat ze verlopen.

Stel allowedUsers op die knop in om te beperken wie op een knop kan klikken (Discord-gebruikers-ID's, tags of *). Wanneer dit is geconfigureerd, ontvangen niet-overeenkomende gebruikers een ephemeral weigering.

De slash-commando's /model en /models openen een interactieve modelkiezer met dropdowns voor provider, model en compatibele runtime plus een verzendstap. /models add is verouderd en retourneert nu een verouderingsbericht in plaats van modellen vanuit chat te registreren. Het antwoord van de kiezer is ephemeral en alleen de aanroepende gebruiker kan het gebruiken. Discord-selectiemenu's zijn beperkt tot 25 opties, dus voeg provider/*-vermeldingen toe aan agents.defaults.models wanneer je wilt dat de kiezer dynamisch ontdekte modellen alleen toont voor geselecteerde providers zoals openai-codex of vllm.

Bestandsbijlagen:

• file-blokken moeten verwijzen naar een bijlagereferentie (attachment://<filename>)
• Lever de bijlage via media/path/filePath (enkel bestand); gebruik media-gallery voor meerdere bestanden
• Gebruik filename om de uploadnaam te overschrijven wanneer die moet overeenkomen met de bijlagereferentie

Modale formulieren:

• Voeg components.modal toe met maximaal 5 velden
• Veldtypen: text, checkbox, radio, select, role-select, user-select
• OpenClaw voegt automatisch een triggerknop toe

Voorbeeld:

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

Toegangscontrole en routering

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

Rolgebaseerde agentroutering

Gebruik bindings[].match.roles om Discord-guildleden op basis van rol-ID naar verschillende agents te routeren. Rolgebaseerde bindings accepteren alleen rol-ID's en worden geevalueerd na peer- of parent-peer-bindings en voor guild-only-bindings. Als een binding ook andere matchvelden instelt (bijvoorbeeld peer + guildId + roles), moeten alle geconfigureerde velden overeenkomen.

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

Native commando's en commando-auth

• commands.native is standaard "auto" en is ingeschakeld voor Discord.
• Override per kanaal: channels.discord.commands.native.
• commands.native=false slaat Discord-slashcommandregistratie en opschoning tijdens het opstarten over. Eerder geregistreerde commando's kunnen zichtbaar blijven in Discord totdat je ze uit de Discord-app verwijdert.
• Native commando-auth gebruikt dezelfde Discord-allowlists/beleidsregels als normale berichtverwerking.
• Commando's kunnen nog steeds zichtbaar zijn in de Discord-UI voor gebruikers die niet zijn geautoriseerd; uitvoering dwingt nog steeds OpenClaw-auth af en retourneert "not authorized".

Zie Slashcommands voor de commandocatalogus en het gedrag.

Standaardinstellingen voor slashcommands:

• ephemeral: true

Functiedetails

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

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

Tools en actiepoorten

Discord-berichtacties omvatten berichten, kanaalbeheer, moderatie, aanwezigheid en metadata-acties.

Kernvoorbeelden:

• berichten: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• reacties: react, reactions, emojiList
• moderatie: timeout, kick, ban
• aanwezigheid: setPresence

De actie event-create accepteert een optionele parameter image (URL of lokaal bestandspad) om de omslagafbeelding van de geplande gebeurtenis in te stellen.

Actiepoorten bevinden zich onder channels.discord.actions.*.

Standaardgedrag van poorten:

Components v2-UI

OpenClaw gebruikt Discord components v2 voor exec-goedkeuringen en cross-context-markeringen. Discord-berichtacties kunnen ook components accepteren voor aangepaste UI (geavanceerd; vereist het construeren van een componentpayload via de discord-tool), terwijl legacy embeds beschikbaar blijven maar niet worden aanbevolen.

• channels.discord.ui.components.accentColor stelt de accentkleur in die wordt gebruikt door Discord-componentcontainers (hex).
• Stel per account in met channels.discord.accounts.<id>.ui.components.accentColor.
• embeds worden genegeerd wanneer components v2 aanwezig zijn.

Voorbeeld:

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

Spraak

Discord heeft twee afzonderlijke spraakoppervlakken: realtime spraakkanalen (doorlopende gesprekken) en spraakberichtbijlagen (de golfvormpreview-indeling). De gateway ondersteunt beide.

Spraakkanalen

Installatiechecklist:

1. Schakel Message Content Intent in de Discord Developer Portal in.
2. Schakel Server Members Intent in wanneer allowlists voor rollen/gebruikers worden gebruikt.
3. Nodig de bot uit met de scopes bot en applications.commands.
4. Verleen Connect, Speak, Send Messages en Read Message History in het doelspraakkanaal.
5. Schakel native opdrachten in (commands.native of channels.discord.commands.native).
6. Configureer channels.discord.voice.

Gebruik /vc join|leave|status om sessies te beheren. De opdracht gebruikt de standaardagent van het account en volgt dezelfde allowlist- en groepsbeleidsregels als andere Discord-opdrachten.

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

Voer het volgende uit om de effectieve machtigingen van de bot te inspecteren voordat je toetreedt:

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

Voorbeeld van automatisch toetreden:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai-codex/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",          voice: "cedar",        },      },    },  },}

Opmerkingen:

• voice.tts overschrijft messages.tts alleen voor stt-tts-stemweergave. Realtime-modi gebruiken voice.realtime.voice.
• voice.mode bepaalt het gesprekspad. De standaardwaarde is agent-proxy: een realtime voice-front-end verwerkt beurt-timing, onderbreking en weergave, delegeert inhoudelijk werk aan de gerouteerde OpenClaw-agent via openclaw_agent_consult, en behandelt het resultaat als een getypte Discord-prompt van die spreker. stt-tts behoudt de oudere batch-STT plus TTS-stroom. Met bidi kan het realtime-model rechtstreeks converseren terwijl openclaw_agent_consult beschikbaar blijft voor het OpenClaw-brein.
• voice.agentSession bepaalt welk OpenClaw-gesprek stembeurten ontvangt. Laat dit ongezet voor de eigen sessie van het spraakkanaal, of stel { mode: "target", target: "channel:<text-channel-id>" } in om het spraakkanaal te laten fungeren als microfoon-/luidsprekeruitbreiding van een bestaande Discord-tekstkanaalsessie zoals #maintainers.
• voice.model overschrijft het OpenClaw-agentbrein voor Discord-stemreacties en realtime-consults. Laat dit ongezet om het gerouteerde agentmodel te erven. Het staat los van voice.realtime.model.
• agent-proxy routeert spraak via discord-voice, waardoor de normale eigenaar-/toolautorisatie voor de spreker en doelsessie behouden blijft, maar de agenttool tts wordt verborgen omdat Discord voice eigenaar is van de weergave. Standaard geeft agent-proxy de consult volledige eigenaar-equivalente tooltoegang voor eigenaars-sprekers (voice.realtime.toolPolicy: "owner") en geeft het sterk de voorkeur aan het raadplegen van de OpenClaw-agent vóór inhoudelijke antwoorden (voice.realtime.consultPolicy: "always"). In die standaardmodus always spreekt de realtime-laag niet automatisch opvulling uit vóór het consultantwoord; deze legt spraak vast en transcribeert die, en spreekt daarna het gerouteerde OpenClaw-antwoord uit. Als meerdere afgedwongen consultantwoorden klaar zijn terwijl Discord nog steeds het eerste antwoord afspeelt, worden latere antwoorden met exacte spraak in een wachtrij gezet totdat de weergave inactief is, in plaats van spraak midden in een zin te vervangen.
• In de modus stt-tts gebruikt STT tools.media.audio; voice.model heeft geen invloed op transcriptie.
• In realtime-modi configureren voice.realtime.provider, voice.realtime.model en voice.realtime.voice de realtime-audiosessie. Gebruik voor OpenAI Realtime 2 plus het Codex-brein voice.realtime.model: "gpt-realtime-2" en voice.model: "openai-codex/gpt-5.5".
• De realtime-provider van OpenAI accepteert huidige Realtime 2-gebeurtenisnamen en legacy Codex-compatibele aliassen voor uitvoeraudio- en transcriptgebeurtenissen, zodat compatibele providersnapshots kunnen verschuiven zonder assistentaudio te laten wegvallen.
• voice.realtime.bargeIn bepaalt of spreker-startgebeurtenissen van Discord actieve realtime-weergave onderbreken. Als dit ongezet is, volgt het de instelling voor input-audio-onderbreking van de realtime-provider.
• voice.realtime.minBargeInAudioEndMs bepaalt de minimale duur van assistentweergave voordat een OpenAI realtime-barge-in audio afkapt. Standaard: 250. Stel 0 in voor onmiddellijke onderbreking in ruimtes met weinig echo, of verhoog dit voor luidsprekeropstellingen met veel echo.
• Stel voor een OpenAI-stem bij Discord-weergave voice.tts.provider: "openai" in en kies een Text-to-speech-stem onder voice.tts.openai.voice of voice.tts.providers.openai.voice. cedar is een goede mannelijk klinkende keuze op het huidige OpenAI TTS-model.
• Per-kanaal Discord-overschrijvingen voor systemPrompt zijn van toepassing op stemtranscriptbeurten voor dat spraakkanaal.
• Stemtranscriptbeurten leiden de eigenaarsstatus af van Discord allowFrom (of dm.allowFrom); niet-eigenaarsprekers hebben geen toegang tot tools die alleen voor eigenaars zijn (bijvoorbeeld gateway en cron).
• Discord voice is opt-in voor tekst-only configuraties; stel channels.discord.voice.enabled=true in (of behoud een bestaand channels.discord.voice-blok) om /vc-opdrachten, de voice-runtime en de GuildVoiceStates Gateway-intent in te schakelen.
• channels.discord.intents.voiceStates kan het abonnement op de voice-state-intent expliciet overschrijven. Laat dit ongezet zodat de intent de effectieve voice-inschakeling volgt.
• Als voice.autoJoin meerdere items voor dezelfde guild heeft, sluit OpenClaw aan bij het laatst geconfigureerde kanaal voor die guild.
• voice.allowedChannels is een optionele allowlist voor verblijf. Laat dit ongezet om /vc join toe te staan in elk geautoriseerd Discord-spraakkanaal. Wanneer dit is ingesteld, zijn /vc join, automatisch aansluiten bij opstarten en verplaatsingen van de bot-voice-state beperkt tot de vermelde { guildId, channelId }-items. Stel dit in op een lege array om alle Discord voice-joins te weigeren. Als Discord de bot buiten de allowlist verplaatst, verlaat OpenClaw dat kanaal en sluit het opnieuw aan bij het geconfigureerde auto-join-doel wanneer er een beschikbaar is.
• voice.daveEncryption en voice.decryptionFailureTolerance worden doorgegeven aan de join-opties van @discordjs/voice.
• De standaardwaarden van @discordjs/voice zijn daveEncryption=true en decryptionFailureTolerance=24 als ze ongezet zijn.
• OpenClaw gebruikt standaard de pure-JS opusscript-decoder voor het ontvangen van Discord voice. Het optionele native pakket @discordjs/opus wordt genegeerd door het pnpm-installatiebeleid van de repo, zodat normale installaties, Docker-lanes en niet-gerelateerde tests geen native addon compileren. Toegewijde hosts voor voice-performance kunnen opt-in gebruiken met OPENCLAW_DISCORD_OPUS_DECODER=native nadat de native addon is geïnstalleerd.
• voice.connectTimeoutMs bepaalt de initiële @discordjs/voice Ready-wachttijd voor /vc join en auto-join-pogingen. Standaard: 30000.
• voice.reconnectGraceMs bepaalt hoelang OpenClaw wacht totdat een verbroken voicesessie opnieuw begint te verbinden voordat deze wordt vernietigd. Standaard: 15000.
• In de modus stt-tts stopt stemweergave niet alleen omdat een andere gebruiker begint te spreken. Om feedbackloops te voorkomen, negeert OpenClaw nieuwe stemopname terwijl TTS wordt afgespeeld; spreek nadat de weergave is voltooid voor de volgende beurt. Realtime-modi sturen spreker-startsignalen door als barge-in-signalen naar de realtime-provider.
• In realtime-modi kan echo van luidsprekers in een open microfoon lijken op barge-in en weergave onderbreken. Stel voor Discord-ruimtes met veel echo voice.realtime.providers.openai.interruptResponseOnInputAudio: false in om te voorkomen dat OpenAI automatisch onderbreekt bij input-audio. Voeg voice.realtime.bargeIn: true toe als je nog steeds wilt dat spreker-startgebeurtenissen van Discord actieve weergave onderbreken. De OpenAI realtime-bridge negeert afkappingen van weergave die korter zijn dan voice.realtime.minBargeInAudioEndMs als waarschijnlijke echo/ruis en logt ze als overgeslagen in plaats van Discord-weergave te wissen.
• voice.captureSilenceGraceMs bepaalt hoelang OpenClaw wacht nadat Discord meldt dat een spreker is gestopt voordat dat audiosegment voor STT wordt afgerond. Standaard: 2500; verhoog dit als Discord normale pauzes opsplitst in haperige gedeeltelijke transcripties.
• Wanneer ElevenLabs de geselecteerde TTS-provider is, gebruikt Discord-stemweergave streaming-TTS en start deze vanuit de providerresponsstream. Providers zonder streamingondersteuning vallen terug op het pad met een gesynthetiseerd tijdelijk bestand.
• OpenClaw bewaakt ook decryptiefouten bij ontvangst en herstelt automatisch door het spraakkanaal te verlaten en opnieuw te joinen na herhaalde fouten binnen een kort tijdsvenster.
• Als ontvangstlogs na een update herhaaldelijk DecryptionFailed(UnencryptedWhenPassthroughDisabled) tonen, verzamel dan een dependencyrapport en logs. De gebundelde @discordjs/voice-lijn bevat de upstream padding-fix uit discord.js PR #11449, waarmee discord.js issue #11419 werd gesloten.
• Ontvangstgebeurtenissen The operation was aborted worden verwacht wanneer OpenClaw een vastgelegd sprekersegment afrondt; het zijn uitgebreide diagnostische meldingen, geen waarschuwingen.
• Uitgebreide Discord voice-logs bevatten een begrensde eenregelige STT-transcriptpreview voor elk geaccepteerd sprekersegment, zodat debugging zowel de gebruikerskant als de agentantwoordkant toont zonder onbeperkte transcripttekst te dumpen.
• In de modus agent-proxy slaat afgedwongen consultfallback waarschijnlijk onvolledige transcriptfragmenten over, zoals tekst die eindigt op ... of een afsluitende connector zoals and, plus duidelijk niet-actiegerichte afsluitingen zoals “be right back” of “bye”. Logs tonen forced agent consult skipped reason=... wanneer dit een verouderd antwoord in de wachtrij voorkomt.

Native opus-installatie voor source-checkouts:

pnpm installmise exec node@22 -- pnpm discord:opus:install

Gebruik Node 22 voor de Gateway wanneer je de upstream macOS arm64 vooraf gebouwde native addon wilt. Als je een andere Node-runtime gebruikt, kan de opt-in-installer een lokale node-gyp source-build-toolchain nodig hebben.

Start na installatie van de native addon de Gateway met:

OPENCLAW_DISCORD_OPUS_DECODER=native pnpm gateway:watch

Uitgebreide voice-logs zouden discord voice: opus decoder: @discordjs/opus moeten tonen. Zonder de env-opt-in, of als de native addon ontbreekt of niet op de host kan laden, logt OpenClaw discord voice: opus decoder: opusscript en blijft het voice ontvangen via de pure-JS fallback.

STT plus TTS-pijplijn:

• Discord PCM-opname wordt geconverteerd naar een tijdelijk WAV-bestand.
• tools.media.audio verwerkt STT, bijvoorbeeld openai/gpt-4o-mini-transcribe.
• Het transcript wordt via Discord-ingress en routering verzonden terwijl de response-LLM draait met een voice-outputbeleid dat de agenttool tts verbergt en om teruggegeven tekst vraagt, omdat Discord voice eigenaar is van de uiteindelijke TTS-weergave.
• voice.model, wanneer ingesteld, overschrijft alleen de response-LLM voor deze spraakkanaalbeurt.
• voice.tts wordt over messages.tts samengevoegd; providers met streamingmogelijkheden voeden de speler rechtstreeks, anders wordt het resulterende audiobestand afgespeeld in het gejoinde kanaal.

Standaardvoorbeeld van een agent-proxy-spraakkanaalsessie:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai-codex/gpt-5.5",        realtime: {          provider: "openai",          model: "gpt-realtime-2",          voice: "cedar",        },      },    },  },}

Zonder voice.agentSession-blok krijgt elk spraakkanaal zijn eigen gerouteerde OpenClaw-sessie. Bijvoorbeeld, /vc join channel:234567890123456789 praat met de sessie voor dat Discord-spraakkanaal. Het realtime-model is alleen de voice-front-end; inhoudelijke verzoeken worden doorgegeven aan de geconfigureerde OpenClaw-agent. Als het realtime-model een definitief transcript produceert zonder de consulttool aan te roepen, dwingt OpenClaw het consult af als fallback, zodat de standaard nog steeds werkt alsof je met de agent praat.

Legacy STT plus TTS-voorbeeld:

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

Realtime bidi-voorbeeld:

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

Voice als uitbreiding van een bestaande Discord-kanaalsessie:

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

In de modus agent-proxy joint de bot het geconfigureerde spraakkanaal, maar OpenClaw-agentbeurten gebruiken de normale gerouteerde sessie en agent van het doelkanaal. De realtime-voicesessie spreekt het teruggegeven resultaat terug in het spraakkanaal. De supervisor-agent kan nog steeds normale berichttools gebruiken volgens zijn toolbeleid, inclusief het verzenden van een apart Discord-bericht als dat de juiste actie is.

Nuttige doelvormen:

• target: "channel:123456789012345678" routeert via een Discord-tekstkanaalsessie.
• target: "123456789012345678" wordt behandeld als kanaaldoel.
• target: "dm:123456789012345678" of target: "user:123456789012345678" routeert via die direct-message-sessie.

OpenAI Realtime-voorbeeld met veel echo:

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

Gebruik dit wanneer het model zijn eigen Discord-weergave via een open microfoon hoort, maar je het nog steeds wilt onderbreken door te spreken. OpenClaw voorkomt dat OpenAI automatisch onderbreekt op ruwe invoeraudio, terwijl bargeIn: true ervoor zorgt dat Discord-gebeurtenissen voor het starten van een spreker en al actieve sprekeraudio actieve realtime-antwoorden kunnen annuleren voordat de volgende vastgelegde beurt OpenAI bereikt. Zeer vroege barge-in-signalen met audioEndMs onder minBargeInAudioEndMs worden behandeld als vermoedelijke echo/ruis en genegeerd, zodat het model niet stopt bij het eerste afspeelframe.

Verwachte spraaklogs:

• Bij deelnemen: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• Bij realtime-start: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• Bij sprekeraudio: discord voice: realtime speaker turn opened ..., discord voice: realtime input audio started ... outputAudioMs=... outputActive=..., en discord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=...
• Bij overgeslagen verouderde spraak: discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... of reason=non-actionable-closing ...
• Bij voltooiing van realtime-antwoord: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• Bij stoppen/resetten van weergave: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• Bij realtime-consult: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• Bij agentantwoord: discord voice: agent turn answer ...
• Bij exacte spraak in de wachtrij: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=..., gevolgd door discord voice: realtime exact speech dequeued reason=player-idle ...
• Bij barge-in-detectie: discord voice: realtime barge-in detected source=speaker-start ... of discord voice: realtime barge-in detected source=active-speaker-audio ..., gevolgd door discord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=...
• Bij realtime-onderbreking: discord voice: realtime model interrupt requested client:response.cancel reason=barge-in, gevolgd door discord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=... of discord voice: realtime model interrupt confirmed server:response.done status=cancelled ...
• Bij genegeerde echo/ruis: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• Bij uitgeschakelde barge-in: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• Bij inactieve weergave: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

Lees de realtime-spraaklogs als tijdlijn om afgekapt geluid te debuggen:

1. realtime audio playback started betekent dat Discord is begonnen met het afspelen van assistentaudio. De brug begint vanaf dit punt assistent-uitvoerchunks, Discord PCM-bytes, realtime-bytes van de provider en gesynthetiseerde audioduur te tellen.
2. realtime speaker turn opened markeert dat een Discord-spreker actief wordt. Als weergave al actief is en bargeIn is ingeschakeld, kan dit worden gevolgd door barge-in detected source=speaker-start.
3. realtime input audio started markeert het eerste daadwerkelijke audioframe dat voor die sprekerbeurt is ontvangen. outputActive=true of een niet-nul outputAudioMs betekent hier dat de microfoon invoer verzendt terwijl assistentweergave nog actief is.
4. barge-in detected source=active-speaker-audio betekent dat OpenClaw live sprekeraudio zag terwijl assistentweergave actief was. Dit is nuttig om een echte onderbreking te onderscheiden van een Discord-gebeurtenis voor het starten van een spreker zonder bruikbare audio.
5. barge-in requested reason=... betekent dat OpenClaw de realtime-provider heeft gevraagd het actieve antwoord te annuleren of af te kappen. Het bevat outputAudioMs, outputActive en playbackChunks, zodat je kunt zien hoeveel assistentaudio daadwerkelijk was afgespeeld vóór de onderbreking.
6. realtime audio playback stopped reason=... is het lokale resetpunt voor Discord-weergave. De reden geeft aan wie de weergave heeft gestopt: barge-in, player-idle, provider-clear-audio, forced-agent-consult, stream-close of session-close.
7. realtime speaker turn closed vat de vastgelegde invoerbeurt samen. chunks=0 of hasAudio=false betekent dat de sprekerbeurt werd geopend, maar dat geen bruikbare audio de realtime-brug bereikte. interruptedPlayback=true betekent dat die invoerbeurt overlapte met assistentuitvoer en barge-in-logica activeerde.

Nuttige velden:

• outputAudioMs: duur van assistentaudio die vóór de logregel door de realtime-provider is gegenereerd.
• audioMs: duur van assistentaudio die OpenClaw telde voordat de weergave stopte.
• elapsedMs: wandkloktijd tussen het openen en sluiten van de weergavestream of sprekerbeurt.
• discordBytes: 48 kHz stereo PCM-bytes verzonden naar of ontvangen van Discord-spraak.
• realtimeBytes: PCM-bytes in providerformaat verzonden naar of ontvangen van de realtime-provider.
• playbackChunks: assistentaudiochunks doorgestuurd naar Discord voor het actieve antwoord.
• sinceLastAudioMs: onderbreking tussen het laatst vastgelegde sprekeraudioframe en het sluiten van de sprekerbeurt.

Veelvoorkomende patronen:

• Direct afkappen met source=active-speaker-audio, kleine outputAudioMs en dezelfde gebruiker in de buurt wijst meestal op luidsprekerecho die de microfoon binnenkomt. Verhoog voice.realtime.minBargeInAudioEndMs, verlaag het luidsprekervolume, gebruik een koptelefoon of stel voice.realtime.providers.openai.interruptResponseOnInputAudio: false in.
• source=speaker-start gevolgd door speaker turn closed ... hasAudio=false betekent dat Discord een sprekerstart meldde, maar dat geen audio OpenClaw bereikte. Dat kan een tijdelijke Discord-spraakgebeurtenis zijn, gedrag van een noise gate of een client die kort de microfoon activeert.
• audio playback stopped reason=stream-close zonder nabije barge-in of provider-clear-audio betekent dat de lokale Discord-weergavestream onverwacht is beëindigd. Controleer de voorafgaande provider- en Discord-spelerlogs.
• capture ignored during playback (barge-in disabled) betekent dat OpenClaw invoer bewust heeft laten vallen terwijl assistentaudio actief was. Schakel voice.realtime.bargeIn in als je wilt dat spraak de weergave onderbreekt.
• barge-in ignored ... outputActive=false betekent dat Discord of provider-VAD spraak meldde, maar dat OpenClaw geen actieve weergave had om te onderbreken. Dit zou audio niet moeten afkappen.

Referenties worden per component opgelost: LLM-route-authenticatie voor voice.model, STT-authenticatie voor tools.media.audio, TTS-authenticatie voor messages.tts/voice.tts en realtime-provider-authenticatie voor voice.realtime.providers of de normale authenticatieconfiguratie van de provider.

Spraakberichten

Discord-spraakberichten tonen een golfvormvoorbeeld en vereisen OGG/Opus-audio. OpenClaw genereert de golfvorm automatisch, maar heeft ffmpeg en ffprobe op de Gateway-host nodig om te inspecteren en te converteren.

• Geef een lokaal bestandspad op (URL's worden geweigerd).
• Laat tekstinhoud weg (Discord weigert tekst + spraakbericht in dezelfde payload).
• Elk audioformaat wordt geaccepteerd; OpenClaw converteert waar nodig naar OGG/Opus.

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

Probleemoplossing

openclaw doctoropenclaw channels status --probeopenclaw logs --follow

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

{channels: {discord: {  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 "@Mantis" and send a real Discord mention.        Mantis: "MANTIS_DISCORD_USER_ID",      },    },  },},},}

Configuratiereferentie

Primaire referentie: Configuratiereferentie - Discord.

Veiligheid en beheer

• Behandel bottokens als geheimen (DISCORD_BOT_TOKEN heeft de voorkeur in beheerde omgevingen).
• Verleen Discord-machtigingen met minimale rechten.
• Als opdrachtimplementatie/-status verouderd is, herstart dan de Gateway en controleer opnieuw met openclaw channels status --probe.

Gerelateerd