Mainstream messaging
Discord
Bereit für DMs und Guild-Kanäle über das offizielle Discord-Gateway.
Discord-DMs verwenden standardmäßig den Kopplungsmodus.
Natives Befehlsverhalten und Befehlskatalog.
Kanalübergreifende Diagnose und Reparaturablauf.
Schnelle Einrichtung
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).
Discord-Anwendung und Bot erstellen
Gehen Sie zum Discord Developer Portal und klicken Sie auf New Application. Benennen Sie sie zum Beispiel „OpenClaw“.
Klicken Sie in der Seitenleiste auf Bot. Setzen Sie den Username auf den Namen, den Sie für Ihren OpenClaw-Agenten verwenden.
Privilegierte Intents aktivieren
Bleiben Sie auf der Seite Bot, scrollen Sie nach unten zu Privileged Gateway Intents und aktivieren Sie:
- Message Content Intent (erforderlich)
- Server Members Intent (empfohlen; erforderlich für Rollen-Allowlists und Namens-zu-ID-Abgleich)
- Presence Intent (optional; nur für Presence-Updates erforderlich)
Bot-Token kopieren
Scrollen Sie auf der Seite Bot wieder nach oben und klicken Sie auf Reset Token.
Kopieren Sie das Token und speichern Sie es an einem Ort. Dies ist Ihr Bot Token, und Sie benötigen es gleich.
Einladungs-URL generieren und den Bot zu Ihrem Server hinzufügen
Klicken Sie in der Seitenleiste auf OAuth2. Sie generieren eine Einladungs-URL mit den richtigen Berechtigungen, um den Bot zu Ihrem Server hinzuzufügen.
Scrollen Sie nach unten zu OAuth2 URL Generator und aktivieren Sie:
botapplications.commands
Darunter erscheint ein Abschnitt Bot Permissions. Aktivieren Sie mindestens:
General Permissions
- Kanäle anzeigen
Text Permissions
- Nachrichten senden
- Nachrichtenverlauf lesen
- Links einbetten
- Dateien anhängen
- Reaktionen hinzufügen (optional)
Dies ist die Basisausstattung für normale Textkanäle. Wenn Sie vorhaben, in Discord-Threads zu posten, einschließlich Workflows für Forum- oder Medienkanäle, die einen Thread erstellen oder fortsetzen, aktivieren Sie außerdem Send Messages in Threads. Kopieren Sie die generierte URL unten, fügen Sie sie in Ihren Browser ein, wählen Sie Ihren Server aus und klicken Sie auf Continue, um die Verbindung herzustellen. Sie sollten Ihren Bot jetzt auf dem Discord-Server sehen.
Entwicklermodus aktivieren und Ihre IDs erfassen
Zurück in der Discord-App müssen Sie den Entwicklermodus aktivieren, damit Sie interne IDs kopieren können.
-
Klicken Sie auf User Settings (Zahnradsymbol neben Ihrem Avatar) → scrollen Sie in der Seitenleiste zu Developer → aktivieren Sie Developer Mode
(Hinweis: In der mobilen Discord-App befindet sich der Entwicklermodus unter App Settings → Advanced)
-
Klicken Sie mit der rechten Maustaste auf Ihr Serversymbol in der Seitenleiste → Copy Server ID
-
Klicken Sie mit der rechten Maustaste auf Ihren eigenen Avatar → Copy User ID
Speichern Sie Ihre Server ID und User ID zusammen mit Ihrem Bot Token - Sie senden alle drei im nächsten Schritt an OpenClaw.
DMs von Servermitgliedern erlauben
Damit die Kopplung funktioniert, muss Discord Ihrem Bot erlauben, Ihnen eine DM zu senden. Klicken Sie mit der rechten Maustaste auf Ihr Serversymbol → Privacy Settings → aktivieren Sie Direct Messages.
Dadurch können Servermitglieder (einschließlich Bots) Ihnen DMs senden. Lassen Sie dies aktiviert, wenn Sie Discord-DMs mit OpenClaw verwenden möchten. Wenn Sie nur Guild-Kanäle verwenden möchten, können Sie DMs nach der Kopplung deaktivieren.
Bot-Token sicher setzen (nicht im Chat senden)
Ihr Discord-Bot-Token ist ein Geheimnis (wie ein Passwort). Setzen Sie es auf dem Computer, auf dem OpenClaw läuft, bevor Sie Ihrem Agenten eine Nachricht senden.
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 gatewayWenn OpenClaw bereits als Hintergrunddienst läuft, starten Sie es über die OpenClaw-Mac-App neu oder beenden und starten Sie den Prozess openclaw gateway run erneut.
Für verwaltete Dienstinstallationen führen Sie openclaw gateway install aus einer Shell aus, in der DISCORD_BOT_TOKEN vorhanden ist, oder speichern Sie die Variable in ~/.openclaw/.env, damit der Dienst den env-SecretRef nach dem Neustart auflösen kann.
Wenn Ihr Host durch Discords Startup-Anwendungsabfrage blockiert oder rate-limitiert wird, setzen Sie die Discord-Anwendungs-/Client-ID aus dem Developer Portal, damit der Start diesen REST-Aufruf überspringen kann. Verwenden Sie channels.discord.applicationId für das Standardkonto oder channels.discord.accounts.<accountId>.applicationId, wenn Sie mehrere Discord-Bots ausführen.
OpenClaw konfigurieren und koppeln
Ihren Agenten fragen
Chatten Sie mit Ihrem OpenClaw-Agenten in einem vorhandenen Kanal (z. B. Telegram) und teilen Sie es ihm mit. Wenn Discord Ihr erster Kanal ist, verwenden Sie stattdessen den Tab CLI / config.
„Ich habe mein Discord-Bot-Token bereits in der Konfiguration gesetzt. Bitte schließen Sie die Discord-Einrichtung mit User ID
<user_id>und Server ID<server_id>ab.“
CLI / config
Wenn Sie dateibasierte Konfiguration bevorzugen, setzen Sie:
{channels: {discord: {enabled: true,token: {source: "env",provider: "default",id: "DISCORD_BOT_TOKEN",},},},}Env-Fallback für das Standardkonto:
DISCORD_BOT_TOKEN=...Für skriptbasierte oder Remote-Einrichtung schreiben Sie denselben JSON5-Block mit openclaw config patch --file ./discord.patch.json5 --dry-run und führen Sie ihn dann erneut ohne --dry-run aus. Klartext-token-Werte werden unterstützt. SecretRef-Werte werden ebenfalls für channels.discord.token über env/file/exec-Provider hinweg unterstützt. Siehe Geheimnisverwaltung.
Für mehrere Discord-Bots halten Sie jedes Bot-Token und jede Anwendungs-ID unter dem jeweiligen Konto. Ein channels.discord.applicationId auf oberster Ebene wird von Konten geerbt. Setzen Sie es dort daher nur, wenn jedes Konto dieselbe Anwendungs-ID verwenden soll.
{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",},},},},}Erste DM-Kopplung genehmigen
Warten Sie, bis das Gateway läuft, und senden Sie Ihrem Bot dann eine DM in Discord. Er antwortet mit einem Kopplungscode.
Ihren Agenten fragen
Senden Sie den Kopplungscode in Ihrem vorhandenen Kanal an Ihren Agenten:
„Genehmigen Sie diesen Discord-Kopplungscode:
<CODE>“
CLI
openclaw pairing list discordopenclaw pairing approve discord <CODE>Kopplungscodes laufen nach 1 Stunde ab.
Sie sollten jetzt per DM in Discord mit Ihrem Agenten chatten können.
Empfohlen: Guild-Arbeitsbereich einrichten
Sobald DMs funktionieren, können Sie Ihren Discord-Server als vollständigen Arbeitsbereich 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.
Ihren Server zur Guild-Allowlist hinzufügen
Dadurch kann Ihr Agent in jedem Kanal auf Ihrem Server antworten, nicht nur in DMs.
Ihren Agenten fragen
„Fügen Sie meine Discord Server ID
<server_id>zur Guild-Allowlist hinzu“
Config
{channels: {discord: {groupPolicy: "allowlist",guilds: {YOUR_SERVER_ID: { requireMention: true, users: ["YOUR_USER_ID"],},},},},}Antworten ohne @mention erlauben
Standardmäßig antwortet Ihr Agent in Guild-Kanälen nur, wenn er @erwähnt wird. Für einen privaten Server möchten Sie wahrscheinlich, dass er auf jede Nachricht antwortet.
In Guild-Kanälen werden normale Antworten standardmäßig automatisch gepostet. Aktivieren Sie für gemeinsam genutzte Always-on-Räume messages.groupChat.visibleReplies: "message_tool", damit der Agent mitlesen und nur posten kann, wenn er entscheidet, dass eine Kanalantwort nützlich ist. Dies funktioniert am besten mit Modellen der neuesten Generation mit zuverlässiger Tool-Nutzung, z. B. GPT 5.5. Ambient-Raumereignisse bleiben still, sofern das Tool nicht sendet. Die vollständige Lurk-Modus-Konfiguration finden Sie unter Ambient-Raumereignisse.
Wenn Discord Tippen anzeigt und die Logs Token-Nutzung zeigen, aber keine Nachricht gepostet wird, prüfen Sie, ob der Turn als Ambient-Raumereignis konfiguriert war oder sichtbare Antworten über das Nachrichten-Tool aktiviert wurden.
Ihren Agenten fragen
„Erlauben Sie meinem Agenten, auf diesem Server zu antworten, ohne @erwähnt werden zu müssen“
Config
Setzen Sie requireMention: false in Ihrer Guild-Konfiguration:
{channels: {discord: {guilds: {YOUR_SERVER_ID: { requireMention: false,},},},},}Um Nachrichten-Tool-Sends für sichtbare Gruppen-/Kanalantworten zu verlangen, setzen Sie messages.groupChat.visibleReplies: "message_tool".
Speicher in Guild-Kanälen einplanen
Standardmäßig wird der Langzeitspeicher (MEMORY.md) nur in DM-Sitzungen geladen. Guild-Kanäle laden MEMORY.md nicht automatisch.
Ihren Agenten fragen
„Wenn ich Fragen in Discord-Kanälen stelle, verwenden Sie memory_search oder memory_get, falls Sie Langzeitkontext aus MEMORY.md benötigen.“
Manuell
Wenn Sie in jedem Kanal gemeinsamen Kontext benötigen, legen Sie die stabilen Anweisungen in AGENTS.md oder USER.md ab (sie werden für jede Sitzung injiziert). Bewahren Sie Langzeitnotizen in MEMORY.md auf und greifen Sie bei Bedarf mit Speicher-Tools darauf zu.
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 alles einrichten, was 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-/Kanal-Metadaten werden dem Modell-Prompt als nicht vertrauenswürdiger Kontext hinzugefügt, nicht als für Benutzer sichtbares Antwortpräfix. Wenn ein Modell diese Hülle zurückkopiert, entfernt OpenClaw die kopierten Metadaten aus ausgehenden Antworten und aus künftigem Wiedergabekontext.
- Standardmäßig (
session.dmScope=main) teilen Direktchats die Hauptsitzung des Agents (agent:main:main). - Guild-Kanäle sind isolierte Sitzungsschlüssel (
agent:<agentId>:discord:channel:<channelId>). - Gruppen-DMs werden standardmäßig ignoriert (
channels.discord.dm.groupEnabled=false). - Native Slash-Befehle laufen in isolierten Befehlssitzungen (
agent:<agentId>:discord:slash:<userId>), führen aber weiterhinCommandTargetSessionKeyfür die geroutete Konversationssitzung mit. - Rein textbasierte Cron-/Heartbeat-Ankündigungen an Discord verwenden die endgültige für den Assistenten sichtbare Antwort genau einmal. Medien- und strukturierte Komponenten-Payloads bleiben Mehrfachnachrichten, wenn der Agent mehrere zustellbare Payloads ausgibt.
Forumskanäle
Discord-Forum- und Medienkanäle akzeptieren nur Thread-Beiträge. OpenClaw unterstützt zwei Möglichkeiten, sie zu erstellen:
- Senden Sie eine Nachricht an das Forum übergeordnete Element (
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 Forumskanäle kein--message-id.
Beispiel: an das Forum übergeordnete Element 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 übergeordnete Elemente akzeptieren keine Discord-Komponenten. Wenn Sie Komponenten benötigen, senden 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- Aktionszeilen erlauben bis zu 5 Buttons oder ein einzelnes Auswahlmenü
- Auswahltypen:
string,user,role,mentionable,channel
Standardmäßig sind Komponenten nur einmal verwendbar. Setzen Sie components.reusable=true, damit Buttons, Auswahlen und Formulare mehrfach verwendet werden können, bis sie ablaufen.
Um einzuschränken, wer auf einen Button klicken kann, setzen Sie allowedUsers für diesen Button (Discord-Benutzer-IDs, Tags oder *). Wenn konfiguriert, erhalten nicht übereinstimmende Benutzer eine ephemere Ablehnung.
Komponenten-Callbacks laufen standardmäßig nach 30 Minuten ab. Setzen Sie channels.discord.agentComponents.ttlMs, um diese Callback-Registry-Lebensdauer für das standardmäßige Discord-Konto zu ändern, oder channels.discord.accounts.<accountId>.agentComponents.ttlMs, um ein Konto in einer Multi-Konto-Einrichtung zu überschreiben. Der Wert ist in Millisekunden, muss eine positive Ganzzahl sein und ist auf 86400000 (24 Stunden) begrenzt. Längere TTLs sind nützlich für Review- oder Genehmigungs-Workflows, bei denen Buttons nutzbar bleiben müssen, erweitern aber auch das Zeitfenster, in dem eine alte Discord-Nachricht noch eine Aktion auslösen kann. Bevorzugen Sie die kürzeste TTL, die zum Workflow passt, und behalten Sie die Voreinstellung bei, wenn veraltete Callbacks überraschend wären.
Die Slash-Befehle /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 Auswahlantwort ist ephemer, und nur der aufrufende Benutzer kann sie verwenden. Discord-Auswahlmenüs sind auf 25 Optionen begrenzt. Fügen Sie daher provider/*-Einträge zu agents.defaults.models hinzu, wenn die Auswahl dynamisch erkannte Modelle nur für ausgewählte Provider wie openai oder vllm anzeigen soll.
Dateianhänge:
file-Blöcke müssen auf eine Anhangsreferenz zeigen (attachment://<filename>)- Stellen Sie den Anhang über
media/path/filePathbereit (einzelne Datei); verwenden Siemedia-galleryfür mehrere Dateien - Verwenden Sie
filename, um den Upload-Namen zu überschreiben, wenn er zur Anhangsreferenz passen soll
Modale Formulare:
- Fügen Sie
components.modalmit bis zu 5 Feldern hinzu - Feldtypen:
text,checkbox,radio,select,role-select,user-select - OpenClaw fügt automatisch einen Auslösebutton 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
DM policy
channels.discord.dmPolicy steuert den DM-Zugriff. channels.discord.allowFrom ist die kanonische DM-Allowlist.
pairing(Standard)allowlistopen(erfordert, dasschannels.discord.allowFrom"*"enthält)disabled
Wenn die DM-Richtlinie nicht offen ist, werden unbekannte Benutzer blockiert (oder im Modus pairing zur Kopplung aufgefordert).
Vorrang bei mehreren Konten:
channels.discord.accounts.default.allowFromgilt nur für das Kontodefault.- Bei einem Konto hat
allowFromVorrang vor dem Legacy-dm.allowFrom. - Benannte Konten erben
channels.discord.allowFrom, wenn ihr eigenesallowFromund das Legacy-dm.allowFromnicht gesetzt sind. - Benannte Konten erben
channels.discord.accounts.default.allowFromnicht.
Legacy-channels.discord.dm.policy und channels.discord.dm.allowFrom werden aus Kompatibilitätsgründen weiterhin gelesen. openclaw doctor --fix migriert sie zu dmPolicy und allowFrom, wenn dies ohne Änderung des Zugriffs möglich ist.
DM-Zielformat für die Zustellung:
user:<id><@id>-Erwähnung
Reine numerische IDs werden normalerweise als Kanal-IDs aufgelöst, wenn ein Kanalstandard aktiv ist, aber IDs, die in der effektiven DM-allowFrom des Kontos aufgeführt sind, werden aus Kompatibilitätsgründen als Benutzer-DM-Ziele behandelt.
Access groups
Discord-DMs und die Autorisierung von Textbefehlen können dynamische accessGroup:<name>-Einträge in channels.discord.allowFrom verwenden.
Zugriffgruppennamen werden kanalübergreifend für Nachrichtenkanäle geteilt. Verwenden Sie type: "message.senders" für eine statische Gruppe, deren Mitglieder in der normalen allowFrom-Syntax jedes Kanals ausgedrückt werden, oder type: "discord.channelAudience", wenn die aktuelle ViewChannel-Zielgruppe eines Discord-Kanals die Mitgliedschaft dynamisch definieren soll. Gemeinsames Zugriffgruppenverhalten ist hier dokumentiert: Zugriffgruppen.
{accessGroups: {operators: { type: "message.senders", members: { "*": ["global-owner-id"], discord: ["discord:123456789012345678"], telegram: ["987654321"], },},},channels: {discord: { dmPolicy: "allowlist", allowFrom: ["accessGroup:operators"],},},}Ein Discord-Textkanal hat keine separate Mitgliederliste. type: "discord.channelAudience" modelliert die Mitgliedschaft wie folgt: Der DM-Absender ist Mitglied der konfigurierten Guild und hat derzeit die effektive ViewChannel-Berechtigung für den konfigurierten Kanal, nachdem Rollen- und Kanalüberschreibungen angewendet wurden.
Beispiel: Erlauben Sie allen, die #maintainers sehen können, dem Bot eine DM zu senden, während DMs für alle anderen geschlossen bleiben.
{accessGroups: {maintainers: { type: "discord.channelAudience", guildId: "1456350064065904867", channelId: "1456744319972282449", membership: "canViewChannel",},},channels: {discord: { dmPolicy: "allowlist", allowFrom: ["accessGroup:maintainers"],},},}Sie können dynamische und statische Einträge mischen:
{accessGroups: {maintainers: { type: "discord.channelAudience", guildId: "1456350064065904867", channelId: "1456744319972282449",},},channels: {discord: { dmPolicy: "allowlist", allowFrom: ["accessGroup:maintainers", "discord:123456789012345678"],},},}Nachschlagen schlägt geschlossen fehl. Wenn Discord Missing Access zurückgibt, die Mitgliedersuche fehlschlägt oder der Kanal zu einer anderen Guild gehört, wird der DM-Absender als nicht autorisiert behandelt.
Aktivieren Sie im Discord Developer Portal den Server Members Intent für den Bot, wenn Sie kanalzielgruppenbasierte Zugriffgruppen verwenden. DMs enthalten keinen Guild-Mitgliedsstatus, daher löst OpenClaw das Mitglied zum Autorisierungszeitpunkt über Discord REST auf.
Guild policy
Guild-Behandlung wird durch channels.discord.groupPolicy gesteuert:
openallowlistdisabled
Die sichere Basislinie, wenn channels.discord vorhanden ist, ist allowlist.
Verhalten von allowlist:
- Guild muss
channels.discord.guildsentsprechen (idbevorzugt, Slug akzeptiert) - optionale Absender-Allowlists:
users(stabile IDs empfohlen) undroles(nur Rollen-IDs); wenn eines von beiden konfiguriert ist, sind Absender erlaubt, wenn sieusersODERrolesentsprechen - direkter Namens-/Tag-Abgleich ist standardmäßig deaktiviert; aktivieren Sie
channels.discord.dangerouslyAllowNameMatching: truenur als Notfall-Kompatibilitätsmodus - Namen/Tags werden für
usersunterstützt, aber IDs sind sicherer;openclaw security auditwarnt, wenn Namens-/Tag-Einträge verwendet werden - wenn eine Guild
channelskonfiguriert hat, werden nicht aufgeführte Kanäle abgelehnt - wenn eine Guild keinen
channels-Block hat, sind alle Kanäle in dieser allowgelisteten Guild erlaubt
Beispiel:
{channels: {discord: { groupPolicy: "allowlist", guilds: { "123456789012345678": { requireMention: true, ignoreOtherMentions: true, users: ["987654321098765432"], roles: ["123456789012345678"], channels: { general: { allow: true }, help: { allow: true, requireMention: true }, }, }, },},},}Wenn Sie nur DISCORD_BOT_TOKEN setzen und keinen channels.discord-Block erstellen, ist der Runtime-Fallback groupPolicy="allowlist" (mit einer Warnung in den Logs), auch wenn channels.defaults.groupPolicy open ist.
Mentions and group DMs
Guild-Nachrichten sind standardmäßig durch Erwähnungen geschützt.
Erwähnungserkennung umfasst:
- explizite Bot-Erwähnung
- konfigurierte Erwähnungsmuster (
agents.list[].groupChat.mentionPatterns, Fallbackmessages.groupChat.mentionPatterns) - implizites Antwort-an-Bot-Verhalten in unterstützten Fällen
Verwenden Sie beim Schreiben ausgehender Discord-Nachrichten die kanonische Erwähnungssyntax: <@USER_ID> für Benutzer, <#CHANNEL_ID> für Kanäle und <@&ROLE_ID> für Rollen. Verwenden Sie nicht die Legacy-Nickname-Erwähnungsform <@!USER_ID>.
requireMention wird pro Guild/Kanal konfiguriert (channels.discord.guilds...).
ignoreOtherMentions verwirft optional Nachrichten, die einen anderen Benutzer/eine andere Rolle erwähnen, aber nicht den Bot (ausgenommen @everyone/@here).
Gruppen-DMs:
- Standard: ignoriert (
dm.groupEnabled=false) - optionale Allowlist über
dm.groupChannels(Kanal-IDs oder Slugs)
Rollenbasiertes Agent-Routing
Verwenden Sie bindings[].match.roles, um Discord-Guild-Mitglieder anhand der Rollen-ID an unterschiedliche Agenten weiterzuleiten. Rollenbasierte Bindings akzeptieren ausschließlich Rollen-IDs und werden nach Peer- oder Parent-Peer-Bindings und vor Guild-only-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 Befehle und Befehlsauthentifizierung
commands.nativeist standardmäßig"auto"und für Discord aktiviert.- Überschreibung pro Kanal:
channels.discord.commands.native. commands.native=falseüberspringt die Registrierung und Bereinigung von Discord-Slash-Befehlen beim Start. Zuvor registrierte Befehle können in Discord sichtbar bleiben, bis Sie sie aus der Discord-App entfernen.- Die Authentifizierung nativer Befehle verwendet dieselben Discord-Allowlists/Richtlinien wie die normale Nachrichtenverarbeitung.
- Befehle 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-Befehle für Befehlskatalog und Verhalten.
Standardeinstellungen für Slash-Befehle:
ephemeral: true
Funktionsdetails
Antwort-Tags und native Antworten
Discord unterstützt Antwort-Tags in Agentenausgaben:
[[reply_to_current]][[reply_to:<id>]]
Gesteuert durch channels.discord.replyToMode:
off(Standard)firstallbatched
Hinweis: off deaktiviert implizites Reply-Threading. Explizite [[reply_to_*]]-Tags werden weiterhin beachtet.
first hängt die implizite native Antwortreferenz immer an die erste ausgehende Discord-Nachricht des Turns an.
batched hängt die implizite native Discord-Antwortreferenz nur an, wenn das
eingehende Ereignis ein debounced Batch mehrerer Nachrichten war. Das ist nützlich,
wenn Sie native Antworten hauptsächlich für mehrdeutige, stoßweise Chats wünschen, nicht für jeden
Turn mit nur einer Nachricht.
Nachrichten-IDs werden im Kontext/Verlauf verfügbar gemacht, damit Agenten gezielt bestimmte Nachrichten adressieren können.
Link-Vorschauen
Discord erzeugt standardmäßig Rich-Link-Embeds für URLs. OpenClaw unterdrückt diese generierten Embeds bei ausgehenden Discord-Nachrichten standardmäßig, sodass von Agenten gesendete URLs als einfache Links bleiben, sofern Sie dies nicht aktivieren:
{channels: {discord: { suppressEmbeds: false,},},}Setzen Sie channels.discord.accounts.<id>.suppressEmbeds, um ein Konto zu überschreiben. Sendevorgänge mit dem Agent-Nachrichten-Tool können für eine einzelne Nachricht auch suppressEmbeds: false übergeben. Explizite Discord-embeds-Payloads werden durch die Standard-Link-Vorschau-Einstellung nicht unterdrückt.
Live-Stream-Vorschau
OpenClaw kann Antwortentwürfe streamen, indem es eine temporäre Nachricht sendet und sie bearbeitet, während Text eintrifft. channels.discord.streaming akzeptiert off | partial | block | progress (Standard). progress behält einen bearbeitbaren Statusentwurf bei und aktualisiert ihn bis zur finalen Zustellung mit Tool-Fortschritt; das gemeinsame Startlabel ist eine fortlaufende Zeile, sodass es wie der Rest aus dem sichtbaren Bereich scrollt, sobald genug Arbeit erscheint. streamMode ist ein Legacy-Runtime-Alias. Führen Sie openclaw doctor --fix aus, um persistierte Konfiguration auf den kanonischen Schlüssel umzuschreiben.
Setzen Sie channels.discord.streaming.mode auf off, um Discord-Vorschau-Bearbeitungen zu deaktivieren. Wenn Discord-Block-Streaming ausdrücklich aktiviert ist, überspringt OpenClaw den Vorschau-Stream, um doppeltes Streaming zu vermeiden.
{channels: {discord: { streaming: { mode: "progress", progress: { label: "auto", maxLines: 8, maxLineChars: 120, toolProgress: true, commentary: false, }, },},},}partialbearbeitet eine einzelne Vorschau-Nachricht, während Tokens eintreffen.blockgibt entwurfsgrößenbasierte Chunks aus (verwenden SiedraftChunk, um Größe und Umbruchpunkte anzupassen, begrenzt durchtextChunkLimit).- Medien, Fehler und finale Antworten mit expliziter Antwortreferenz brechen ausstehende Vorschau-Bearbeitungen ab.
streaming.preview.toolProgress(Standardtrue) steuert, ob Tool-/Fortschrittsupdates die Vorschau-Nachricht wiederverwenden.- Tool-/Fortschrittszeilen werden, sofern verfügbar, als kompaktes Emoji + Titel + Detail dargestellt, zum Beispiel
🛠️ Bash: run testsoder🔎 Web Search: for "query". streaming.progress.commentary(Standardfalse) aktiviert Assistant-Kommentar-/Präambeltext im temporären Fortschrittsentwurf. Kommentare werden vor der Anzeige bereinigt, bleiben vorübergehend und ändern die finale Antwortzustellung nicht.streaming.progress.maxLineCharssteuert das Vorschau-Budget pro Fortschrittszeile. Fließtext wird an Wortgrenzen gekürzt; Befehls- und Pfaddetails behalten nützliche Suffixe.streaming.preview.commandText/streaming.progress.commandTextsteuert Befehls-/Exec-Details in kompakten Fortschrittszeilen:raw(Standard) oderstatus(nur Tool-Label).
Rohtext von Befehlen/Exec ausblenden, während kompakte Fortschrittszeilen erhalten bleiben:
{ "channels": { "discord": { "streaming": { "mode": "progress", "progress": { "toolProgress": true, "commandText": "status" } } } }}Vorschau-Streaming ist rein textbasiert; Medienantworten fallen auf die normale Zustellung zurück. Wenn block-Streaming ausdrücklich aktiviert ist, überspringt OpenClaw den Vorschau-Stream, um doppeltes Streaming zu vermeiden.
Verlauf, Kontext und Thread-Verhalten
Guild-Verlaufskontext:
channels.discord.historyLimitStandard20- Fallback:
messages.groupChat.historyLimit 0deaktiviert
DM-Verlaufssteuerung:
channels.discord.dmHistoryLimitchannels.discord.dms["<user_id>"].historyLimit
Thread-Verhalten:
- Discord-Threads werden als Kanalsitzungen geroutet und erben die Konfiguration des übergeordneten Kanals, sofern sie nicht überschrieben wird.
- Thread-Sitzungen erben die Sitzungsebenen-
/model-Auswahl des übergeordneten Kanals als reinen Modell-Fallback; Thread-lokale/model-Auswahlen haben weiterhin Vorrang, und der Transkriptverlauf des übergeordneten Kanals wird nicht kopiert, sofern Transkriptvererbung nicht aktiviert ist. channels.discord.thread.inheritParent(Standardfalse) aktiviert für neue Auto-Threads das Seeding aus dem übergeordneten Transkript. Überschreibungen pro Konto befinden sich unterchannels.discord.accounts.<id>.thread.inheritParent.- Nachrichten-Tool-Reaktionen können
user:<id>-DM-Ziele auflösen. guilds.<guild>.channels.<channel>.requireMention: falsebleibt während des Aktivierungs-Fallbacks in der Antwortphase erhalten.
Kanalthemen werden als nicht vertrauenswürdiger Kontext injiziert. Allowlists steuern, wer den Agenten auslösen kann, sind aber keine vollständige Redaktionsgrenze für Zusatzkontext.
Thread-gebundene Sitzungen für Subagenten
Discord kann einen Thread an ein Sitzungsziel binden, sodass Folgenachrichten in diesem Thread weiterhin an dieselbe Sitzung geroutet werden (einschließlich Subagenten-Sitzungen).
Befehle:
/focus <target>bindet den aktuellen/neuen Thread an ein Subagenten-/Sitzungsziel/unfocusentfernt die aktuelle Thread-Bindung/agentszeigt aktive Läufe und Bindungsstatus an/session idle <duration|off>prüft/aktualisiert das Inaktivitäts-Auto-Unfocus für fokussierte Bindings/session max-age <duration|off>prüft/aktualisiert das harte Höchstalter für fokussierte Bindings
Konfiguration:
{session: {threadBindings: { enabled: true, idleHours: 24, maxAgeHours: 0,},},channels: {discord: { threadBindings: { enabled: true, idleHours: 24, maxAgeHours: 0, spawnSessions: true, defaultSpawnContext: "fork", },},},}Hinweise:
session.threadBindings.*legt globale Standards fest.channels.discord.threadBindings.*überschreibt das Discord-Verhalten.spawnSessionssteuert das automatische Erstellen/Binden von Threads fürsessions_spawn({ thread: true })und ACP-Thread-Spawns. Standard:true.defaultSpawnContextsteuert den nativen Subagenten-Kontext für Thread-gebundene Spawns. Standard:"fork".- Veraltete Schlüssel
spawnSubagentSessions/spawnAcpSessionswerden durchopenclaw doctor --fixmigriert. - Wenn Thread-Bindings für ein Konto deaktiviert sind, sind
/focusund verwandte Thread-Binding-Operationen nicht verfügbar.
Siehe Subagenten, ACP-Agenten und Konfigurationsreferenz.
Persistente ACP-Kanal-Bindings
Für stabile „always-on“-ACP-Arbeitsbereiche konfigurieren Sie Top-Level-typisierte ACP-Bindings, die auf Discord-Unterhaltungen zielen.
Konfigurationspfad:
bindings[]mittype: "acp"undmatch.channel: "discord"
Beispiel:
{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, }, }, }, },},},}Hinweise:
/acp spawn codex --bind herebindet den aktuellen Kanal oder Thread an Ort und Stelle und hält zukünftige Nachrichten in derselben ACP-Sitzung. Thread-Nachrichten erben die Bindung des übergeordneten Kanals.- In einem gebundenen Kanal oder Thread setzen
/newund/resetdieselbe ACP-Sitzung an Ort und Stelle zurück. Temporäre Thread-Bindings können die Zielauflösung überschreiben, solange sie aktiv sind. spawnSessionssteuert das Erstellen/Binden von Child-Threads über--thread auto|here.
Siehe ACP-Agenten für Details zum Binding-Verhalten.
Reaktionsbenachrichtigungen
Reaktionsbenachrichtigungsmodus pro Guild:
offown(Standard)allallowlist(verwendetguilds.<id>.users)
Reaktionsereignisse werden in Systemereignisse umgewandelt und an die geroutete Discord-Sitzung angehängt.
Ack-Reaktionen
ackReaction sendet ein Bestätigungs-Emoji, während OpenClaw eine eingehende Nachricht verarbeitet.
Auflösungsreihenfolge:
channels.discord.accounts.<accountId>.ackReactionchannels.discord.ackReactionmessages.ackReaction- Fallback auf Identitäts-Emoji des Agenten (
agents.list[].identity.emoji, sonst "👀")
Hinweise:
- Discord akzeptiert Unicode-Emoji oder benutzerdefinierte Emoji-Namen.
- Verwenden Sie
"", um die Reaktion für einen Kanal oder ein Konto zu deaktivieren.
Konfigurationsschreibvorgänge
Kanalinitiierte Konfigurationsschreibvorgänge sind standardmäßig aktiviert.
Dies betrifft /config set|unset-Flows (wenn Befehlsfunktionen aktiviert sind).
Deaktivieren:
{channels: {discord: { configWrites: false,},},}Gateway-Proxy
Leiten Sie Discord-Gateway-WebSocket-Verkehr und Startup-REST-Lookups (Anwendungs-ID + Allowlist-Auflösung) mit channels.discord.proxy über einen HTTP(S)-Proxy.
Discord-Gateway-WebSocket-Proxying ist explizit; WebSocket-Verbindungen erben keine umgebenden Proxy-Umgebungsvariablen vom Gateway-Prozess. Startup-REST-Lookups verwenden diesen Proxy, wenn channels.discord.proxy konfiguriert ist.
{channels: {discord: { proxy: "http://proxy.example:8080",},},}Überschreibung pro Konto:
{channels: {discord: { accounts: { primary: { proxy: "http://proxy.example:8080", }, },},},}PluralKit-Unterstützung
Aktivieren Sie die PluralKit-Auflösung, um weitergeleitete Nachrichten der Identität von Systemmitgliedern zuzuordnen:
{channels: {discord: { pluralkit: { enabled: true, token: "pk_live_...", // optional; needed for private systems },},},}Hinweise:
- Allowlists können
pk:<memberId>verwenden - Anzeigenamen von Mitgliedern werden nur dann nach Name/Slug abgeglichen, wenn
channels.discord.dangerouslyAllowNameMatching: truegesetzt ist - Suchvorgänge verwenden die ursprüngliche Nachrichten-ID und sind zeitfensterbeschränkt
- Wenn die Suche fehlschlägt, werden weitergeleitete Nachrichten als Bot-Nachrichten behandelt und verworfen, sofern nicht
allowBots=truegesetzt ist
Ausgehende Erwähnungsaliase
Verwenden Sie mentionAliases, wenn Agents deterministische ausgehende Erwähnungen für bekannte Discord-Benutzer benötigen. Schlüssel sind Handles ohne führendes @; Werte sind Discord-Benutzer-IDs. Unbekannte Handles, @everyone, @here und Erwähnungen innerhalb von Markdown-Code-Spans bleiben unverändert.
{channels: {discord: { mentionAliases: { Vladislava: "123456789012345678", }, accounts: { ops: { mentionAliases: { OpsLead: "234567890123456789", }, }, },},},}Präsenzkonfiguration
Präsenzaktualisierungen werden angewendet, wenn Sie ein Status- oder Aktivitätsfeld setzen oder automatische Präsenz aktivieren.
Beispiel nur für Status:
{channels: {discord: { status: "idle",},},}Aktivitätsbeispiel (benutzerdefinierter Status ist der Standardaktivitätstyp):
{channels: {discord: { activity: "Focus time", activityType: 4,},},}Streaming-Beispiel:
{channels: {discord: { activity: "Live coding", activityType: 1, activityUrl: "https://twitch.tv/openclaw",},},}Zuordnung der Aktivitätstypen:
- 0: Spielen
- 1: Streaming (erfordert
activityUrl) - 2: Zuhören
- 3: Zuschauen
- 4: Benutzerdefiniert (verwendet den Aktivitätstext als Statuszustand; Emoji ist optional)
- 5: Antreten
Beispiel für automatische Präsenz (Laufzeit-Gesundheitssignal):
{channels: {discord: { autoPresence: { enabled: true, intervalMs: 30000, minUpdateIntervalMs: 15000, exhaustedText: "token exhausted", },},},}Automatische Präsenz ordnet die Laufzeitverfügbarkeit dem Discord-Status zu: fehlerfrei => online, beeinträchtigt oder unbekannt => idle, erschöpft oder nicht verfügbar => dnd. Optionale Textüberschreibungen:
autoPresence.healthyTextautoPresence.degradedTextautoPresence.exhaustedText(unterstützt den Platzhalter{reason})
Genehmigungen in Discord
Discord unterstützt schaltflächenbasierte Genehmigungsverarbeitung in DMs und kann optional Genehmigungsaufforderungen im ursprünglichen Kanal posten.
Konfigurationspfad:
channels.discord.execApprovals.enabledchannels.discord.execApprovals.approvers(optional; fällt nach Möglichkeit aufcommands.ownerAllowFromzurück)channels.discord.execApprovals.target(dm|channel|both, Standard:dm)agentFilter,sessionFilter,cleanupAfterResolve
Discord aktiviert native Ausführungsgenehmigungen automatisch, wenn enabled nicht gesetzt oder "auto" ist und mindestens ein Genehmiger aufgelöst werden kann, entweder aus execApprovals.approvers oder aus commands.ownerAllowFrom. Discord leitet Ausführungsgenehmiger nicht aus Kanal-allowFrom, veraltetem dm.allowFrom oder Direct-Message-defaultTo ab. Setzen Sie enabled: false, um Discord ausdrücklich als nativen Genehmigungsclient zu deaktivieren.
Für sensible, nur Eigentümern vorbehaltene Gruppenbefehle wie /diagnostics und /export-trajectory sendet OpenClaw Genehmigungsaufforderungen und Endergebnisse privat. Es versucht zuerst Discord-DM, wenn der aufrufende Eigentümer eine Discord-Eigentümerroute hat; wenn diese nicht verfügbar ist, fällt es auf die erste verfügbare Eigentümerroute aus commands.ownerAllowFrom zurück, etwa Telegram.
Wenn target channel oder both ist, ist die Genehmigungsaufforderung im Kanal sichtbar. Nur aufgelöste Genehmiger können die Schaltflächen verwenden; andere Benutzer erhalten eine flüchtige Ablehnung. Genehmigungsaufforderungen enthalten den Befehlstext, aktivieren Sie Kanalzustellung daher nur in vertrauenswürdigen Kanälen. Wenn die Kanal-ID nicht aus dem Sitzungsschlüssel abgeleitet werden kann, fällt OpenClaw auf DM-Zustellung zurück.
Discord rendert außerdem die gemeinsamen Genehmigungsschaltflächen, die von anderen Chatkanälen verwendet werden. Der native Discord-Adapter fügt hauptsächlich Genehmiger-DM-Routing und Kanal-Fanout hinzu.
Wenn diese Schaltflächen vorhanden sind, sind sie die primäre Genehmigungs-UX; OpenClaw
sollte nur dann einen manuellen /approve-Befehl aufnehmen, wenn das Tool-Ergebnis besagt,
dass Chatgenehmigungen nicht verfügbar sind oder manuelle Genehmigung der einzige Weg ist.
Wenn die native Discord-Genehmigungslaufzeit nicht aktiv ist, lässt OpenClaw die
lokale deterministische Aufforderung /approve <id> <decision> sichtbar. Wenn die
Laufzeit aktiv ist, eine native Karte jedoch an kein Ziel zugestellt werden kann,
sendet OpenClaw im selben Chat einen Fallback-Hinweis mit dem exakten /approve-
Befehl aus der ausstehenden Genehmigung.
Gateway-Authentifizierung und Genehmigungsauflösung folgen dem gemeinsamen Gateway-Client-Vertrag (plugin:-IDs werden über plugin.approval.resolve aufgelöst; andere IDs über exec.approval.resolve). Genehmigungen laufen standardmäßig nach 30 Minuten ab.
Siehe Ausführungsgenehmigungen.
Tools und Aktions-Gates
Discord-Nachrichtenaktionen umfassen Messaging-, Kanaladministrations-, Moderations-, 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 Ereignisses festzulegen.
Aktions-Gates befinden sich unter channels.discord.actions.*.
Standardverhalten der Gates:
| Aktionsgruppe | Standard |
|---|---|
| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | aktiviert |
| roles | deaktiviert |
| moderation | deaktiviert |
| presence | deaktiviert |
Komponenten-v2-UI
OpenClaw verwendet Discord-Komponenten v2 für Ausführungsgenehmigungen und kontextübergreifende Marker. Discord-Nachrichtenaktionen können auch components für benutzerdefinierte UI akzeptieren (fortgeschritten; erfordert das Erstellen einer Komponenten-Payload über das Discord-Tool), während veraltete embeds weiterhin verfügbar sind, aber nicht empfohlen werden.
channels.discord.ui.components.accentColorlegt die Akzentfarbe fest, die von Discord-Komponentencontainern verwendet wird (Hex).- Pro Konto mit
channels.discord.accounts.<id>.ui.components.accentColorsetzen. channels.discord.agentComponents.ttlMssteuert, wie lange gesendete Discord-Komponenten-Callbacks registriert bleiben (Standard1800000, Maximum86400000). Pro Konto mitchannels.discord.accounts.<id>.agentComponents.ttlMssetzen.embedswerden ignoriert, wenn Komponenten v2 vorhanden sind.- Vorschauen für reine URLs werden standardmäßig unterdrückt. Setzen Sie
suppressEmbeds: falsebei einer Nachrichtenaktion, wenn ein einzelner ausgehender Link erweitert werden soll.
Beispiel:
{ channels: { discord: { ui: { components: { accentColor: "#5865F2", }, }, }, },}Voice
Discord hat zwei unterschiedliche Voice-Oberflächen: Echtzeit-Voice-Kanäle (fortlaufende Gespräche) und Voice-Nachrichtenanhänge (das Waveform-Vorschauformat). Das Gateway unterstützt beide.
Voice-Kanäle
Einrichtungscheckliste:
- Aktivieren Sie Message Content Intent im Discord Developer Portal.
- Aktivieren Sie Server Members Intent, wenn Rollen-/Benutzer-Allowlists verwendet werden.
- Laden Sie den Bot mit den Scopes
botundapplications.commandsein. - Gewähren Sie Connect, Speak, Send Messages und Read Message History im Ziel-Voice-Kanal.
- Aktivieren Sie native Befehle (
commands.nativeoderchannels.discord.commands.native). - 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 leaveUm die effektiven Berechtigungen des Bots vor dem Beitritt zu prüfen, führen Sie Folgendes aus:
openclaw channels capabilities --channel discord --target channel:<voice-channel-id>Beispiel für automatischen Beitritt:
{ channels: { discord: { voice: { enabled: true, model: "openai/gpt-5.5", autoJoin: [ { guildId: "123456789012345678", channelId: "234567890123456789", }, ], allowedChannels: [ { guildId: "123456789012345678", channelId: "234567890123456789", }, ], daveEncryption: true, decryptionFailureTolerance: 24, connectTimeoutMs: 30000, reconnectGraceMs: 15000, realtime: { provider: "openai", model: "gpt-realtime-2", speakerVoice: "cedar", }, }, }, },}Hinweise:
voice.ttsüberschreibtmessages.ttsnur für diestt-tts-Sprachwiedergabe. Realtime-Modi verwendenvoice.realtime.speakerVoice.voice.modesteuert den Konversationspfad. Standard istagent-proxy: Ein Realtime-Sprach-Frontend übernimmt Turn-Timing, Unterbrechung und Wiedergabe, delegiert inhaltliche Arbeit überopenclaw_agent_consultan den gerouteten OpenClaw-Agenten und behandelt das Ergebnis wie einen getippten Discord-Prompt dieses Sprechers.stt-ttsbehält den älteren Batch-STT-plus-TTS-Ablauf bei.bidilässt das Realtime-Modell direkt sprechen und stellt dabeiopenclaw_agent_consultfür das OpenClaw-Gehirn bereit.voice.agentSessionsteuert, welche OpenClaw-Konversation Sprach-Turns erhält. Lassen Sie es ungesetzt für die eigene Sitzung des Sprachkanals, oder setzen Sie{ mode: "target", target: "channel:<text-channel-id>" }, damit der Sprachkanal als Mikrofon-/Lautsprecher-Erweiterung einer bestehenden Discord-Textkanal-Sitzung wie#maintainersagiert.voice.modelüberschreibt das OpenClaw-Agentengehirn für Discord-Sprachantworten und Realtime-Consults. Lassen Sie es ungesetzt, um das geroutete Agentenmodell zu übernehmen. Es ist vonvoice.realtime.modelgetrennt.voice.followUserslässt den Bot Discord-Sprachkanälen mit ausgewählten Benutzern beitreten, zwischen ihnen wechseln und sie verlassen. Siehe Benutzern in Sprache folgen für Verhaltensregeln und Beispiele.agent-proxyleitet Sprache überdiscord-voice, wodurch die normale Besitzer-/Tool-Autorisierung für den Sprecher und die Zielsitzung erhalten bleibt, das Agenten-Toolttsaber ausgeblendet wird, weil Discord-Sprache die Wiedergabe besitzt. Standardmäßig gibtagent-proxydem Consult für Besitzer-Sprecher vollständigen, besitzeräquivalenten Tool-Zugriff (voice.realtime.toolPolicy: "owner") und bevorzugt nachdrücklich, vor inhaltlichen Antworten den OpenClaw-Agenten zu konsultieren (voice.realtime.consultPolicy: "always"). In diesem standardmäßigenalways-Modus spricht die Realtime-Schicht 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 Exaktsprache-Antworten eingereiht, bis die Wiedergabe untätig ist, statt Sprache mitten im Satz zu ersetzen.- Im
stt-tts-Modus verwendet STTtools.media.audio;voice.modelbeeinflusst die Transkription nicht. - In Realtime-Modi konfigurieren
voice.realtime.provider,voice.realtime.modelundvoice.realtime.speakerVoicedie Realtime-Audiositzung. Verwenden Sie für OpenAI Realtime 2 plus Codex-Gehirnvoice.realtime.model: "gpt-realtime-2"undvoice.model: "openai/gpt-5.5". - Realtime-Sprachmodi nehmen standardmäßig kleine Profildateien
IDENTITY.md,USER.mdundSOUL.mdin die Anweisungen des Realtime-Providers auf, damit schnelle direkte Turns dieselbe Identität, Benutzerverankerung und Persona wie der geroutete OpenClaw-Agent behalten. Setzen Sievoice.realtime.bootstrapContextFilesauf eine Teilmenge, um dies anzupassen, oder auf[], um es zu deaktivieren. Die unterstützten Realtime-Bootstrap-Dateien sind auf diese Profildateien beschränkt;AGENTS.mdbleibt im normalen Agentenkontext. Der eingefügte Profilkontext ersetztopenclaw_agent_consultnicht für Workspace-Arbeit, aktuelle Fakten, Speichersuche oder Tool-gestützte Aktionen. - Setzen Sie im OpenAI-
agent-proxy-Realtime-Modusvoice.realtime.requireWakeName: true, damit Discord-Realtime-Sprache stumm bleibt, bis ein Transkript mit einem Wake-Namen beginnt oder endet. Konfigurierte Wake-Namen müssen ein oder zwei Wörter sein. Wennvoice.realtime.wakeNamesungesetzt ist, verwendet OpenClaw den gerouteten Agenten-nameplusOpenClawund fällt auf die Agenten-ID plusOpenClawzurück. Wake-Name-Gating deaktiviert die automatische Antwort des Realtime-Providers, leitet akzeptierte Turns über den OpenClaw-Agenten-Consult-Pfad und gibt eine kurze gesprochene Bestätigung, wenn ein führender Wake-Name aus der Teiltranskription erkannt wird, bevor das endgültige Transkript eintrifft. - Der OpenAI-Realtime-Provider akzeptiert aktuelle Realtime-2-Ereignisnamen und ältere Codex-kompatible Aliasse für Ausgabeaudio- und Transkriptereignisse, sodass kompatible Provider-Snapshots abweichen können, ohne Assistant-Audio zu verwerfen.
voice.realtime.bargeInsteuert, ob Discord-Sprecherstart-Ereignisse aktive Realtime-Wiedergabe unterbrechen. Wenn ungesetzt, folgt es der Eingabeaudio-Unterbrechungseinstellung des Realtime-Providers.voice.realtime.minBargeInAudioEndMssteuert die minimale Assistant-Wiedergabedauer, bevor ein OpenAI-Realtime-Barge-in Audio abschneidet. Standard:250. Setzen Sie0fü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 untervoice.tts.providers.openai.speakerVoiceeine Text-to-Speech-Stimme.cedarist auf dem aktuellen OpenAI-TTS-Modell eine gute männlich klingende Wahl. - Discord-
systemPrompt-Überschreibungen pro Kanal gelten für Sprachtranskript-Turns dieses Sprachkanals. - Sprachtranskript-Turns leiten den Besitzerstatus aus Discord-
allowFrom(oderdm.allowFrom) für besitzergeschützte Befehle und Kanalaktionen ab. Die Sichtbarkeit von Agenten-Tools folgt der konfigurierten Tool-Policy für die geroutete Sitzung. - Discord-Sprache ist für reine Textkonfigurationen Opt-in; setzen Sie
channels.discord.voice.enabled=true(oder behalten Sie einen bestehendenchannels.discord.voice-Block), um/vc-Befehle, die Sprachlaufzeit und denGuildVoiceStates-Gateway-Intent zu aktivieren. channels.discord.intents.voiceStateskann das Abonnement für Voice-State-Intents ausdrücklich überschreiben. Lassen Sie es ungesetzt, damit der Intent der effektiven Sprachaktivierung folgt.- Wenn
voice.autoJoinmehrere Einträge für dieselbe Guild hat, tritt OpenClaw dem zuletzt konfigurierten Kanal für diese Guild bei. voice.allowedChannelsist eine optionale Aufenthalts-Allowlist. Lassen Sie sie ungesetzt, um/vc joinin jeden autorisierten Discord-Sprachkanal zu erlauben. Wenn sie gesetzt ist, sind/vc join, Auto-Join beim Start und Bot-Voice-State-Verschiebungen auf die aufgeführten{ guildId, channelId }-Einträge beschränkt. Setzen Sie sie auf ein leeres Array, um alle Discord-Sprachbeitritte 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, wenn eines verfügbar ist.voice.daveEncryptionundvoice.decryptionFailureTolerancewerden an die Join-Optionen von@discordjs/voicedurchgereicht.- Die Standardwerte von
@discordjs/voicesinddaveEncryption=trueunddecryptionFailureTolerance=24, wenn ungesetzt. - OpenClaw verwendet den gebündelten Codec
libopus-wasmfür Discord-Spracherfassung und Realtime-Raw-PCM-Wiedergabe. Es liefert einen gepinnten libopus-WebAssembly-Build mit und benötigt keine nativen opus-Add-ons. voice.connectTimeoutMssteuert das anfängliche@discordjs/voice-Warten auf Ready für/vc joinund Auto-Join-Versuche. Standard:30000.voice.reconnectGraceMssteuert, wie lange OpenClaw wartet, bis eine getrennte Sprachsitzung mit der Wiederverbindung beginnt, bevor sie zerstört wird. Standard:15000.- Im
stt-tts-Modus stoppt die Sprachwiedergabe nicht nur deshalb, weil ein anderer Benutzer zu sprechen beginnt. Um Feedback-Schleifen zu vermeiden, ignoriert OpenClaw neue Spracherfassung, während TTS abgespielt wird; sprechen Sie nach Ende der Wiedergabe für den nächsten Turn. Realtime-Modi leiten Sprecherstarts als Barge-in-Signale an den Realtime-Provider weiter. - In Realtime-Modi kann Echo von Lautsprechern in ein offenes Mikrofon wie Barge-in wirken und die Wiedergabe unterbrechen. Setzen Sie für Discord-Räume mit starkem Echo
voice.realtime.providers.openai.interruptResponseOnInputAudio: false, damit OpenAI bei Eingabeaudio nicht automatisch unterbricht. Fügen Sievoice.realtime.bargeIn: truehinzu, wenn Discord-Sprecherstart-Ereignisse aktive Wiedergabe weiterhin unterbrechen sollen. Die OpenAI-Realtime-Bridge ignoriert Wiedergabeabschneidungen, die kürzer alsvoice.realtime.minBargeInAudioEndMssind, als wahrscheinliches Echo/Rauschen und protokolliert sie als übersprungen, statt die Discord-Wiedergabe zu leeren. voice.captureSilenceGraceMssteuert, wie lange OpenClaw wartet, nachdem Discord gemeldet hat, dass ein Sprecher aufgehört hat, bevor dieses Audiosegment für STT finalisiert wird. Standard:2000; erhöhen Sie diesen Wert, wenn Discord normale Pausen in abgehackte Teiltranskripte aufteilt.- Wenn ElevenLabs der ausgewählte TTS-Provider ist, verwendet Discord-Sprachwiedergabe Streaming-TTS und startet aus dem Antwortstream des Providers. Provider ohne Streaming-Unterstützung fallen auf den synthetisierten temporären Dateipfad zurück.
- OpenClaw überwacht außerdem Empfangsentschlüsselungsfehler und stellt automatisch wieder her, indem es den Sprachkanal nach wiederholten Fehlern in einem kurzen Zeitfenster verlässt und erneut beitritt.
- Wenn Empfangslogs nach einer Aktualisierung wiederholt
DecryptionFailed(UnencryptedWhenPassthroughDisabled)zeigen, erfassen Sie einen Abhängigkeitsbericht 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. - Empfangsereignisse
The operation was abortedwerden erwartet, wenn OpenClaw ein erfasstes Sprechersegment finalisiert; sie sind ausführliche Diagnosen, keine Warnungen. - Ausführliche Discord-Sprachlogs enthalten eine begrenzte einzeilige STT-Transkriptvorschau für jedes akzeptierte Sprechersegment, sodass das Debugging sowohl die Benutzerseite als auch die Agentenantwortseite zeigt, ohne unbegrenzten Transkripttext auszugeben.
- Im
agent-proxy-Modus überspringt der erzwungene Consult-Fallback wahrscheinlich unvollständige Transkriptfragmente, etwa Text, der auf...endet, oder einen nachgestellten Verbinder wieand, sowie offensichtlich nicht handlungsrelevante Abschlüsse wie „bin gleich zurück“ oder „tschüss“. Logs zeigenforced agent consult skipped reason=..., wenn dadurch eine veraltete eingereihte Antwort verhindert wird.
Benutzern in Sprache folgen
Verwenden Sie voice.followUsers, wenn der Discord-Sprachbot bei einem oder mehreren bekannten Discord-Benutzern bleiben soll, statt beim Start einem festen Kanal beizutreten oder auf /vc join zu warten.
{ channels: { discord: { voice: { enabled: true, followUsersEnabled: true, followUsers: ["discord:123456789012345678"], allowedChannels: [ { guildId: "123456789012345678", channelId: "234567890123456789", }, ], }, }, },}Verhalten:
followUsersakzeptiert rohe Discord-Benutzer-IDs unddiscord:<id>-Werte. OpenClaw normalisiert beide Formen, bevor Voice-State-Ereignisse abgeglichen werden.followUsersEnabledist standardmäßigtrue, wennfollowUserskonfiguriert ist. Setzen Sie es auffalse, um die gespeicherte Liste zu behalten, aber das automatische Folgen in Sprachkanälen zu stoppen.- Wenn ein verfolgter Benutzer einem erlaubten Sprachkanal beitritt, tritt OpenClaw diesem Kanal bei. Wenn der Benutzer wechselt, wechselt OpenClaw mit. Wenn der aktive verfolgte Benutzer die Verbindung trennt, verlässt OpenClaw den Kanal.
- Wenn mehrere verfolgte Benutzer in derselben Guild sind und der aktive verfolgte Benutzer geht, wechselt OpenClaw zum Kanal eines anderen erfassten verfolgten Benutzers, bevor es die Guild verlässt. Wenn mehrere verfolgte Benutzer gleichzeitig wechseln, gewinnt das zuletzt beobachtete Voice-State-Ereignis.
allowedChannelsgilt weiterhin. Ein verfolgter Benutzer in einem nicht erlaubten Kanal wird ignoriert, und eine Follow-eigene Sitzung wechselt zu einem anderen verfolgten Benutzer oder verlässt den Kanal.- OpenClaw gleicht verpasste Voice-State-Ereignisse beim Start und in einem begrenzten Intervall ab. Der Abgleich beprobt konfigurierte Guilds und begrenzt REST-Lookups pro Lauf, sodass sehr große
followUsers-Listen mehr als ein Intervall benötigen können, um zu konvergieren. - Wenn Discord oder ein Admin den Bot verschiebt, während er einem Benutzer folgt, baut OpenClaw die Sprachsitzung neu auf und behält die Follow-Zugehörigkeit bei, wenn das Ziel erlaubt ist. Wenn der Bot außerhalb von
allowedChannelsverschoben wird, verlässt OpenClaw den Kanal und tritt dem konfigurierten Ziel wieder bei, wenn eines existiert. - DAVE-Empfangswiederherstellung kann denselben Kanal nach wiederholten Entschlüsselungsfehlern verlassen und erneut betreten. Follow-eigene Sitzungen behalten ihre Follow-Zugehörigkeit über diesen Wiederherstellungspfad hinweg, sodass ein späteres Trennen des verfolgten Benutzers den Kanal weiterhin verlässt.
Wählen Sie zwischen den Beitrittsmodi:
- Verwenden Sie
followUsersfür persönliche oder Betreiber-Setups, bei denen der Bot automatisch im Sprachkanal sein soll, wenn Sie es sind. - Verwenden Sie
autoJoinfür Bots in festen Räumen, die auch dann anwesend sein sollen, wenn kein erfasster Benutzer im Sprachkanal ist. - Verwenden Sie
/vc joinfür einmalige Beitritte oder Räume, in denen automatische Sprachanwesenheit überraschend wäre.
Discord-Sprachcodec:
- Sprach-Empfangsprotokolle zeigen
discord voice: opus decoder: libopus-wasm. - Die Echtzeitwiedergabe codiert rohes 48-kHz-Stereo-PCM mit demselben gebündelten Paket
libopus-wasmzu Opus, bevor Pakete an@discordjs/voiceübergeben werden. - Datei- und Provider-Stream-Wiedergabe transcodiert mit ffmpeg zu rohem 48-kHz-Stereo-PCM und verwendet anschließend
libopus-wasmfür den an Discord gesendeten Opus-Paketstream.
STT-plus-TTS-Pipeline:
- Discord-PCM-Erfassung wird in eine temporäre WAV-Datei konvertiert.
tools.media.audioübernimmt STT, zum Beispielopenai/gpt-4o-mini-transcribe.- Das Transkript wird über Discord-Ingress und Routing gesendet, während das Antwort-LLM mit einer Sprachausgabe-Policy ausgeführt wird, die das Agent-Tool
ttsausblendet und zurückgegebenen Text anfordert, weil Discord Voice die endgültige TTS-Wiedergabe besitzt. voice.modelüberschreibt, wenn festgelegt, nur das Antwort-LLM für diesen Sprachkanal-Turn.voice.ttswird übermessages.ttszusammengeführt; streamingfähige Provider speisen den Player direkt, andernfalls wird die resultierende Audiodatei im beigetretenen Kanal abgespielt.
Beispiel für eine Standard-Agent-Proxy-Sprachkanalsitzung:
{ channels: { discord: { voice: { enabled: true, model: "openai/gpt-5.5", followUsersEnabled: true, followUsers: ["123456789012345678"], realtime: { provider: "openai", model: "gpt-realtime-2", speakerVoice: "cedar", }, }, }, },}Ohne voice.agentSession-Block erhält jeder Sprachkanal seine eigene geroutete OpenClaw-Sitzung. Zum Beispiel spricht /vc join channel:234567890123456789 mit der Sitzung für diesen Discord-Sprachkanal. Das Echtzeitmodell ist nur das Voice-Frontend; inhaltliche Anfragen werden an den konfigurierten OpenClaw-Agent übergeben. Wenn das Echtzeitmodell ein endgültiges Transkript erzeugt, ohne das Consult-Tool aufzurufen, erzwingt OpenClaw Consult als Fallback, sodass sich der Standard weiterhin wie ein Gespräch mit dem Agent verhält.
Legacy-STT-plus-TTS-Beispiel:
{ 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", }, }, }, }, }, },}Echtzeit-Bidi-Beispiel:
{ channels: { discord: { voice: { enabled: true, mode: "bidi", model: "openai/gpt-5.5", realtime: { provider: "openai", model: "gpt-realtime-2", speakerVoice: "cedar", toolPolicy: "safe-read-only", consultPolicy: "always", }, }, }, },}Voice als Erweiterung einer vorhandenen Discord-Kanalsitzung:
{ channels: { discord: { voice: { enabled: true, mode: "agent-proxy", model: "openai/gpt-5.5", agentSession: { mode: "target", target: "channel:123456789012345678", }, realtime: { provider: "openai", model: "gpt-realtime-2", speakerVoice: "cedar", }, }, }, },}Im Modus agent-proxy tritt der Bot dem konfigurierten Sprachkanal bei, aber OpenClaw-Agent-Turns verwenden die normale geroutete Sitzung und den Agent des Zielkanals. Die Echtzeit-Voice-Sitzung spricht das zurückgegebene Ergebnis wieder in den Sprachkanal. Der Supervisor-Agent kann gemäß seiner Tool-Policy weiterhin normale Nachrichtentools verwenden, einschließlich des Sendens einer separaten Discord-Nachricht, wenn dies die richtige Aktion ist.
Während ein delegierter OpenClaw-Lauf aktiv ist, werden neue Discord-Voice-Transkripte als Live-Laufsteuerung behandelt, bevor ein weiterer Agent-Turn gestartet wird. Formulierungen wie „status“, „cancel that“, „use the smaller fix“ oder „when you're done also check tests“ werden als Status-, Abbruch-, Steuerungs- oder Follow-up-Eingabe für die aktive Sitzung klassifiziert. Status, Abbruch, akzeptierte Steuerung und Follow-up-Ergebnisse werden in den Sprachkanal zurückgesprochen, damit der Anrufer weiß, ob OpenClaw die Anfrage verarbeitet hat.
Nützliche Zielformen:
target: "channel:123456789012345678"routet über eine Discord-Textkanalsitzung.target: "123456789012345678"wird als Kanalziel behandelt.target: "dm:123456789012345678"odertarget: "user:123456789012345678"routet über diese Direktnachrichtensitzung.
Echo-lastiges OpenAI Realtime-Beispiel:
{ channels: { discord: { voice: { enabled: true, mode: "bidi", model: "openai/gpt-5.5", realtime: { provider: "openai", model: "gpt-realtime-2", speakerVoice: "cedar", bargeIn: true, minBargeInAudioEndMs: 500, consultPolicy: "always", providers: { openai: { interruptResponseOnInputAudio: false, }, }, }, }, }, },}Verwenden Sie dies, wenn das Modell seine eigene Discord-Wiedergabe über ein offenes Mikrofon hört, Sie es aber dennoch durch Sprechen unterbrechen möchten. OpenClaw verhindert, dass OpenAI bei rohem Eingabeaudio automatisch unterbricht, während bargeIn: true zulässt, dass Discord-Sprecherstart-Ereignisse und bereits aktives Sprecher-Audio aktive Echtzeitantworten abbrechen, bevor der nächste erfasste Turn OpenAI erreicht. Sehr frühe Barge-in-Signale mit audioEndMs unter minBargeInAudioEndMs werden als wahrscheinliches Echo/Rauschen behandelt und ignoriert, damit das Modell nicht beim ersten Wiedergabeframe abbricht.
Erwartete Voice-Protokolle:
- Beim Beitritt:
discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=... - Beim Echtzeitstart:
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=...unddiscord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=... - Bei übersprungener veralteter Sprache:
discord voice: realtime forced agent consult skipped reason=incomplete-transcript ...oderreason=non-actionable-closing ... - Beim Abschluss der Echtzeitantwort:
discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=... - Beim Wiedergabestopp/-Reset:
discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=... - Bei Echtzeit-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 vondiscord voice: realtime exact speech dequeued reason=player-idle ... - Bei Barge-in-Erkennung:
discord voice: realtime barge-in detected source=speaker-start ...oderdiscord voice: realtime barge-in detected source=active-speaker-audio ..., gefolgt vondiscord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=... - Bei Echtzeitunterbrechung:
discord voice: realtime model interrupt requested client:response.cancel reason=barge-in, gefolgt von entwederdiscord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=...oderdiscord 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 Leerlaufwiedergabe:
discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0
Um abgeschnittenes Audio zu debuggen, lesen Sie die Echtzeit-Voice-Protokolle als Zeitleiste:
realtime audio playback startedbedeutet, dass Discord mit der Wiedergabe von Assistenten-Audio begonnen hat. Die Bridge beginnt ab diesem Punkt, Assistenten-Ausgabe-Chunks, Discord-PCM-Bytes, Provider-Echtzeit-Bytes und synthetisierte Audiodauer zu zählen.realtime speaker turn openedmarkiert, dass ein Discord-Sprecher aktiv wird. Wenn die Wiedergabe bereits aktiv ist undbargeInaktiviert ist, kann daraufbarge-in detected source=speaker-startfolgen.realtime input audio startedmarkiert den ersten tatsächlichen Audioframe, der für diesen Sprecher-Turn empfangen wurde.outputActive=trueoder einoutputAudioMsungleich null bedeutet hier, dass das Mikrofon Eingabe sendet, während die Assistenten-Wiedergabe noch aktiv ist.barge-in detected source=active-speaker-audiobedeutet, dass OpenClaw Live-Sprecher-Audio gesehen hat, während Assistenten-Wiedergabe aktiv war. Dies ist nützlich, um eine echte Unterbrechung von einem Discord-Sprecherstart-Ereignis ohne nützliches Audio zu unterscheiden.barge-in requested reason=...bedeutet, dass OpenClaw den Echtzeit-Provider gebeten hat, die aktive Antwort abzubrechen oder zu kürzen. Es enthältoutputAudioMs,outputActiveundplaybackChunks, damit Sie sehen können, wie viel Assistenten-Audio vor der Unterbrechung tatsächlich abgespielt wurde.realtime audio playback stopped reason=...ist der lokale Discord-Wiedergabe-Resetpunkt. Der Grund sagt, wer die Wiedergabe gestoppt hat:barge-in,player-idle,provider-clear-audio,forced-agent-consult,stream-closeodersession-close.realtime speaker turn closedfasst den erfassten Eingabe-Turn zusammen.chunks=0oderhasAudio=falsebedeutet, dass der Sprecher-Turn geöffnet wurde, aber kein nutzbares Audio die Echtzeit-Bridge erreicht hat.interruptedPlayback=truebedeutet, dass sich dieser Eingabe-Turn mit Assistentenausgabe überschnitten und Barge-in-Logik ausgelöst hat.
Nützliche Felder:
outputAudioMs: Assistenten-Audiodauer, die der Echtzeit-Provider vor der Protokollzeile erzeugt hat.audioMs: Assistenten-Audiodauer, die OpenClaw gezählt hat, bevor die Wiedergabe gestoppt wurde.elapsedMs: Wanduhrzeit zwischen Öffnen und Schließen des Wiedergabestreams 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 Echtzeit-Provider gesendet oder von dort empfangen wurden.playbackChunks: Assistenten-Audio-Chunks, die für die aktive Antwort an Discord weitergeleitet wurden.sinceLastAudioMs: Abstand zwischen dem letzten erfassten Sprecher-Audioframe und dem Schließen des Sprecher-Turns.
Häufige Muster:
- Sofortiger Abbruch mit
source=active-speaker-audio, kleinemoutputAudioMsund demselben Benutzer in der Nähe deutet meist darauf hin, dass Lautsprecher-Echo ins Mikrofon gelangt. Erhöhen Sievoice.realtime.minBargeInAudioEndMs, verringern Sie die Lautsprecherlautstärke, verwenden Sie Kopfhörer oder setzen Sievoice.realtime.providers.openai.interruptResponseOnInputAudio: false. source=speaker-startgefolgt vonspeaker turn closed ... hasAudio=falsebedeutet, 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-closeohne nahes Barge-in oderprovider-clear-audiobedeutet, dass der lokale Discord-Wiedergabestream unerwartet beendet wurde. Prüfen Sie die vorhergehenden Provider- und Discord-Player-Protokolle.capture ignored during playback (barge-in disabled)bedeutet, dass OpenClaw Eingabe absichtlich verworfen hat, während Assistenten-Audio aktiv war. Aktivieren Sievoice.realtime.bargeIn, wenn Sprache die Wiedergabe unterbrechen soll.barge-in ignored ... outputActive=falsebedeutet, 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 Echtzeit-Provider-Authentifizierung für voice.realtime.providers oder die normale Auth-Konfiguration des Providers.
Sprachnachrichten
Discord-Sprachnachrichten zeigen eine Wellenformvorschau und erfordern OGG/Opus-Audio. OpenClaw erzeugt 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 Textinhalte 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
Nicht zulässige Intents verwendet oder Bot sieht keine Guild-Nachrichten
- Message Content Intent aktivieren
- Server Members Intent aktivieren, wenn Sie von Benutzer-/Mitgliederauflösung abhängen
- Gateway nach Änderungen an Intents neu starten
Guild-Nachrichten unerwartet blockiert
groupPolicyprüfen- Guild-Allowlist unter
channels.discord.guildsprüfen - wenn eine Guild-
channels-Map vorhanden ist, sind nur aufgelistete Kanäle erlaubt requireMention-Verhalten und Mention-Muster prüfen
Nützliche Prüfungen:
openclaw doctoropenclaw channels status --probeopenclaw logs --followMention nicht erforderlich, aber trotzdem blockiert
Häufige Ursachen:
groupPolicy="allowlist"ohne passende Guild-/Kanal-AllowlistrequireMentionam falschen Ort konfiguriert (muss unterchannels.discord.guildsoder dem Kanaleintrag stehen)- Absender durch Guild-/Kanal-
users-Allowlist blockiert
Lang laufende Discord-Turns oder doppelte Antworten
Typische Logs:
Slow listener detected ...stuck session: sessionKey=agent:...:discord:... state=processing ...
Discord-Gateway-Warteschlangenoptionen:
- Einzelkonto:
channels.discord.eventQueue.listenerTimeout - Mehrere Konten:
channels.discord.accounts.<accountId>.eventQueue.listenerTimeout - dies steuert nur Listener-Arbeit des Discord-Gateways, nicht die Lebensdauer eines Agent-Turns
Discord wendet kein kanaleigenes Timeout auf eingereihte Agent-Turns an. Message-Listener übergeben sofort, und eingereihte Discord-Läufe behalten die Reihenfolge pro Sitzung bei, bis der Sitzungs-/Tool-/Runtime-Lebenszyklus die Arbeit abschließt oder abbricht.
{channels: {discord: { accounts: { default: { eventQueue: { listenerTimeout: 120000, }, }, },},},}Timeout-Warnungen bei Gateway-Metadatenabfrage
OpenClaw ruft Discord-/gateway/bot-Metadaten vor dem Verbinden ab. Vorübergehende Fehler fallen auf Discords Standard-Gateway-URL zurück und werden in Logs ratenbegrenzt.
Metadaten-Timeout-Optionen:
- Einzelkonto:
channels.discord.gatewayInfoTimeoutMs - Mehrere Konten:
channels.discord.accounts.<accountId>.gatewayInfoTimeoutMs - Env-Fallback, wenn die Konfiguration nicht gesetzt ist:
OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS - Standard:
30000(30 Sekunden), Maximum:120000
Gateway-READY-Timeout-Neustarts
OpenClaw wartet während des Starts und nach Runtime-Reconnects auf Discords Gateway-READY-Ereignis. Setups mit mehreren Konten und gestaffeltem Start können ein längeres READY-Startfenster als den Standard benötigen.
READY-Timeout-Optionen:
- Start Einzelkonto:
channels.discord.gatewayReadyTimeoutMs - Start mehrere Konten:
channels.discord.accounts.<accountId>.gatewayReadyTimeoutMs - Start-Env-Fallback, wenn die Konfiguration nicht gesetzt ist:
OPENCLAW_DISCORD_READY_TIMEOUT_MS - Startstandard:
15000(15 Sekunden), Maximum:120000 - Runtime Einzelkonto:
channels.discord.gatewayRuntimeReadyTimeoutMs - Runtime mehrere Konten:
channels.discord.accounts.<accountId>.gatewayRuntimeReadyTimeoutMs - Runtime-Env-Fallback, wenn die Konfiguration nicht gesetzt ist:
OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS - Runtime-Standard:
30000(30 Sekunden), Maximum:120000
Abweichungen bei Berechtigungsprüfung
Berechtigungsprüfungen von channels status --probe funktionieren nur für numerische Kanal-IDs.
Wenn Sie Slug-Schlüssel verwenden, kann Runtime-Abgleich weiterhin funktionieren, aber die Prüfung kann Berechtigungen nicht vollständig verifizieren.
DM- und Pairing-Probleme
- DM deaktiviert:
channels.discord.dm.enabled=false - DM-Richtlinie deaktiviert:
channels.discord.dmPolicy="disabled"(Legacy:channels.discord.dm.policy) - Pairing-Genehmigung im
pairing-Modus ausstehend
Bot-zu-Bot-Schleifen
Standardmäßig werden von Bots verfasste Nachrichten ignoriert.
Wenn Sie channels.discord.allowBots=true setzen, verwenden Sie strikte Mention- und Allowlist-Regeln, um Schleifenverhalten zu vermeiden.
Bevorzugen Sie channels.discord.allowBots="mentions", um nur Bot-Nachrichten zu akzeptieren, die den Bot erwähnen.
OpenClaw liefert außerdem gemeinsamen Bot-Schleifenschutz mit. Immer wenn allowBots von Bots verfasste Nachrichten bis zum Dispatch gelangen lässt, ordnet Discord das eingehende Ereignis (account, channel, bot pair)-Fakten zu, und der generische Paar-Wächter unterdrückt das Paar, nachdem es das konfigurierte Ereignisbudget überschreitet. Der Wächter verhindert ausufernde Zwei-Bot-Schleifen, die zuvor durch Discord-Ratenlimits gestoppt werden mussten; er betrifft keine Ein-Bot-Deployments oder einmaligen Bot-Antworten, die unter dem Budget bleiben.
Standardeinstellungen (aktiv, wenn allowBots gesetzt ist):
maxEventsPerWindow: 20-- Bot-Paar kann innerhalb des gleitenden Fensters 20 Nachrichten austauschenwindowSeconds: 60-- Länge des gleitenden FensterscooldownSeconds: 60-- sobald das Budget ausgelöst wird, wird jede zusätzliche Bot-zu-Bot-Nachricht in beide Richtungen für eine Minute verworfen
Konfigurieren Sie den gemeinsamen Standard einmal unter channels.defaults.botLoopProtection und überschreiben Sie dann Discord, wenn ein legitimer Workflow mehr Spielraum benötigt. Die Priorität ist:
channels.discord.accounts.<account>.botLoopProtectionchannels.discord.botLoopProtectionchannels.defaults.botLoopProtection- eingebaute Standards
Discord verwendet die generischen Schlüssel maxEventsPerWindow, windowSeconds und cooldownSeconds.
{channels: {defaults: { botLoopProtection: { maxEventsPerWindow: 20, windowSeconds: 60, cooldownSeconds: 60, },},discord: { // Optional Discord-wide override. Account blocks override individual // fields and inherit omitted fields from here. botLoopProtection: { maxEventsPerWindow: 4, }, accounts: { mantis: { // Mantis listens to other bots only when they mention her. allowBots: "mentions", }, molty: { // Molty listens to all bot-authored Discord messages. allowBots: true, mentionAliases: { // Lets Molty write a Mantis Discord mention with the configured user id. Mantis: "MANTIS_DISCORD_USER_ID", }, botLoopProtection: { // Allow up to five messages per minute before suppressing the pair. maxEventsPerWindow: 5, windowSeconds: 60, cooldownSeconds: 90, }, }, },},},}Voice-STT-Ausfälle mit DecryptionFailed(...)
- halten Sie OpenClaw aktuell (
openclaw update), damit die Wiederherstellungslogik für Discord-Voice-Empfang vorhanden ist - bestätigen Sie
channels.discord.voice.daveEncryption=true(Standard) - beginnen Sie mit
channels.discord.voice.decryptionFailureTolerance=24(Upstream-Standard) und passen Sie nur bei Bedarf an - beobachten Sie Logs auf:
discord voice: DAVE decrypt failures detecteddiscord voice: repeated decrypt failures; attempting rejoin
- wenn Fehler nach automatischem Rejoin weiterhin auftreten, sammeln Sie Logs und vergleichen Sie sie mit der Upstream-DAVE-Empfangshistorie in discord.js #11419 und discord.js #11449
Konfigurationsreferenz
Primäre Referenz: Konfigurationsreferenz - Discord.
Aussagekräftige Discord-Felder
- Start/Auth:
enabled,token,accounts.*,allowBots - Richtlinie:
groupPolicy,dm.*,guilds.*,guilds.*.channels.* - Befehl:
commands.native,commands.useAccessGroups,configWrites,slashCommand.* - Ereigniswarteschlange:
eventQueue.listenerTimeout(Listener-Budget),eventQueue.maxQueueSize,eventQueue.maxConcurrency - Gateway:
gatewayInfoTimeoutMs,gatewayReadyTimeoutMs,gatewayRuntimeReadyTimeoutMs - Antwort/Verlauf:
replyToMode,historyLimit,dmHistoryLimit,dms.*.historyLimit - Zustellung:
textChunkLimit,chunkMode,maxLinesPerMessage - Streaming:
streaming(Legacy-Alias:streamMode),streaming.preview.toolProgress,draftChunk,blockStreaming,blockStreamingCoalesce - Medien/Wiederholung:
mediaMaxMb(begrenzt ausgehende Discord-Uploads, Standard100MB),retry - Aktionen:
actions.* - Präsenz:
activity,status,activityType,activityUrl - UI:
ui.components.accentColor - Funktionen:
threadBindings, oberste Ebenebindings[](type: "acp"),pluralkit,execApprovals,intents,agentComponents.enabled,agentComponents.ttlMs,heartbeat,responsePrefix
Sicherheit und Betrieb
- Behandeln Sie Bot-Token als Geheimnisse (
DISCORD_BOT_TOKENin überwachten Umgebungen bevorzugt). - Gewähren Sie Discord-Berechtigungen nach dem Prinzip der geringsten Rechte.
- Wenn Befehls-Deployment/-Status veraltet ist, starten Sie das Gateway neu und prüfen Sie erneut mit
openclaw channels status --probe.
Verwandt
Koppeln Sie einen Discord-Benutzer mit dem Gateway.
Gruppenchat- und Allowlist-Verhalten.
Eingehende Nachrichten an Agenten weiterleiten.
Bedrohungsmodell und Härtung.
Guilds und Kanäle Agenten zuordnen.
Natives Befehlsverhalten.