Zum Hauptinhalt springen

​
Discord (Bot API)

Status: bereit für DMs und Serverkanäle über das offizielle Discord-Gateway.

Kopplung

Discord-DMs verwenden standardmäßig den Kopplungsmodus.

Slash-Befehle

Natives Befehlsverhalten und Befehlskatalog.

Fehlerbehebung für Kanäle

Kanalübergreifende Diagnose- und Reparaturabläufe.

​
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).
1

Eine Discord-Anwendung und einen Bot erstellen

Gehen Sie zum Discord Developer Portal und klicken Sie auf New Application. Geben Sie ihr einen Namen wie „OpenClaw“.Klicken Sie in der Seitenleiste auf Bot. Setzen Sie den Username auf den Namen, den Ihr OpenClaw-Agent tragen soll.
2

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 Name-zu-ID-Abgleich)
  • Presence Intent (optional; nur für Präsenzaktualisierungen erforderlich)
3

Ihren Bot-Token kopieren

Scrollen Sie auf der Seite Bot wieder nach oben und klicken Sie auf Reset Token.
Trotz des Namens wird dadurch Ihr erster Token erzeugt — es wird nichts „zurückgesetzt“.
Kopieren Sie den Token und speichern Sie ihn irgendwo. Dies ist Ihr Bot Token, und Sie werden ihn gleich benötigen.
4

Eine Einladungs-URL erzeugen und den Bot zu Ihrem Server hinzufügen

Klicken Sie in der Seitenleiste auf OAuth2. Sie erzeugen 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:
  • bot
  • applications.commands
Darunter wird ein Abschnitt Bot Permissions angezeigt. Aktivieren Sie:
  • View Channels
  • Send Messages
  • Read Message History
  • Embed Links
  • Attach Files
  • Add Reactions (optional)
Kopieren Sie die unten erzeugte URL, 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.
5

Developer Mode aktivieren und Ihre IDs erfassen

Zurück in der Discord-App müssen Sie den Developer Mode aktivieren, damit Sie interne IDs kopieren können.
  1. Klicken Sie auf User Settings (Zahnradsymbol neben Ihrem Avatar) → Advanced → aktivieren Sie Developer Mode
  2. Rechtsklick auf Ihr Serversymbol in der Seitenleiste → Copy Server ID
  3. Rechtsklick 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.
6

DMs von Servermitgliedern erlauben

Damit die Kopplung funktioniert, muss Discord zulassen, dass Ihr Bot Ihnen eine DM senden darf. Rechtsklick 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 Serverkanäle verwenden möchten, können Sie DMs nach der Kopplung deaktivieren.
7

Ihren Bot-Token sicher setzen (nicht im Chat senden)

Ihr Discord-Bot-Token ist ein Geheimnis (wie ein Passwort). Setzen Sie ihn auf dem Rechner, auf dem OpenClaw ausgeführt wird, bevor Sie Ihrem Agenten schreiben.
export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set channels.discord.enabled true --strict-json
openclaw gateway
Wenn OpenClaw bereits als Hintergrunddienst läuft, starten Sie ihn über die OpenClaw-Mac-App neu oder indem Sie den Prozess openclaw gateway run stoppen und erneut starten.
8

OpenClaw konfigurieren und koppeln

Chatten Sie mit Ihrem OpenClaw-Agenten auf einem bestehenden Kanal (z. B. Telegram) und teilen Sie es ihm mit. Wenn Discord Ihr erster Kanal ist, verwenden Sie stattdessen die Registerkarte CLI / config.
„Ich habe meinen Discord-Bot-Token bereits in der Konfiguration gesetzt. Bitte schließe die Discord-Einrichtung mit der User ID <user_id> und der Server ID <server_id> ab.“
9

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.
Senden Sie den Kopplungscode auf Ihrem bestehenden Kanal an Ihren Agenten:
„Genehmige diesen Discord-Kopplungscode: <CODE>“
Kopplungscodes laufen nach 1 Stunde ab.Sie sollten jetzt per DM in Discord mit Ihrem Agenten chatten können.
Die Token-Auflösung ist kontobewusst. Token-Werte aus der Konfiguration haben Vorrang vor dem Env-Fallback. DISCORD_BOT_TOKEN wird nur für das Standardkonto verwendet. Für erweiterte ausgehende Aufrufe (message-Tool/Kanalaktionen) wird ein expliziter aufrufbezogener token für diesen Aufruf verwendet. Dies gilt für Sende- sowie Lese-/Probe-Aktionen (zum Beispiel read/search/fetch/thread/pins/permissions). Kontorichtlinien und Wiederholungseinstellungen stammen weiterhin aus dem ausgewählten Konto im aktiven Runtime-Snapshot.

