Discord

Bereit für DMs und Guild-Kanäle über den offiziellen Discord-Gateway.

Schnelleinrichtung

Sie müssen eine neue Anwendung mit einem Bot erstellen, den Bot zu Ihrem Server hinzufügen und ihn mit OpenClaw koppeln. Wir empfehlen, Ihren Bot zu Ihrem eigenen privaten Server hinzuzufügen. Wenn Sie noch keinen haben, erstellen Sie zuerst einen (wählen Sie 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>

Empfohlen: Guild-Workspace einrichten

Sobald DMs funktionieren, können Sie Ihren Discord-Server als vollständigen Workspace einrichten, in dem jeder Kanal seine eigene Agentensitzung mit eigenem Kontext erhält. Dies wird für private Server empfohlen, auf denen nur Sie und Ihr Bot sind.

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

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

Erstellen Sie nun einige Kanäle auf Ihrem Discord-Server und beginnen Sie zu chatten. Ihr Agent kann den Kanalnamen sehen, und jeder Kanal erhält seine eigene isolierte Sitzung — Sie können also #coding, #home, #research oder etwas anderes einrichten, das zu Ihrem Workflow passt.

Runtime-Modell

• Gateway besitzt die Discord-Verbindung.
• Das Reply-Routing ist deterministisch: Eingehende Discord-Antworten gehen zurück an Discord.
• Discord-Guild-/Channel-Metadaten werden dem Modell-Prompt als nicht vertrauenswürdiger Kontext hinzugefügt, nicht als für Benutzer sichtbares Antwortpräfix. Wenn ein Modell diesen Umschlag zurückkopiert, entfernt OpenClaw die kopierten Metadaten aus ausgehenden Antworten und aus künftigem Replay-Kontext.
• Standardmäßig (session.dmScope=main) teilen direkte Chats die Hauptsitzung des Agents (agent:main:main).
• Guild-Channels sind isolierte Sitzungsschlüssel (agent:<agentId>:discord:channel:<channelId>).
• Gruppen-DMs werden standardmäßig ignoriert (channels.discord.dm.groupEnabled=false).
• Native Slash-Commands laufen in isolierten Command-Sitzungen (agent:<agentId>:discord:slash:<userId>), führen aber weiterhin CommandTargetSessionKey zur gerouteten Konversationssitzung mit.
• Text-only-Cron-/Heartbeat-Ankündigungen an Discord verwenden die finale für den Assistenten sichtbare Antwort einmal. Medien- und strukturierte Komponenten-Payloads bleiben mehrteilig, wenn der Agent mehrere zustellbare Payloads ausgibt.

Forum-Channels

Discord-Forum- und Media-Channels akzeptieren nur Thread-Beiträge. OpenClaw unterstützt zwei Möglichkeiten, sie zu erstellen:

• Senden Sie eine Nachricht an das Forum-Parent (channel:<forumId>), um automatisch einen Thread zu erstellen. Der Thread-Titel verwendet die erste nicht leere Zeile Ihrer Nachricht.
• Verwenden Sie openclaw message thread create, um einen Thread direkt zu erstellen. Übergeben Sie für Forum-Channels nicht --message-id.

Beispiel: an das Forum-Parent senden, um einen Thread zu erstellen

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

Beispiel: einen Forum-Thread explizit erstellen

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

Forum-Parents akzeptieren keine Discord-Komponenten. Wenn Sie Komponenten benötigen, senden Sie sie an den Thread selbst (channel:<threadId>).

Interaktive Komponenten

OpenClaw unterstützt Discord-Komponenten-v2-Container für Agent-Nachrichten. Verwenden Sie das Nachrichten-Tool mit einem components-Payload. Interaktionsergebnisse werden als normale eingehende Nachrichten an den Agent zurückgeroutet und folgen den bestehenden Discord-replyToMode-Einstellungen.

Unterstützte Blöcke:

• text, section, separator, actions, media-gallery, file
• Action Rows erlauben bis zu 5 Buttons oder ein einzelnes Auswahlmenü
• Auswahltypen: string, user, role, mentionable, channel

Standardmäßig können Komponenten nur einmal verwendet werden. Setzen Sie components.reusable=true, damit Buttons, Auswahlelemente und Formulare bis zu ihrem Ablauf mehrfach verwendet werden können.

Um einzuschränken, wer einen Button anklicken darf, setzen Sie allowedUsers für diesen Button (Discord-Benutzer-IDs, Tags oder *). Wenn konfiguriert, erhalten nicht übereinstimmende Benutzer eine ephemere Ablehnung.

Die Slash-Commands /model und /models öffnen eine interaktive Modellauswahl mit Dropdowns für Provider, Modell und kompatible Runtime sowie einem Absenden-Schritt. /models add ist veraltet und gibt jetzt eine Veraltungsmeldung zurück, statt Modelle aus dem Chat zu registrieren. Die Picker-Antwort ist ephemer und kann nur vom aufrufenden Benutzer verwendet werden. Discord-Auswahlmenüs sind auf 25 Optionen begrenzt. Fügen Sie daher provider/*-Einträge zu agents.defaults.models hinzu, wenn der Picker dynamisch erkannte Modelle nur für ausgewählte Provider wie openai-codex oder vllm anzeigen soll.

Dateianhänge:

• file-Blöcke müssen auf eine Anhangsreferenz verweisen (attachment://<filename>)
• Stellen Sie den Anhang über media/path/filePath bereit (einzelne Datei); verwenden Sie media-gallery für mehrere Dateien
• Verwenden Sie filename, um den Upload-Namen zu überschreiben, wenn er der Anhangsreferenz entsprechen soll

Modale Formulare:

• Fügen Sie components.modal mit bis zu 5 Feldern hinzu
• Feldtypen: text, checkbox, radio, select, role-select, user-select
• OpenClaw fügt automatisch einen Auslöse-Button hinzu

Beispiel:

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

Zugriffskontrolle und Routing

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

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

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

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

Rollenbasiertes Agent-Routing

Verwenden Sie bindings[].match.roles, um Discord-Guild-Mitglieder anhand der Rollen-ID zu verschiedenen Agents zu routen. Rollenbasierte Bindings akzeptieren nur Rollen-IDs und werden nach Peer- oder Parent-Peer-Bindings und vor reinen Guild-Bindings ausgewertet. Wenn ein Binding auch andere Match-Felder setzt (zum Beispiel peer + guildId + roles), müssen alle konfigurierten Felder übereinstimmen.

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

Native Commands und Command-Auth

• commands.native ist standardmäßig "auto" und für Discord aktiviert.
• Kanalspezifische Überschreibung: channels.discord.commands.native.
• commands.native=false überspringt beim Start die Registrierung und Bereinigung von Discord-Slash-Commands. Zuvor registrierte Commands können in Discord sichtbar bleiben, bis Sie sie aus der Discord-App entfernen.
• Die Authentifizierung nativer Commands verwendet dieselben Discord-Allowlists/-Richtlinien wie die normale Nachrichtenverarbeitung.
• Commands können in der Discord-Oberfläche weiterhin für Benutzer sichtbar sein, die nicht autorisiert sind; die Ausführung erzwingt dennoch die OpenClaw-Authentifizierung und gibt "not authorized" zurück.

Siehe Slash-Commands für Command-Katalog und Verhalten.

Standardeinstellungen für Slash-Commands:

• ephemeral: true

Funktionsdetails

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

Tools und Aktions-Gates

Discord-Nachrichtenaktionen umfassen Messaging, Kanaladministration, Moderation, Präsenz und Metadatenaktionen.

Kernbeispiele:

• Messaging: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• Reaktionen: react, reactions, emojiList
• Moderation: timeout, kick, ban
• Präsenz: setPresence

Die Aktion event-create akzeptiert einen optionalen Parameter image (URL oder lokaler Dateipfad), um das Titelbild des geplanten Events festzulegen.

Aktions-Gates befinden sich unter channels.discord.actions.*.

Standardverhalten der Gates:

Components-v2-UI

OpenClaw verwendet Discord Components v2 für Exec-Genehmigungen und kontextübergreifende Marker. Discord-Nachrichtenaktionen können außerdem components für benutzerdefinierte UI akzeptieren (fortgeschritten; erfordert das Erstellen einer Component-Payload über das Discord-Tool), während veraltete embeds weiterhin verfügbar sind, aber nicht empfohlen werden.

• channels.discord.ui.components.accentColor legt die Akzentfarbe fest, die von Discord-Component-Containern verwendet wird (Hex).
• Pro Konto mit channels.discord.accounts.<id>.ui.components.accentColor festlegen.
• embeds werden ignoriert, wenn Components v2 vorhanden sind.

Beispiel:

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

Sprache

Discord hat zwei unterschiedliche Sprachoberflächen: Echtzeit-Sprachkanäle (kontinuierliche Unterhaltungen) und Sprachnachrichten-Anhänge (das Waveform-Vorschauformat). Der Gateway unterstützt beide.

Sprachkanäle

Einrichtungs-Checkliste:

1. Aktivieren Sie Message Content Intent im Discord Developer Portal.
2. Aktivieren Sie Server Members Intent, wenn Rollen-/Benutzer-Allowlists verwendet werden.
3. Laden Sie den Bot mit den Scopes bot und applications.commands ein.
4. Gewähren Sie Connect, Speak, Send Messages und Read Message History im Ziel-Sprachkanal.
5. Aktivieren Sie native Befehle (commands.native oder channels.discord.commands.native).
6. Konfigurieren Sie channels.discord.voice.

Verwenden Sie /vc join|leave|status, um Sitzungen zu steuern. Der Befehl verwendet den Standard-Agent des Kontos und folgt denselben Allowlist- und Gruppenrichtlinienregeln wie andere Discord-Befehle.

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

Um die effektiven Berechtigungen des Bots vor dem Beitritt zu prüfen, führen Sie aus:

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

Beispiel für automatischen Beitritt:

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

Hinweise:

• voice.tts überschreibt messages.tts nur für die Sprachwiedergabe mit stt-tts. Echtzeitmodi verwenden voice.realtime.voice.
• voice.mode steuert den Gesprächspfad. Standard ist agent-proxy: Ein Echtzeit-Voice-Frontend übernimmt Turn-Timing, Unterbrechung und Wiedergabe, delegiert inhaltliche Arbeit über openclaw_agent_consult an den gerouteten OpenClaw-Agent und behandelt das Ergebnis wie einen getippten Discord-Prompt von dieser sprechenden Person. stt-tts behält den älteren Batch-STT-plus-TTS-Ablauf bei. bidi lässt das Echtzeitmodell direkt sprechen und stellt zugleich openclaw_agent_consult für das OpenClaw-Brain bereit.
• voice.agentSession steuert, welche OpenClaw-Konversation Voice-Turns erhält. Lassen Sie es ungesetzt für die eigene Sitzung des Voice-Kanals, oder setzen Sie { mode: "target", target: "channel:<text-channel-id>" }, damit der Voice-Kanal als Mikrofon-/Lautsprecher-Erweiterung einer bestehenden Discord-Textkanal-Sitzung wie #maintainers fungiert.
• voice.model überschreibt das OpenClaw-Agent-Brain für Discord-Voice-Antworten und Echtzeit-Consults. Lassen Sie es ungesetzt, um das Modell des gerouteten Agents zu erben. Es ist von voice.realtime.model getrennt.
• agent-proxy routet Sprache über discord-voice; dadurch bleibt die normale Owner-/Tool-Autorisierung für die sprechende Person und die Zielsitzung erhalten, aber das Agent-Tool tts wird ausgeblendet, weil Discord Voice die Wiedergabe besitzt. Standardmäßig gibt agent-proxy dem Consult für Owner-Sprechende vollständigen Owner-äquivalenten Tool-Zugriff (voice.realtime.toolPolicy: "owner") und bevorzugt deutlich, vor inhaltlichen Antworten den OpenClaw-Agent zu konsultieren (voice.realtime.consultPolicy: "always"). In diesem Standardmodus always spricht die Echtzeitschicht vor der Consult-Antwort nicht automatisch Fülltext; sie erfasst und transkribiert Sprache und spricht dann die geroutete OpenClaw-Antwort. Wenn mehrere erzwungene Consult-Antworten fertig werden, während Discord noch die erste Antwort abspielt, werden spätere Antworten mit exakter Sprachausgabe in die Warteschlange gestellt, bis die Wiedergabe im Leerlauf ist, statt Sprache mitten im Satz zu ersetzen.
• Im Modus stt-tts verwendet STT tools.media.audio; voice.model beeinflusst die Transkription nicht.
• In Echtzeitmodi konfigurieren voice.realtime.provider, voice.realtime.model und voice.realtime.voice die Echtzeit-Audiositzung. Für OpenAI Realtime 2 plus Codex-Brain verwenden Sie voice.realtime.model: "gpt-realtime-2" und voice.model: "openai-codex/gpt-5.5".
• Der OpenAI-Echtzeit-Provider akzeptiert aktuelle Realtime-2-Ereignisnamen und ältere Codex-kompatible Aliasse für Output-Audio- und Transcript-Ereignisse, sodass kompatible Provider-Snapshots abweichen können, ohne Assistant-Audio zu verlieren.
• voice.realtime.bargeIn steuert, ob Discord-Speaker-Start-Ereignisse aktive Echtzeitwiedergabe unterbrechen. Wenn es ungesetzt ist, folgt es der Input-Audio-Unterbrechungseinstellung des Echtzeit-Providers.
• voice.realtime.minBargeInAudioEndMs steuert die minimale Assistant-Wiedergabedauer, bevor ein OpenAI-Echtzeit-Barge-in Audio abschneidet. Standard: 250. Setzen Sie 0 für sofortige Unterbrechung in Räumen mit wenig Echo, oder erhöhen Sie den Wert für Lautsprecher-Setups mit starkem Echo.
• Für eine OpenAI-Stimme bei Discord-Wiedergabe setzen Sie voice.tts.provider: "openai" und wählen Sie eine Text-to-Speech-Stimme unter voice.tts.openai.voice oder voice.tts.providers.openai.voice. cedar ist beim aktuellen OpenAI-TTS-Modell eine gute maskulin klingende Wahl.
• Discord-systemPrompt-Überschreibungen pro Kanal gelten für Voice-Transcript-Turns dieses Voice-Kanals.
• Voice-Transcript-Turns leiten den Owner-Status aus Discord allowFrom (oder dm.allowFrom) ab; Nicht-Owner-Sprechende können nicht auf Owner-only-Tools zugreifen (zum Beispiel gateway und cron).
• Discord Voice ist für reine Textkonfigurationen opt-in; setzen Sie channels.discord.voice.enabled=true (oder behalten Sie einen bestehenden channels.discord.voice-Block bei), um /vc-Befehle, die Voice-Runtime und den Gateway-Intent GuildVoiceStates zu aktivieren.
• channels.discord.intents.voiceStates kann das Abonnement des Voice-State-Intents explizit überschreiben. Lassen Sie es ungesetzt, damit der Intent der effektiven Voice-Aktivierung folgt.
• Wenn voice.autoJoin mehrere Einträge für dieselbe Guild enthält, tritt OpenClaw dem zuletzt konfigurierten Kanal für diese Guild bei.
• voice.allowedChannels ist eine optionale Residency-Allowlist. Lassen Sie es ungesetzt, um /vc join in jeden autorisierten Discord-Voice-Kanal zu erlauben. Wenn gesetzt, sind /vc join, Auto-Join beim Start und Bot-Voice-State-Verschiebungen auf die aufgeführten Einträge { guildId, channelId } beschränkt. Setzen Sie es auf ein leeres Array, um alle Discord-Voice-Beitritte zu verweigern. Wenn Discord den Bot außerhalb der Allowlist verschiebt, verlässt OpenClaw diesen Kanal und tritt wieder dem konfigurierten Auto-Join-Ziel bei, sobald eines verfügbar ist.
• voice.daveEncryption und voice.decryptionFailureTolerance werden an die Join-Optionen von @discordjs/voice durchgereicht.
• Die Standardwerte von @discordjs/voice sind daveEncryption=true und decryptionFailureTolerance=24, wenn sie ungesetzt sind.
• OpenClaw verwendet standardmäßig den reinen JS-Decoder opusscript für Discord-Voice-Empfang. Das optionale native Paket @discordjs/opus wird von der pnpm-Installationsrichtlinie des Repos ignoriert, sodass normale Installationen, Docker-Lanes und nicht verwandte Tests kein natives Addon kompilieren. Dedizierte Hosts für Voice-Performance können nach der Installation des nativen Addons mit OPENCLAW_DISCORD_OPUS_DECODER=native opt-in aktivieren.
• voice.connectTimeoutMs steuert das anfängliche Warten auf @discordjs/voice Ready für /vc join und Auto-Join-Versuche. Standard: 30000.
• voice.reconnectGraceMs steuert, wie lange OpenClaw wartet, bis eine getrennte Voice-Sitzung mit der erneuten Verbindung beginnt, bevor sie zerstört wird. Standard: 15000.
• Im Modus stt-tts stoppt die Voice-Wiedergabe nicht nur deshalb, weil eine andere Person zu sprechen beginnt. Um Feedback-Schleifen zu vermeiden, ignoriert OpenClaw neue Voice-Erfassung, während TTS abgespielt wird; sprechen Sie nach Ende der Wiedergabe für den nächsten Turn. Echtzeitmodi leiten Speaker-Starts als Barge-in-Signale an den Echtzeit-Provider weiter.
• In Echtzeitmodi kann Echo von Lautsprechern in ein offenes Mikrofon wie Barge-in wirken und die Wiedergabe unterbrechen. Für Discord-Räume mit starkem Echo setzen Sie voice.realtime.providers.openai.interruptResponseOnInputAudio: false, damit OpenAI bei Input-Audio nicht automatisch unterbricht. Fügen Sie voice.realtime.bargeIn: true hinzu, wenn Discord-Speaker-Start-Ereignisse aktive Wiedergabe weiterhin unterbrechen sollen. Die OpenAI-Echtzeit-Bridge ignoriert Wiedergabeabschneidungen, die kürzer als voice.realtime.minBargeInAudioEndMs sind, als wahrscheinliches Echo/Rauschen und protokolliert sie als übersprungen, statt die Discord-Wiedergabe zu löschen.
• voice.captureSilenceGraceMs steuert, wie lange OpenClaw wartet, nachdem Discord gemeldet hat, dass eine sprechende Person aufgehört hat, bevor dieses Audiosegment für STT finalisiert wird. Standard: 2500; erhöhen Sie diesen Wert, wenn Discord normale Pausen in abgehackte Teil-Transcripts aufteilt.
• Wenn ElevenLabs der ausgewählte TTS-Provider ist, verwendet Discord-Voice-Wiedergabe Streaming-TTS und startet aus dem Antwortstream des Providers. Provider ohne Streaming-Unterstützung fallen auf den Pfad mit synthetisierter temporärer Datei zurück.
• OpenClaw überwacht außerdem Receive-Decrypt-Fehler und stellt sich automatisch wieder her, indem es nach wiederholten Fehlern in einem kurzen Zeitfenster den Voice-Kanal verlässt und erneut beitritt.
• Wenn Receive-Logs nach einem Update wiederholt DecryptionFailed(UnencryptedWhenPassthroughDisabled) zeigen, sammeln Sie einen Dependency-Bericht und Logs. Die gebündelte @discordjs/voice-Linie enthält den Upstream-Padding-Fix aus discord.js PR #11449, der discord.js Issue #11419 geschlossen hat.
• Receive-Ereignisse The operation was aborted sind zu erwarten, wenn OpenClaw ein erfasstes Sprechersegment finalisiert; sie sind ausführliche Diagnosen, keine Warnungen.
• Ausführliche Discord-Voice-Logs enthalten eine begrenzte einzeilige STT-Transcript-Vorschau für jedes akzeptierte Sprechersegment, sodass Debugging sowohl die Benutzerseite als auch die Agent-Antwortseite zeigt, ohne unbegrenzt Transcript-Text auszugeben.
• Im Modus agent-proxy überspringt der erzwungene Consult-Fallback wahrscheinlich unvollständige Transcript-Fragmente, etwa Text, der auf ... endet, oder einen nachgestellten Konnektor wie and, sowie offensichtlich nicht umsetzbare Abschlüsse wie „bin gleich zurück“ oder „tschüss“. Logs zeigen forced agent consult skipped reason=..., wenn dies eine veraltete Antwort in der Warteschlange verhindert.

Native Opus-Einrichtung für Source-Checkouts:

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

Verwenden Sie Node 22 für den Gateway, wenn Sie das native Upstream-macOS-arm64-Addon als Prebuild nutzen möchten. Wenn Sie eine andere Node-Runtime verwenden, benötigt der Opt-in-Installer möglicherweise eine lokale node-gyp-Toolchain für den Source-Build.

Nach der Installation des nativen Addons starten Sie den Gateway mit:

OPENCLAW_DISCORD_OPUS_DECODER=native pnpm gateway:watch

Ausführliche Voice-Logs sollten discord voice: opus decoder: @discordjs/opus anzeigen. Ohne das Env-Opt-in, oder wenn das native Addon fehlt oder auf dem Host nicht geladen werden kann, protokolliert OpenClaw discord voice: opus decoder: opusscript und empfängt Voice weiterhin über den reinen JS-Fallback.

STT-plus-TTS-Pipeline:

• Discord-PCM-Erfassung wird in eine temporäre WAV-Datei konvertiert.
• tools.media.audio übernimmt STT, zum Beispiel openai/gpt-4o-mini-transcribe.
• Das Transcript wird über Discord-Ingress und Routing gesendet, während das Antwort-LLM mit einer Voice-Output-Richtlinie läuft, die das Agent-Tool tts ausblendet und zurückgegebenen Text anfordert, weil Discord Voice die finale TTS-Wiedergabe besitzt.
• voice.model überschreibt, wenn gesetzt, nur das Antwort-LLM für diesen Voice-Kanal-Turn.
• voice.tts wird über messages.tts gemergt; streamingfähige Provider speisen den Player direkt, andernfalls wird die resultierende Audiodatei im beigetretenen Kanal abgespielt.

Beispiel für eine standardmäßige agent-proxy-Voice-Kanal-Sitzung:

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

Ohne voice.agentSession-Block erhält jeder Voice-Kanal seine eigene geroutete OpenClaw-Sitzung. Zum Beispiel spricht /vc join channel:234567890123456789 mit der Sitzung für diesen Discord-Voice-Kanal. Das Echtzeitmodell ist nur das Voice-Frontend; inhaltliche Anfragen werden an den konfigurierten OpenClaw-Agent übergeben. Wenn das Echtzeitmodell ein finales Transcript erzeugt, ohne das Consult-Tool aufzurufen, erzwingt OpenClaw den Consult als Fallback, damit der Standard weiterhin so funktioniert, als würden Sie mit dem Agent sprechen.

Beispiel für Legacy-STT-plus-TTS:

{  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-Beispiel:

{  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 Erweiterung einer bestehenden Discord-Kanalsitzung:

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

Im Modus agent-proxy tritt der Bot dem konfigurierten Voice-Kanal bei, aber OpenClaw-Agent-Turns verwenden die normale geroutete Sitzung und den Agent des Zielkanals. Die Echtzeit-Voice-Sitzung spricht das zurückgegebene Ergebnis zurück in den Voice-Kanal. Der Supervisor-Agent kann entsprechend seiner Tool-Richtlinie weiterhin normale Message-Tools verwenden, einschließlich des Sendens einer separaten Discord-Nachricht, wenn das die richtige Aktion ist.

Nützliche Zielformen:

• target: "channel:123456789012345678" routet über eine Discord-Textkanal-Sitzung.
• target: "123456789012345678" wird als Kanalziel behandelt.
• target: "dm:123456789012345678" oder target: "user:123456789012345678" routet über diese Direct-Message-Sitzung.

OpenAI-Realtime-Beispiel für starkes 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,            },          },        },      },    },  },}

Verwenden Sie dies, wenn das Modell seine eigene Discord-Wiedergabe über ein offenes Mikrofon hört, Sie es aber weiterhin durch Sprechen unterbrechen möchten. OpenClaw verhindert, dass OpenAI bei rohem Eingabeaudio automatisch unterbricht, während bargeIn: true Discord-Sprecherstart-Ereignisse und bereits aktive Sprecher-Audiosignale aktive Realtime-Antworten abbrechen lässt, bevor der nächste erfasste Turn OpenAI erreicht. Sehr frühe Barge-in-Signale mit audioEndMs unterhalb von minBargeInAudioEndMs werden als wahrscheinliches Echo/Rauschen behandelt und ignoriert, damit das Modell nicht bereits beim ersten Wiedergabe-Frame abbricht.

Erwartete Voice-Logs:

• Beim Beitreten: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• Beim Realtime-Start: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• Bei Sprecher-Audio: discord voice: realtime speaker turn opened ..., discord voice: realtime input audio started ... outputAudioMs=... outputActive=... und discord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=...
• Bei übersprungener veralteter Sprache: discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... oder reason=non-actionable-closing ...
• Beim Abschluss der Realtime-Antwort: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• Bei Wiedergabestopp/-zurücksetzung: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• Bei Realtime-Consult: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• Bei Agent-Antwort: discord voice: agent turn answer ...
• Bei eingereihter exakter Sprache: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=..., gefolgt von discord voice: realtime exact speech dequeued reason=player-idle ...
• Bei Barge-in-Erkennung: discord voice: realtime barge-in detected source=speaker-start ... oder discord voice: realtime barge-in detected source=active-speaker-audio ..., gefolgt von discord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=...
• Bei Realtime-Unterbrechung: discord voice: realtime model interrupt requested client:response.cancel reason=barge-in, gefolgt entweder von discord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=... oder discord voice: realtime model interrupt confirmed server:response.done status=cancelled ...
• Bei ignoriertem Echo/Rauschen: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• Bei deaktiviertem Barge-in: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• Bei inaktiver Wiedergabe: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

Um abgeschnittenes Audio zu debuggen, lesen Sie die Realtime-Voice-Logs als Zeitachse:

1. realtime audio playback started bedeutet, dass Discord mit der Wiedergabe von Assistant-Audio begonnen hat. Die Bridge zählt ab diesem Punkt Assistant-Ausgabe-Chunks, Discord-PCM-Bytes, Provider-Realtime-Bytes und die synthetisierte Audiodauer.
2. realtime speaker turn opened markiert, dass ein Discord-Sprecher aktiv wird. Wenn die Wiedergabe bereits aktiv ist und bargeIn aktiviert ist, kann darauf barge-in detected source=speaker-start folgen.
3. realtime input audio started markiert den ersten tatsächlich empfangenen Audio-Frame für diesen Sprecher-Turn. outputActive=true oder ein von null verschiedener outputAudioMs hier bedeutet, dass das Mikrofon Eingaben sendet, während die Assistant-Wiedergabe noch aktiv ist.
4. barge-in detected source=active-speaker-audio bedeutet, dass OpenClaw Live-Sprecher-Audio gesehen hat, während die Assistant-Wiedergabe aktiv war. Dies ist nützlich, um eine echte Unterbrechung von einem Discord-Sprecherstart-Ereignis ohne verwertbares Audio zu unterscheiden.
5. barge-in requested reason=... bedeutet, dass OpenClaw den Realtime-Provider aufgefordert hat, die aktive Antwort abzubrechen oder zu kürzen. Es enthält outputAudioMs, outputActive und playbackChunks, damit Sie sehen können, wie viel Assistant-Audio vor der Unterbrechung tatsächlich abgespielt wurde.
6. realtime audio playback stopped reason=... ist der lokale Zurücksetzungspunkt der Discord-Wiedergabe. Der Grund gibt an, wer die Wiedergabe gestoppt hat: barge-in, player-idle, provider-clear-audio, forced-agent-consult, stream-close oder session-close.
7. realtime speaker turn closed fasst den erfassten Eingabe-Turn zusammen. chunks=0 oder hasAudio=false bedeutet, dass der Sprecher-Turn geöffnet wurde, aber kein nutzbares Audio die Realtime-Bridge erreicht hat. interruptedPlayback=true bedeutet, dass sich dieser Eingabe-Turn mit der Assistant-Ausgabe überschnitten und Barge-in-Logik ausgelöst hat.

Nützliche Felder:

• outputAudioMs: vom Realtime-Provider vor der Log-Zeile erzeugte Assistant-Audiodauer.
• audioMs: Assistant-Audiodauer, die OpenClaw gezählt hat, bevor die Wiedergabe gestoppt wurde.
• elapsedMs: Echtzeit zwischen Öffnen und Schließen des Wiedergabe-Streams oder Sprecher-Turns.
• discordBytes: 48-kHz-Stereo-PCM-Bytes, die an Discord Voice gesendet oder von dort empfangen wurden.
• realtimeBytes: PCM-Bytes im Provider-Format, die an den Realtime-Provider gesendet oder von dort empfangen wurden.
• playbackChunks: Assistant-Audio-Chunks, die für die aktive Antwort an Discord weitergeleitet wurden.
• sinceLastAudioMs: Abstand zwischen dem letzten erfassten Sprecher-Audio-Frame und dem Schließen des Sprecher-Turns.

Häufige Muster:

• Sofortiges Abschneiden mit source=active-speaker-audio, kleinem outputAudioMs und demselben Nutzer in der Nähe weist meist darauf hin, dass Lautsprecherecho in das Mikrofon gelangt. Erhöhen Sie voice.realtime.minBargeInAudioEndMs, senken Sie die Lautsprecherlautstärke, verwenden Sie Kopfhörer oder setzen Sie voice.realtime.providers.openai.interruptResponseOnInputAudio: false.
• source=speaker-start gefolgt von speaker turn closed ... hasAudio=false bedeutet, dass Discord einen Sprecherstart gemeldet hat, aber kein Audio OpenClaw erreicht hat. Das kann ein vorübergehendes Discord-Voice-Ereignis, Noise-Gate-Verhalten oder ein Client sein, der das Mikrofon kurz aktiviert.
• audio playback stopped reason=stream-close ohne nahegelegenes Barge-in oder provider-clear-audio bedeutet, dass der lokale Discord-Wiedergabe-Stream unerwartet beendet wurde. Prüfen Sie die vorherigen Provider- und Discord-Player-Logs.
• capture ignored during playback (barge-in disabled) bedeutet, dass OpenClaw Eingaben absichtlich verworfen hat, während Assistant-Audio aktiv war. Aktivieren Sie voice.realtime.bargeIn, wenn Sprache die Wiedergabe unterbrechen soll.
• barge-in ignored ... outputActive=false bedeutet, dass Discord oder Provider-VAD Sprache gemeldet hat, OpenClaw aber keine aktive Wiedergabe zum Unterbrechen hatte. Dies sollte Audio nicht abschneiden.

Anmeldedaten werden pro Komponente aufgelöst: LLM-Routen-Authentifizierung für voice.model, STT-Authentifizierung für tools.media.audio, TTS-Authentifizierung für messages.tts/voice.tts und Realtime-Provider-Authentifizierung für voice.realtime.providers oder die normale Authentifizierungskonfiguration des Providers.

Sprachnachrichten

Discord-Sprachnachrichten zeigen eine Wellenformvorschau und erfordern OGG/Opus-Audio. OpenClaw generiert die Wellenform automatisch, benötigt aber ffmpeg und ffprobe auf dem Gateway-Host, um zu prüfen und zu konvertieren.

• Geben Sie einen lokalen Dateipfad an (URLs werden abgelehnt).
• Lassen Sie Textinhalt weg (Discord lehnt Text + Sprachnachricht in derselben Nutzlast ab).
• Jedes Audioformat wird akzeptiert; OpenClaw konvertiert bei Bedarf zu OGG/Opus.

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

Fehlerbehebung

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

Konfigurationsreferenz

Primäre Referenz: Konfigurationsreferenz - Discord.

Sicherheit und Betrieb

• Behandeln Sie Bot-Tokens als Geheimnisse (DISCORD_BOT_TOKEN bevorzugt in überwachten Umgebungen).
• Gewähren Sie Discord-Berechtigungen nach dem Prinzip der geringsten Rechte.
• Wenn Befehls-Deployment/-Status veraltet ist, starten Sie den Gateway neu und prüfen Sie erneut mit openclaw channels status --probe.

Verwandt