Discord Bot Integration mit dem OpenClaw Gateway

Es ist frustrierend, wenn man eine einfache Discord-Integration bauen will, aber die meiste Zeit damit verbringt, Verbindungszustände zu debuggen oder Sessions manuell zu mappen. Man möchte eigentlich nur, dass der Bot Nachrichten korrekt empfängt und antwortet, ohne sich im Gateway-Management zu verlieren.

Hier erfährst du, wie du die Discord API effizient anbindest und die Session-Logik sauber hältst.

Voraussetzungen

Bevor du startest, stelle sicher, dass du Zugriff auf das Discord Developer Portal hast. Du benötigst:

• Eine Discord App mit einem aktiven Bot-Token.
• Aktivierte Message Content Intent.
• Aktivierte Server Members Intent (empfohlen für Name-zu-ID Lookups).

Schnellstart

In fünf Minuten ist dein Bot einsatzbereit. Folge diesen Schritten:

1. Bot erstellen und Intents aktivieren

Erstelle eine Application im Discord Developer Portal, füge einen Bot hinzu und aktiviere unter dem Reiter “Bot” die Optionsfelder für Message Content Intent und Server Members Intent.

2. Token konfigurieren

Trage deinen Token in die Konfigurationsdatei ein:

{
  channels: {
    discord: {
      enabled: true,
      token: "YOUR_BOT_TOKEN",
    },
  },
}

Für den Default-Account kannst du alternativ eine Umgebungsvariable nutzen:

DISCORD_BOT_TOKEN=...

3. Bot einladen und Gateway starten

Lade den Bot mit Berechtigungen für Nachrichten auf deinen Server ein und starte die Verbindung:

openclaw gateway

4. Erstes DM-Pairing bestätigen

Discord DMs nutzen standardmäßig den Pairing-Modus. Genehmige die Verbindung mit diesen Befehlen:

openclaw pairing list discord
openclaw pairing approve discord <CODE>

Runtime Model

Das Gateway übernimmt die vollständige Discord-Verbindung. Das Routing der Antworten ist deterministisch: Eine eingehende Nachricht von Discord wird immer direkt zurück an Discord geroutet.

Für die Session-Verwaltung gelten folgende Regeln:

• Direktnachrichten (DMs): Diese teilen sich standardmäßig die Haupt-Session des Agents (agent:main:main), sofern session.dmScope=main gesetzt ist.
• Server-Channels (Guilds): Hier werden isolierte Session-Keys verwendet (agent:<agentId>:discord:channel:<channelId>).
• Slash Commands: Diese laufen in isolierten Command-Sessions, übertragen aber den CommandTargetSessionKey an die geroutete Konversation.
• Group DMs: Diese werden standardmäßig ignoriert (channels.discord.dm.groupEnabled=false).

Fehlerbehebung

Falls die Verbindung nicht wie gewünscht funktioniert, prüfe diese Punkte:

• Token-Priorität: Die Auflösung ist account-abhängig. Werte in der Konfigurationsdatei überschreiben immer die Umgebungsvariablen. DISCORD_BOT_TOKEN wird nur für den Default-Account herangezogen.
• Pairing-Codes: Denke daran, dass Pairing-Codes nach einer Stunde ablaufen. Wenn du zu lange wartest, musst du die Liste neu abrufen.

Du hast spezifische Fragen zu deinem Setup? Nutze den AI Setup Assistant für direkte Hilfe.

Nächste Schritte

• Pairing-Modus Details
• Native Slash Commands nutzen
• Channel-Diagnose und Reparatur
• Gateway-Architektur

Berechtigungen für Discord-Bots zu verwalten, kann schnell unübersichtlich werden. Entweder antwortet der Bot jedem, der ihn anpinnt, oder er ignoriert wichtige Nachrichten, weil eine Konfiguration fehlt. Es ist oft mühsam, die richtige Balance zwischen Sicherheit und Erreichbarkeit zu finden, ohne den Überblick über die Config-Files zu verlieren.

Hier erfährst du, wie du den Zugriff präzise steuerst und das Routing für deinen Bot aufsetzt.

Voraussetzungen