​
Empfohlen: Einen Server-Workspace einrichten

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

Ihren Server zur Server-Allowlist hinzufügen

Dadurch kann Ihr Agent in jedem Kanal Ihres Servers antworten, nicht nur in DMs.
„Füge meine Discord Server ID <server_id> zur Server-Allowlist hinzu“
2

Antworten ohne @Erwähnung erlauben

Standardmäßig antwortet Ihr Agent in Serverkanälen nur, wenn er mit @ erwähnt wird. Für einen privaten Server möchten Sie wahrscheinlich, dass er auf jede Nachricht antwortet.
„Erlaube meinem Agenten, auf diesem Server zu antworten, ohne dass er mit @ erwähnt werden muss“
3

Speichernutzung in Serverkanälen planen

Standardmäßig wird Langzeitspeicher (MEMORY.md) nur in DM-Sitzungen geladen. In Serverkanälen wird MEMORY.md nicht automatisch geladen.
„Wenn ich in Discord-Kanälen Fragen stelle, verwende memory_search oder memory_get, wenn du Langzeitkontext aus MEMORY.md benötigst.“
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 — so können Sie #coding, #home, #research oder was auch immer zu Ihrem Workflow passt einrichten.

​
Laufzeitmodell

  • Das Gateway besitzt die Discord-Verbindung.
  • Die Antwortweiterleitung ist deterministisch: Eingehende Discord-Antworten gehen zurück an Discord.
  • Standardmäßig (session.dmScope=main) teilen sich Direktchats die Hauptsitzung des Agenten (agent:main:main).
  • Serverkanä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 weiterhin CommandTargetSessionKey zur weitergeleiteten Konversationssitzung mit.

​
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-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 direkt einen Thread zu erstellen. Übergeben Sie für Forumskanäle 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 an den Thread selbst (channel:<threadId>).

​
Interaktive Komponenten

OpenClaw unterstützt Discord-Komponenten-v2-Container für Agentennachrichten. Verwenden Sie das message-Tool mit einer components-Payload. Interaktionsergebnisse werden als normale eingehende Nachrichten zurück an den Agenten geleitet und folgen den vorhandenen Discord-Einstellungen für replyToMode. 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, um Buttons, Auswahlen und Formulare mehrfach verwendbar zu machen, bis sie ablaufen. Um einzuschränken, wer auf einen Button klicken kann, setzen Sie allowedUsers auf diesem Button (Discord-Benutzer-IDs, Tags oder *). Wenn dies konfiguriert ist, erhalten nicht passende Benutzer eine ephemere Ablehnung. Die Slash-Befehle /model und /models öffnen einen interaktiven Modellauswähler mit Dropdowns für Provider und Modell sowie einem Schritt zum Absenden. Die Antwort des Auswählers ist ephemer, und nur der aufrufende Benutzer kann sie verwenden. Dateianhänge:
  • file-Blöcke müssen auf eine Anhangsreferenz zeigen (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 mit der Anhangsreferenz übereinstimmen 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

channels.discord.dmPolicy steuert den DM-Zugriff (veraltet: channels.discord.dm.policy):
  • pairing (Standard)
  • allowlist
  • open (erfordert, dass channels.discord.allowFrom "*" enthält; veraltet: channels.discord.dm.allowFrom)
  • 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.allowFrom gilt nur für das default-Konto.
  • Benannte Konten erben channels.discord.allowFrom, wenn ihr eigenes allowFrom nicht gesetzt ist.
  • Benannte Konten erben nicht channels.discord.accounts.default.allowFrom.
DM-Zielformat für Zustellung:
  • user:<id>
  • <@id>-Erwähnung
Reine numerische IDs sind mehrdeutig und werden abgelehnt, sofern nicht explizit eine Art von Benutzer-/Kanalziel angegeben wird.

​
Rollenbasiertes Agenten-Routing

Verwenden Sie bindings[].match.roles, um Discord-Servermitglieder anhand ihrer Rollen-ID an unterschiedliche Agenten weiterzuleiten. Rollenbasierte Bindings akzeptieren nur Rollen-IDs und werden nach Peer- oder Parent-Peer-Bindings und vor rein serverbasierten 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",
      },
    },
  ],
}

​
Einrichtung im Developer Portal

  1. Discord Developer Portal -> Applications -> New Application
  2. Bot -> Add Bot
  3. Bot-Token kopieren
Aktivieren Sie in Bot -> Privileged Gateway Intents:
  • Message Content Intent
  • Server Members Intent (empfohlen)
Presence Intent ist optional und nur erforderlich, wenn Sie Präsenzaktualisierungen empfangen möchten. Das Setzen der Bot-Präsenz (setPresence) erfordert nicht, dass Präsenzaktualisierungen für Mitglieder aktiviert sind.
OAuth-URL-Generator:
  • Scopes: bot, applications.commands
Typische grundlegende Berechtigungen:
  • View Channels
  • Send Messages
  • Read Message History
  • Embed Links
  • Attach Files
  • Add Reactions (optional)
Vermeiden Sie Administrator, sofern es nicht ausdrücklich benötigt wird.
Aktivieren Sie den Discord Developer Mode und kopieren Sie dann:
  • Server-ID
  • Kanal-ID
  • Benutzer-ID
Bevorzugen Sie numerische IDs in der OpenClaw-Konfiguration für zuverlässige Audits und Probes.

​
Native Befehle und Befehlsauthentifizierung

  • commands.native ist standardmäßig "auto" und für Discord aktiviert.
  • Kanalbezogene Überschreibung: channels.discord.commands.native.
  • commands.native=false löscht explizit zuvor registrierte native Discord-Befehle.
  • Die Authentifizierung nativer Befehle verwendet dieselben Discord-Allowlists/-Richtlinien wie die normale Nachrichtenverarbeitung.
  • Befehle können in der Discord-Benutzeroberfläche weiterhin für Benutzer sichtbar sein, die nicht autorisiert sind; die Ausführung erzwingt dennoch die OpenClaw-Authentifizierung und gibt „nicht autorisiert“ zurück.
Siehe Slash commands für Befehlskatalog und Verhalten. Standard-Slash-Befehlseinstellungen:
  • ephemeral: true

​
Funktionsdetails

Discord unterstützt Antwort-Tags in der Agentenausgabe:
  • [[reply_to_current]]
  • [[reply_to:<id>]]
Gesteuert durch channels.discord.replyToMode:
  • off (Standard)
  • first
  • all
  • batched
Hinweis: off deaktiviert implizites Reply-Threading. Explizite [[reply_to_*]]-Tags werden weiterhin berücksichtigt. first hängt die implizite native Antwortreferenz immer an die erste ausgehende Discord-Nachricht des Turns an. batched hängt Disords implizite native Antwortreferenz nur dann an, wenn der eingehende Turn ein entprelltes Batch aus mehreren Nachrichten war. Das ist nützlich, wenn Sie native Antworten hauptsächlich für mehrdeutige, stoßweise Chats möchten, nicht für jeden einzelnen Turn mit nur einer Nachricht.Nachrichten-IDs werden im Kontext/Verlauf offengelegt, sodass Agenten gezielt bestimmte Nachrichten adressieren können.
OpenClaw kann Antwortentwürfe streamen, indem eine temporäre Nachricht gesendet und beim Eintreffen von Text bearbeitet wird.
  • channels.discord.streaming steuert Vorschau-Streaming (off | partial | block | progress, Standard: off).
  • Der Standard bleibt off, weil Discord-Vorschau-Bearbeitungen schnell an Ratenlimits stoßen können, insbesondere wenn mehrere Bots oder Gateways dasselbe Konto oder denselben Serververkehr teilen.
  • progress wird zur kanalübergreifenden Konsistenz akzeptiert und in Discord auf partial abgebildet.
  • channels.discord.streamMode ist ein veralteter Alias und wird automatisch migriert.
  • partial bearbeitet eine einzelne Vorschau-Nachricht, wenn Tokens eintreffen.
  • block sendet Entwurfsblöcke in Chunk-Größe (verwenden Sie draftChunk, um Größe und Trennpunkte abzustimmen).