• Discord Developer Portal Account
• Bot Token (DISCORD_BOT_TOKEN)
• Server ID, Channel ID und User ID (Discord Developer Mode aktiviert)

Schnellstart

In 5 Minuten steht dein Basis-Setup:

1. Bot erstellen: Gehe ins Discord Developer Portal, erstelle eine New Application und füge unter Bot einen neuen Bot hinzu. Kopiere den Token.
2. Intents aktivieren: Aktiviere unter Bot -> Privileged Gateway Intents den “Message Content Intent” und den “Server Members Intent”.
3. OAuth Scopes: Generiere eine URL mit den Scopes bot und applications.commands. Nutze Berechtigungen wie “View Channels”, “Send Messages” und “Read Message History”.
4. Config anpassen: Hinterlege deine IDs und Policies in der Konfiguration, um den Zugriff zu beschränken.

Access Control und Routing

DM Policy

Mit channels.discord.dm.policy steuerst du den Zugriff auf Direktnachrichten. Du hast vier Optionen:

• pairing (Standard): Unbekannte User werden zur Kopplung aufgefordert.
• allowlist: Nur explizit erlaubte User können den Bot nutzen.
• open: Jeder kann schreiben (erfordert channels.discord.dm.allowFrom auf "*").
• disabled: DMs sind komplett deaktiviert.

Wenn du Nachrichten sendest, nutzt du diese Formate:

• user:<id>
• <@id> Mention

Reine numerische IDs werden abgelehnt, da sie ohne Typ-Angabe (User oder Channel) nicht eindeutig sind.

Guild Policy

Das Verhalten in Servern wird über channels.discord.groupPolicy geregelt. Sobald ein channels.discord Block existiert, ist allowlist der sichere Standard.

• open: Der Bot reagiert auf allen Servern.
• allowlist: Zugriff nur auf Server in channels.discord.guilds.
• disabled: Server-Funktionen sind deaktiviert.

Bei der allowlist gilt: Wenn ein Server gelistet ist, aber keine channels definiert sind, sind alle Channels erlaubt. Sobald du channels definierst, sind alle nicht gelisteten Channels gesperrt.

Hier ist ein Beispiel für eine strikte Konfiguration:

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

Falls du nur den DISCORD_BOT_TOKEN setzt und keinen channels.discord Block erstellst, nutzt das System groupPolicy="open" als Fallback und gibt eine Warnung aus.

Mentions und Group DMs

In Servern reagiert der Bot standardmäßig nur, wenn er erwähnt wird (mention-gated).

Die Erkennung umfasst:

• Direkte Bot-Mention.
• Konfigurierte Muster in agents.list[].groupChat.mentionPatterns.
• Antworten (Replies) auf Bot-Nachrichten.

Group DMs sind standardmäßig deaktiviert (dm.groupEnabled=false). Du kannst sie über eine Allowlist in dm.groupChannels mit IDs oder Slugs freischalten.

Native Commands

• commands.native steht auf "auto" und ist für Discord aktiv.
• Du kannst dies pro Channel mit channels.discord.commands.native überschreiben.
• Setzt du den Wert auf false, werden bereits registrierte native Commands gelöscht.
• Die Authentifizierung für native Commands nutzt dieselben Allowlists und Policies wie normale Nachrichten.

Wichtig: User sehen Commands eventuell im Discord UI, auch wenn sie keine Berechtigung haben. Die Ausführung wird trotzdem geprüft und bei fehlenden Rechten mit “not authorized” abgelehnt.

Fehlerbehebung

• ID Fehler: Wenn IDs abgelehnt werden, stelle sicher, dass du das Format user:<id> nutzt. Reine Zahlen sind nicht eindeutig genug.
• Bot antwortet nicht: Prüfe, ob die Privileged Gateway Intents im Developer Portal aktiv sind. Ohne “Message Content Intent” sieht der Bot keine Nachrichten.
• Command sichtbar, aber keine Funktion: Das ist normales Verhalten. Die Discord UI zeigt Commands global, aber die OpenClaw Auth blockiert die Ausführung auf Basis deiner Policies.

Hast du Fragen zur Konfiguration? Nutze den AI Setup Assistant.

Nächste Schritte