Beispiel:
{
  channels: {
    discord: {
      streaming: "partial",
    },
  },
}
Standardwerte für Chunking im Modus block (begrenzt durch channels.discord.textChunkLimit):
{
  channels: {
    discord: {
      streaming: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph",
      },
    },
  },
}
Vorschau-Streaming ist nur für Text verfügbar; Medienantworten fallen auf normale Zustellung zurück.Hinweis: Vorschau-Streaming ist vom Block-Streaming getrennt. Wenn Block-Streaming für Discord explizit aktiviert ist, überspringt OpenClaw den Vorschau-Stream, um doppeltes Streaming zu vermeiden.
Verlaufskontext in Servern:
  • channels.discord.historyLimit Standard 20
  • Fallback: messages.groupChat.historyLimit
  • 0 deaktiviert
Steuerelemente für DM-Verlauf:
  • channels.discord.dmHistoryLimit
  • channels.discord.dms["<user_id>"].historyLimit
Thread-Verhalten:
  • Discord-Threads werden als Kanalsitzungen weitergeleitet
  • Parent-Thread-Metadaten können für eine Verknüpfung zur übergeordneten Sitzung verwendet werden
  • Thread-Konfiguration erbt die Konfiguration des Parent-Kanals, sofern kein threadspezifischer Eintrag vorhanden ist
Kanalthemen werden als nicht vertrauenswürdiger Kontext injiziert (nicht als System-Prompt). Antwort- und Kontext aus zitierten Nachrichten bleibt derzeit wie empfangen erhalten. Discord-Allowlists steuern in erster Linie, wer den Agenten auslösen kann, und sind keine vollständige Redaktionsgrenze für ergänzenden Kontext.
Discord kann einen Thread an ein Sitzungsziel binden, sodass nachfolgende Nachrichten in diesem Thread weiterhin an dieselbe Sitzung weitergeleitet werden (einschließlich Subagent-Sitzungen).Befehle:
  • /focus <target> bindet den aktuellen/neuen Thread an ein Subagent-/Sitzungsziel
  • /unfocus entfernt die aktuelle Thread-Bindung
  • /agents zeigt aktive Läufe und den Bindungsstatus
  • /session idle <duration|off> prüft/aktualisiert das automatische Lösen des Fokus bei Inaktivität für fokussierte Bindungen
  • /session max-age <duration|off> prüft/aktualisiert das harte Maximalalter für fokussierte Bindungen
Konfiguration:
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // Opt-in
      },
    },
  },
}
Hinweise:
  • session.threadBindings.* setzt globale Standardwerte.
  • channels.discord.threadBindings.* überschreibt das Discord-Verhalten.
  • spawnSubagentSessions muss true sein, damit Threads für sessions_spawn({ thread: true }) automatisch erstellt/gebunden werden.
  • spawnAcpSessions muss true sein, damit Threads für ACP automatisch erstellt/gebunden werden (/acp spawn ... --thread ... oder sessions_spawn({ runtime: "acp", thread: true })).
  • Wenn Thread-Bindungen für ein Konto deaktiviert sind, sind /focus und verwandte Operationen für Thread-Bindungen nicht verfügbar.
Siehe Sub-agents, ACP Agents und Configuration Reference.
Für stabile „always-on“-ACP-Workspaces konfigurieren Sie ACP-Bindungen mit Typ auf oberster Ebene, die auf Discord-Konversationen zielen.Konfigurationspfad:
  • bindings[] mit type: "acp" und match.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 here bindet den aktuellen Discord-Kanal oder Thread direkt vor Ort und hält zukünftige Nachrichten an dieselbe ACP-Sitzung gebunden.
  • Das kann weiterhin bedeuten: „Eine frische Codex-ACP-Sitzung starten“, aber es wird dadurch nicht von selbst ein neuer Discord-Thread erstellt. Der bestehende Kanal bleibt die Chat-Oberfläche.
  • Codex kann weiterhin in seinem eigenen cwd oder Backend-Workspace auf dem Datenträger laufen. Dieser Workspace ist Laufzeitzustand, kein Discord-Thread.
  • Thread-Nachrichten können die ACP-Bindung des Parent-Kanals erben.
  • In einem gebundenen Kanal oder Thread setzen /new und /reset dieselbe ACP-Sitzung direkt vor Ort zurück.
  • Temporäre Thread-Bindungen funktionieren weiterhin und können die Zielauflösung überschreiben, solange sie aktiv sind.
  • spawnAcpSessions ist nur erforderlich, wenn OpenClaw einen untergeordneten Thread über --thread auto|here erstellen/binden muss. Es ist nicht erforderlich für /acp spawn ... --bind here im aktuellen Kanal.
Siehe ACP Agents für Details zum Bindungsverhalten.
Modus für Reaktionsbenachrichtigungen pro Server:
  • off
  • own (Standard)
  • all
  • allowlist (verwendet guilds.<id>.users)
Reaktionsereignisse werden in Systemereignisse umgewandelt und an die weitergeleitete Discord-Sitzung angehängt.
ackReaction sendet ein Bestätigungs-Emoji, während OpenClaw eine eingehende Nachricht verarbeitet.Auflösungsreihenfolge:
  • channels.discord.accounts.<accountId>.ackReaction
  • channels.discord.ackReaction
  • messages.ackReaction
  • Emoji-Fallback der Agentenidentität (agents.list[].identity.emoji, sonst ”👀”)
Hinweise:
  • Discord akzeptiert Unicode-Emojis oder benutzerdefinierte Emoji-Namen.
  • Verwenden Sie "", um die Reaktion für einen Kanal oder ein Konto zu deaktivieren.
Durch Kanäle initiierte Konfigurationsschreibvorgänge sind standardmäßig aktiviert.Dies betrifft Abläufe für /config set|unset (wenn Befehlsfunktionen aktiviert sind).Deaktivieren:
{
  channels: {
    discord: {
      configWrites: false,
    },
  },
}
Leiten Sie WebSocket-Datenverkehr des Discord-Gateways und REST-Abfragen beim Start (Anwendungs-ID + Allowlist-Auflösung) mit channels.discord.proxy über einen HTTP(S)-Proxy.
{
  channels: {
    discord: {
      proxy: "http://proxy.example:8080",
    },
  },
}
Überschreibung pro Konto:
{
  channels: {
    discord: {
      accounts: {
        primary: {
          proxy: "http://proxy.example:8080",
        },
      },
    },
  },
}
Aktivieren Sie die PluralKit-Auflösung, um weitergeleitete Nachrichten auf die Identität eines Systemmitglieds abzubilden:
{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // optional; für private Systeme erforderlich
      },
    },
  },
}
Hinweise:
  • Allowlists können pk:<memberId> verwenden
  • Anzeigenamen von Mitgliedern werden nur dann nach Name/Slug abgeglichen, wenn channels.discord.dangerouslyAllowNameMatching: true gesetzt ist
  • Abfragen verwenden die ursprüngliche Nachrichten-ID und sind auf ein Zeitfenster begrenzt
  • wenn die Abfrage fehlschlägt, werden weitergeleitete Nachrichten als Bot-Nachrichten behandelt und verworfen, sofern nicht allowBots=true
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 Standard-Aktivitä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: Playing
  • 1: Streaming (erfordert activityUrl)
  • 2: Listening
  • 3: Watching
  • 4: Custom (verwendet den Aktivitätstext als Statusstatus; Emoji ist optional)
  • 5: Competing