• Slash commands – Erfahre mehr über den Command-Katalog.

Kennst du das? Du baust eine Integration und plötzlich geht der Kontext verloren, weil Nachrichten nicht richtig verknüpft sind oder die History fehlt. Es nervt, wenn Agents in einem vollen Channel den Faden verlieren und nicht wissen, auf wen sie sich gerade beziehen.

Oft wirken Bot-Antworten deplatziert, weil sie einfach nur in den Raum geworfen werden, anstatt die nativen Features der Plattform zu nutzen. Wenn du willst, dass sich dein Agent wie ein echter Teilnehmer anfühlt, musst du die Discord-spezifischen Funktionen richtig konfigurieren.

Voraussetzungen

• Eine laufende Discord-Integration
• Zugriff auf deine Konfigurationsdatei (JSON5)

Schnellstart

In weniger als fünf Minuten verbesserst du die Interaktion deines Agents massiv. Ich empfehle dir, den replyToMode sofort zu aktivieren, damit Antworten direkt an die richtige Nachricht angehängt werden.

1. Öffne deine Config und navigiere zu channels.discord.
2. Setze replyToMode auf first oder all.
3. Nutze im Agent-Output den Tag [[reply_to_current]].

{
  channels: {
    discord: {
      replyToMode: "first",
      historyLimit: 20
    }
  }
}

Reply-Tags und native Antworten

Discord unterstützt native Reply-Tags im Output deines Agents. Das ist der beste Weg, um Klarheit in Unterhaltungen zu bringen. Du hast zwei Optionen für die Tags:

• [[reply_to_current]]: Antwortet auf die aktuelle Nachricht im Flow.
• [[reply_to:<id>]]: Antwortet gezielt auf eine bestimmte Message ID.

Gesteuert wird dieses Verhalten über channels.discord.replyToMode. Du kannst zwischen off (Standard), first und all wählen. Die Message IDs werden im Kontext und in der History mitgeliefert, damit dein Agent genau weiß, welche Nachricht er adressieren soll.

History, Kontext und Threads

Für die Qualität der Antworten ist die Guild History entscheidend. Standardmäßig liegt das channels.discord.historyLimit bei 20 Nachrichten. Wenn dieser Wert nicht gesetzt ist, greift das System auf messages.groupChat.historyLimit zurück. Mit dem Wert 0 schaltest du die History komplett ab.

Für DMs hast du separate Kontrollmöglichkeiten:

• channels.discord.dmHistoryLimit für allgemeine DMs.
• channels.discord.dms["<user_id>"].historyLimit für spezifische User.

Threads werden in Discord als eigene Channel-Sessions behandelt. Dabei werden Metadaten des Parent-Threads genutzt, um die Verknüpfung der Sessions sicherzustellen. Ein Thread erbt die Konfiguration des Parent-Channels, außer du legst einen spezifischen Eintrag für den Thread an. Wichtig: Channel-Topics werden als untrusted Kontext injiziert und nicht als System Prompt behandelt.

Reaction Notifications

Du kannst festlegen, wie der Agent auf Reactions reagiert. Diese Events werden in System-Events umgewandelt und an die jeweilige Discord-Session angehängt. Es gibt vier Modi für jede Guild:

• off: Keine Benachrichtigungen.
• own (Standard): Nur eigene Reactions.
• all: Alle Reactions im Channel.
• allowlist: Nur Reactions von Usern, die unter guilds.<id>.users gelistet sind.

Config Writes

Standardmäßig sind Schreibzugriffe auf die Config über Discord-Channel aktiviert. Das ist besonders nützlich für /config set oder /config unset Flows, sofern die Command-Features aktiv sind. Wenn du das unterbinden willst, kannst du es so deaktivieren:

{
  channels: {
    discord: {
      configWrites: false,
    },
  },
}

PluralKit Support

Wenn du PluralKit nutzt, kannst du Nachrichten von Proxies automatisch auf die Identität von System-Membern mappen. Das ist besonders für Systeme wichtig, die Wert auf korrekte Identitäten legen.

{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // optional; für private Systeme nötig
      },
    },
  },
}

Beachte dabei:

• Allowlists können pk:<memberId> verwenden.
• Member-Displaynamen werden über Name oder Slug abgeglichen.
• Lookups nutzen die originale Message ID und sind zeitlich begrenzt.
• Falls ein Lookup fehlschlägt, werden Proxy-Nachrichten als Bot-Messages gewertet und ignoriert, außer allowBots=true ist gesetzt.

Exec Approvals in Discord

Discord ermöglicht Button-basierte Freigaben (Exec Approvals) direkt in den DMs. Das ist der effizienteste Weg, um kritische Aktionen abzusichern.

Die Konfiguration erfolgt über diesen Pfad:

• channels.discord.execApprovals.enabled
• channels.discord.execApprovals.approvers
• Zusätzliche Filter wie agentFilter, sessionFilter oder cleanupAfterResolve.

Fehlerbehebung

Falls Probleme auftreten, liegen sie meist an der Konfiguration der Berechtigungen oder IDs:

• Fehler bei Approvals: Wenn Approvals mit “unknown approval IDs” fehlschlagen, solltest du die Approver-Liste und die Aktivierung des Features prüfen.
• Fehlende PluralKit-Daten: Wenn Nachrichten gedroppt werden, prüfe, ob allowBots auf true stehen muss oder ob der API-Token für private Systeme korrekt hinterlegt ist.

Du hast Fragen zu einem spezifischen Setup? Nutze den AI Setup Assistant für schnelle Hilfe.

Nächste Schritte

• Exec approvals
• General Channel Config

Berechtigungen in Discord können echt nerven. Du willst eigentlich nur eine Nachricht senden oder einen User kicken, aber plötzlich hängst du in den Config-Dateien fest. Es ist frustrierend, wenn man nicht genau weiß, welche Action standardmäßig erlaubt ist und welche nicht.

Voraussetzungen

• Zugriff auf Action Gates unter dem Pfad channels.discord.actions.*

Schnellstart

Discord bietet dir verschiedene Actions für Nachrichten, Moderation und Metadaten. Damit du nicht lange suchen musst, sind hier die wichtigsten Kategorien und die dazugehörigen Befehle:

• Messaging: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• Reactions: react, reactions, emojiList
• Moderation: timeout, kick, ban
• Presence: setPresence

Diese Actions werden über sogenannte Action Gates gesteuert. Du findest diese unter channels.discord.actions.*.

Ich empfehle dir, besonders bei Moderations-Tools genau hinzuschauen. Standardmäßig sind nämlich nicht alle Funktionen direkt scharf geschaltet. Hier ist die Übersicht des Standard-Verhaltens (Default behavior):

Action group	Default
reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions	enabled
roles	disabled
moderation	disabled
presence	disabled

Wie du siehst, sind kritische Bereiche wie moderation oder roles erst einmal deaktiviert. Das ist auch gut so, damit dein Bot nicht aus Versehen Dinge tut, die er nicht soll. Wenn du diese Features nutzen willst, musst du das entsprechende Gate explizit konfigurieren.

AI Setup Assistant

Nächste Schritte

• Discord API Referenz
• Action Gate Konfiguration

Du kennst das sicher: Dein Bot ist online, der Prozess läuft ohne Absturz, aber er reagiert einfach nicht auf Nachrichten. Oder noch schlimmer: Er antwortet in manchen Channels, ignoriert andere aber komplett. Meistens liegt der Fehler tief in den Gateway-Einstellungen oder bei den Discord Intents, die man leicht übersieht.

Statt stundenlang im Trüben zu fischen, solltest du systematisch vorgehen. Oft sind es nur ein paar Zeilen in der Config oder ein fehlender Haken im Discord Developer Portal, die zwischen Frust und einem funktionierenden Bot stehen.

Voraussetzungen

Bevor du mit dem Debugging startest, stelle sicher, dass du Zugriff auf folgende Dinge hast:

• Deinen Discord Bot Token
• Die installierte CLI für dein Gateway (openclaw)
• Zugriff auf das Discord Developer Portal

Quick Start: Der 5-Minuten-Check

Wenn etwas nicht funktioniert, nutze diese Befehle in der angegebenen Reihenfolge, um den Status zu prüfen:

1. System-Check: Prüfe die generelle Gesundheit deines Setups.

   openclaw doctor

2. Channel-Verbindung: Teste, ob die Kanäle korrekt erkannt werden.

   openclaw channels status --probe

3. Live-Logs: Beobachte in Echtzeit, was passiert, wenn eine Nachricht eingeht.

   openclaw logs --follow

4. Gateway-Neustart: Nach jeder Änderung an den Intents musst du das Gateway neu starten, damit die Änderungen aktiv werden.

Fehlerbehebung

Ungültige Intents oder keine Nachrichten

Wenn dein Bot keine Nachrichten sieht, liegt es meist an den Intents.

• Aktiviere den Message Content Intent im Discord Developer Portal.
• Aktiviere den Server Members Intent, falls dein Bot User oder Member auflösen muss.
• Starte das Gateway nach jeder Änderung der Intents neu.

Nachrichten werden unerwartet blockiert

Falls Nachrichten zwar ankommen, aber nicht verarbeitet werden, solltest du deine Routing-Logik prüfen:

• Kontrolliere die groupPolicy.
• Überprüfe die Guild Allowlist unter channels.discord.guilds.
• Falls eine channels Map für eine Guild existiert, sind nur die dort explizit gelisteten Channels erlaubt.
• Prüfe das requireMention Verhalten und deine Mention-Patterns.

Require mention ist “false”, aber Nachrichten werden trotzdem blockiert

Das passiert oft durch Konfigurationsfehler:

• groupPolicy="allowlist" ist aktiv, aber es gibt keine passende Guild/Channel Allowlist.
• requireMention wurde an der falschen Stelle konfiguriert (es muss unter channels.discord.guilds oder direkt beim Channel-Eintrag stehen).
• Der Absender steht auf einer Blocklist unter users in der Guild- oder Channel-Konfiguration.
• Die Berechtigungen im Discord Client selbst verhindern den Zugriff.

Abweichungen beim Permissions Audit

Der Befehl channels status --probe führt Berechtigungsprüfungen durch. Beachte dabei:

• Diese Checks funktionieren nur für numerische Channel IDs.
• Wenn du Slug-Keys verwendest, funktioniert das Matching zur Laufzeit zwar weiterhin, aber der Probe-Befehl kann die Berechtigungen nicht vollständig verifizieren.

Probleme mit DMs und Pairing

DMs funktionieren nicht wie erwartet? Checke diese Punkte:

• Prüfe, ob DMs deaktiviert sind: channels.discord.dm.enabled=false.
• Checke die DM Policy: channels.discord.dm.policy="disabled".
• Falls du im pairing Modus bist, stelle sicher, dass die Pairing-Anfrage bestätigt wurde.
• Kontrolliere die History-Limits für DMs.

Bot-to-Bot Loops

Standardmäßig werden Nachrichten, die von Bots geschrieben wurden, ignoriert.

• Falls du channels.discord.allowBots=true setzt, musst du strikte Mention- und Allowlist-Regeln verwenden.
• Ohne diese Regeln riskierst du Endlosschleifen zwischen zwei Bots.

Configuration Reference

Hier sind die wichtigsten Felder für deine Discord-Konfiguration, auf die du achten solltest:

• Startup & Auth: enabled, token, accounts.*, allowBots
• Policy: groupPolicy, dm.*, guilds.*, guilds.*.channels.*
• Commands: commands.native, commands.useAccessGroups, configWrites
• Delivery: textChunkLimit, chunkMode, maxLinesPerMessage

Safety und Operations

Behandle Bot-Tokens immer als Secrets. In überwachten Umgebungen ist die Nutzung von DISCORD_BOT_TOKEN als Umgebungsvariable der beste Weg. Achte darauf, deinem Bot nur die minimal notwendigen Discord-Berechtigungen (Least-Privilege) zu geben.

Falls dein Command-Deployment oder der State veraltet wirken, starte das Gateway neu und validiere den Zustand erneut mit openclaw channels status --probe.

Hast du spezifische Fragen zu deinem Setup? Der AI Setup Assistant hilft dir direkt weiter.

Nächste Schritte

• Pairing
• Channel routing
• Troubleshooting
• Slash commands