Beispiel für automatische Präsenz (Signal für Laufzeitzustand):
{
  channels: {
    discord: {
      autoPresence: {
        enabled: true,
        intervalMs: 30000,
        minUpdateIntervalMs: 15000,
        exhaustedText: "token exhausted",
      },
    },
  },
}
Die automatische Präsenz ordnet die Laufzeitverfügbarkeit dem Discord-Status zu: healthy => online, degraded oder unknown => idle, exhausted oder unavailable => dnd. Optionale Textüberschreibungen:
  • autoPresence.healthyText
  • autoPresence.degradedText
  • autoPresence.exhaustedText (unterstützt Platzhalter {reason})
Discord unterstützt Genehmigungsabläufe auf Button-Basis in DMs und kann optional Genehmigungsaufforderungen im auslösenden Kanal veröffentlichen.Konfigurationspfad:
  • channels.discord.execApprovals.enabled
  • channels.discord.execApprovals.approvers (optional; fällt nach Möglichkeit auf commands.ownerAllowFrom zurück)
  • channels.discord.execApprovals.target (dm | channel | both, Standard: dm)
  • agentFilter, sessionFilter, cleanupAfterResolve
Discord aktiviert native Exec-Genehmigungen 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 Exec-Genehmiger nicht aus kanalbezogenem allowFrom, veraltetem dm.allowFrom oder direktem defaultTo für Direktnachrichten ab. Setzen Sie enabled: false, um Discord explizit als nativen Genehmigungs-Client zu deaktivieren.Wenn target den Wert channel oder both hat, ist die Genehmigungsaufforderung im Kanal sichtbar. Nur aufgelöste Genehmiger können die Buttons verwenden; andere Benutzer erhalten eine ephemere Ablehnung. Genehmigungsaufforderungen enthalten den Befehlstext, daher sollten Sie die Zustellung im Kanal nur in vertrauenswürdigen Kanälen aktivieren. Wenn die Kanal-ID nicht aus dem Sitzungsschlüssel abgeleitet werden kann, verwendet OpenClaw stattdessen die Zustellung per DM.Discord rendert auch die gemeinsamen Genehmigungsbuttons, die von anderen Chat-Kanälen verwendet werden. Der native Discord-Adapter fügt hauptsächlich das DM-Routing für Genehmiger und die Verteilung an Kanäle hinzu. Wenn diese Buttons vorhanden sind, sind sie die primäre UX für Genehmigungen; OpenClaw sollte einen manuellen /approve-Befehl nur dann einschließen, wenn das Tool-Ergebnis angibt, dass Chat-Genehmigungen nicht verfügbar sind oder nur eine manuelle Genehmigung möglich ist.Die Gateway-Authentifizierung für diesen Handler verwendet denselben gemeinsamen Vertrag zur Anmeldedatenauflösung wie andere Gateway-Clients:
  • env-first-lokale Authentifizierung (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD dann gateway.auth.*)
  • im lokalen Modus kann gateway.remote.* nur dann als Fallback verwendet werden, wenn gateway.auth.* nicht gesetzt ist; konfigurierte, aber nicht aufgelöste lokale SecretRefs schlagen geschlossen fehl
  • Unterstützung für den Remote-Modus über gateway.remote.*, wenn zutreffend
  • URL-Überschreibungen sind Override-sicher: CLI-Überschreibungen verwenden keine impliziten Anmeldedaten wieder, und Env-Überschreibungen verwenden nur Env-Anmeldedaten
Verhalten bei der Genehmigungsauflösung:
  • Mit plugin: präfixierte IDs werden über plugin.approval.resolve aufgelöst.
  • Andere IDs werden über exec.approval.resolve aufgelöst.
  • Discord führt hier keinen zusätzlichen Exec-zu-Plugin-Fallback durch; das ID-Präfix entscheidet, welche Gateway-Methode aufgerufen wird.
Exec-Genehmigungen laufen standardmäßig nach 30 Minuten ab. Wenn Genehmigungen mit unbekannten Genehmigungs-IDs fehlschlagen, prüfen Sie die Auflösung der Genehmiger, die Aktivierung der Funktion und ob die zugestellte Art der Genehmigungs-ID zur ausstehenden Anfrage passt.Zugehörige Dokumentation: Exec approvals

​
Tools und Action Gates

Discord-Nachrichtenaktionen umfassen Messaging, Kanaladministration, Moderation, Präsenz und Metadatenaktionen. Zentrale Beispiele:
  • 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. Action Gates befinden sich unter channels.discord.actions.*. Standardverhalten der Gates:
Action groupStandard
reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissionsaktiviert
rolesdeaktiviert
moderationdeaktiviert
presencedeaktiviert

​
Components v2 UI

OpenClaw verwendet Discord components v2 für Exec-Genehmigungen und kanalübergreifende Markierungen. 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.accentColor setzt die Akzentfarbe, die von Discord-Komponentencontainern verwendet wird (hex).
  • Pro Konto mit channels.discord.accounts.<id>.ui.components.accentColor setzen.
  • embeds werden ignoriert, wenn components v2 vorhanden sind.
Beispiel: 
{
  channels: {
    discord: {
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
    },
  },
}

​
Sprachkanäle

OpenClaw kann Discord-Sprachkanälen für Echtzeitgespräche mit kontinuierlicher Interaktion beitreten. Dies ist von Anhängen mit Sprachnachrichten getrennt. Anforderungen:
  • Aktivieren Sie native Befehle (commands.native oder channels.discord.commands.native).
  • Konfigurieren Sie channels.discord.voice.
  • Der Bot benötigt die Berechtigungen Connect + Speak im Ziel-Sprachkanal.
Verwenden Sie den nur für Discord verfügbaren nativen Befehl /vc join|leave|status, um Sitzungen zu steuern. Der Befehl verwendet den Standard-Agenten des Kontos und folgt denselben Allowlist- und Gruppenrichtlinienregeln wie andere Discord-Befehle. Beispiel für automatischen Beitritt: 
{
  channels: {
    discord: {
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
    },
  },
}
Hinweise:
  • voice.tts überschreibt messages.tts nur für die Sprachausgabe.
  • Sprach-Transkript-Turns leiten den Eigentümerstatus aus Discord allowFrom (oder dm.allowFrom) ab; Sprecher ohne Eigentümerstatus können nicht auf Tools zugreifen, die nur Eigentümern vorbehalten sind (zum Beispiel gateway und cron).
  • Voice ist standardmäßig aktiviert; setzen Sie channels.discord.voice.enabled=false, um sie zu deaktivieren.
  • 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 nicht gesetzt sind.
  • OpenClaw überwacht außerdem Entschlüsselungsfehler beim Empfang und stellt sich nach wiederholten Fehlern in einem kurzen Zeitfenster automatisch wieder her, indem der Sprachkanal verlassen und erneut betreten wird.
  • Wenn Empfangslogs wiederholt DecryptionFailed(UnencryptedWhenPassthroughDisabled) anzeigen, könnte dies der Upstream-Receive-Bug von @discordjs/voice sein, der in discord.js #11419 verfolgt wird.

​
Sprachnachrichten

Discord-Sprachnachrichten zeigen eine Wellenformvorschau an und erfordern OGG/Opus-Audio plus Metadaten. OpenClaw erzeugt die Wellenform automatisch, benötigt aber ffmpeg und ffprobe, die auf dem Gateway-Host verfügbar sein müssen, um Audiodateien zu prüfen und zu konvertieren. Anforderungen und Einschränkungen:
  • Geben Sie einen lokalen Dateipfad an (URLs werden abgelehnt).
  • Lassen Sie Textinhalte weg (Discord erlaubt nicht Text + Sprachnachricht in derselben Payload).
  • Jedes Audioformat wird akzeptiert; OpenClaw konvertiert bei Bedarf in OGG/Opus.
Beispiel: 
message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)

​
Fehlerbehebung

  • Message Content Intent aktivieren
  • Server Members Intent aktivieren, wenn Sie von Benutzer-/Mitgliederauflösung abhängen
  • Gateway nach Änderung der Intents neu starten
  • groupPolicy prüfen
  • Server-Allowlist unter channels.discord.guilds prüfen
  • wenn eine channels-Zuordnung für den Server existiert, sind nur aufgelistete Kanäle erlaubt
  • Verhalten von requireMention und Erwähnungsmustern prüfen
Nützliche Prüfungen:
openclaw doctor
openclaw channels status --probe
openclaw logs --follow
Häufige Ursachen:
  • groupPolicy="allowlist" ohne passende Server-/Kanal-Allowlist
  • requireMention an der falschen Stelle konfiguriert (muss unter channels.discord.guilds oder im Kanaleintrag stehen)
  • Absender durch Server-/Kanal-users-Allowlist blockiert
Typische Logs:
  • Listener DiscordMessageListener timed out after 30000ms for event MESSAGE_CREATE
  • Slow listener detected ...
  • discord inbound worker timed out after ...
Regler für Listener-Budget:
  • Einzelkonto: channels.discord.eventQueue.listenerTimeout
  • mehrere Konten: channels.discord.accounts.<accountId>.eventQueue.listenerTimeout
Regler für Worker-Laufzeit-Timeout:
  • Einzelkonto: channels.discord.inboundWorker.runTimeoutMs
  • mehrere Konten: channels.discord.accounts.<accountId>.inboundWorker.runTimeoutMs
  • Standard: 1800000 (30 Minuten); setzen Sie 0, um zu deaktivieren
Empfohlene Baseline:
{
  channels: {
    discord: {
      accounts: {
        default: {
          eventQueue: {
            listenerTimeout: 120000,
          },
          inboundWorker: {
            runTimeoutMs: 1800000,
          },
        },
      },
    },
  },
}
Verwenden Sie eventQueue.listenerTimeout für langsame Listener-Einrichtung und inboundWorker.runTimeoutMs nur dann, wenn Sie ein separates Sicherheitsventil für in die Warteschlange gestellte Agenten-Turns möchten.
Berechtigungsprüfungen von channels status --probe funktionieren nur für numerische Kanal-IDs.Wenn Sie Slug-Schlüssel verwenden, kann das Runtime-Matching weiterhin funktionieren, aber die Probe kann die Berechtigungen nicht vollständig überprüfen.
  • DM deaktiviert: channels.discord.dm.enabled=false
  • DM-Richtlinie deaktiviert: channels.discord.dmPolicy="disabled" (veraltet: channels.discord.dm.policy)
  • im Modus pairing wird auf Genehmigung der Kopplung gewartet
Standardmäßig werden von Bots verfasste Nachrichten ignoriert.Wenn Sie channels.discord.allowBots=true setzen, verwenden Sie strenge Erwähnungs- und Allowlist-Regeln, um Schleifenverhalten zu vermeiden. Bevorzugen Sie channels.discord.allowBots="mentions", um nur Bot-Nachrichten zu akzeptieren, die den Bot erwähnen.
  • halten Sie OpenClaw aktuell (openclaw update), damit die Wiederherstellungslogik für den Empfang von Discord-Voice 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 die Logs auf:
    • discord voice: DAVE decrypt failures detected
    • discord voice: repeated decrypt failures; attempting rejoin
  • wenn die Fehler nach automatischem erneuten Beitritt weiterhin auftreten, sammeln Sie Logs und vergleichen Sie sie mit discord.js #11419

​
Verweise auf die Konfigurationsreferenz

Primäre Referenz: Signalstarke 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
  • Eingangs-Worker: inboundWorker.runTimeoutMs
  • Antwort/Verlauf: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
  • Zustellung: textChunkLimit, chunkMode, maxLinesPerMessage
  • Streaming: streaming (veralteter Alias: streamMode), draftChunk, blockStreaming, blockStreamingCoalesce
  • Medien/Wiederholung: mediaMaxMb, retry
    • mediaMaxMb begrenzt ausgehende Discord-Uploads (Standard: 100MB)
  • Aktionen: actions.*
  • Präsenz: activity, status, activityType, activityUrl
  • UI: ui.components.accentColor
  • Funktionen: threadBindings, oberstes bindings[] (type: "acp"), pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

​
Sicherheit und Betrieb

  • Behandeln Sie Bot-Tokens als Geheimnisse (DISCORD_BOT_TOKEN wird in überwachten Umgebungen bevorzugt).
  • Gewähren Sie Discord-Berechtigungen mit minimalen Rechten.
  • Wenn der Befehlsbereitstellungs-/Statuszustand veraltet ist, starten Sie das Gateway neu und prüfen Sie mit openclaw channels status --probe erneut.

​
Verwandt