OpenClaw mit Discord verbinden: Bot, Intents und Serverrechte ohne Blindflug

Ein Discord-Bot kann online erscheinen und trotzdem keine Nachrichten verarbeiten. Das ist kein eindeutiges Fehlerbild: Der Invite kann unvollständig sein, ein Intent fehlen, OpenClaw kann noch mit einer alten Konfiguration laufen oder eine Nachricht kann an Pairing- und Guild-Regeln scheitern.

Deshalb richtest du die Verbindung in überprüfbaren Etappen ein. Nach jedem Schritt testest du genau eine Ebene, bevor du die nächste hinzunimmst.

Voraussetzungen

Für die Einrichtung brauchst du:

• eine laufende OpenClaw-Installation mit Shell-Zugriff auf den Gateway-Host,
• Zugriff auf das Discord Developer Portal,
• die Berechtigung, einen Bot auf einen Discord-Server einzuladen,
• einen privaten Testserver oder einen abgegrenzten Testkanal,
• einen in OpenClaw konfigurierten Secret-Provider für Umgebungsvariablen.

Teste nicht zuerst in einem stark frequentierten Community-Server. In einem privaten Server lassen sich Discord-Rechte, Mentions und OpenClaw-Regeln getrennt prüfen.

1. Discord-Anwendung und Bot anlegen

Öffne das Discord Developer Portal, wähle New Application und vergib einen Namen. Öffne anschließend in der Seitenleiste Bot und lege dort die Bot-Identität fest.

Aktiviere unter Privileged Gateway Intents:

• Message Content Intent: erforderlich, damit der Bot normale Nachrichten in Guild-Channels lesen kann.
• Server Members Intent: erforderlich, wenn du Rollen-Allowlists, Name-zu-ID-Auflösung oder kanalbezogene Audience-Gruppen verwendest.
• Presence Intent: optional; für einen normalen Text-Bot nicht nötig.

Erwartetes Ergebnis: Im Bot-Bereich existiert eine Bot-Identität und der Message Content Intent ist aktiv.

2. Token sicher an OpenClaw übergeben

Erzeuge den Token auf der Bot-Seite über Reset Token und kopiere ihn. Der Token gehört weder in ein Repository noch in einen Screenshot oder Chat. Wenn er offengelegt wurde, rotierst du ihn im Developer Portal, bevor du weiterarbeitest.

Setze ihn in der Umgebung, in der du die Konfiguration vorbereitest:

export DISCORD_BOT_TOKEN="<YOUR_DISCORD_BOT_TOKEN>"

Der Export gilt nur für diese Shell. Der Prozess, der den Gateway startet, muss dieselbe Variable ebenfalls erhalten. Bei einem Hintergrunddienst konfigurierst du sie deshalb in dessen Service-Umgebung und nicht nur in einem beliebigen Terminal.

Lege anschließend eine SecretRef auf die Umgebungsvariable an und aktiviere den Discord-Kanal:

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 config validate

Falls dein Env-Provider nicht default heißt, verwendest du dessen konfigurierte Provider-ID. openclaw config set --help zeigt die SecretRef-Optionen deiner installierten CLI.

Erwartetes Ergebnis: openclaw config validate beendet sich ohne Schemafehler. Der Token selbst wird nicht als Klartext in die Konfiguration geschrieben.

Mit diesem Befehl siehst du, welche Konfigurationsdatei die CLI bearbeitet:

openclaw config file

3. Bot mit den nötigen Rechten einladen

Öffne im Developer Portal OAuth2 und dort den OAuth2 URL Generator. Aktiviere die Scopes:

• bot
• applications.commands

Für normale Textkanäle braucht der Bot mindestens diese Berechtigungen:

• View Channels
• Send Messages
• Read Message History
• Embed Links
• Attach Files

Add Reactions ist optional. Soll der Bot in Threads oder Forum-Threads schreiben, braucht er zusätzlich Send Messages in Threads.

Öffne die erzeugte Invite-URL, wähle deinen Testserver und autorisiere den Bot. Kontrolliere danach die kanalbezogenen Discord-Rechte: Serverrechte allein helfen nicht, wenn ein Kanal sie durch einen Override verweigert.

Erwartetes Ergebnis: Der Bot erscheint im Testserver und darf den vorgesehenen Testkanal sehen sowie dort Nachrichten senden.

4. Gateway neu laden und Verbindung prüfen

Nach Änderungen an Token oder Discord-Konfiguration startest du den laufenden Gateway neu:

openclaw gateway restart

Prüfe danach zuerst Runtime und Transport:

openclaw status
openclaw gateway status
openclaw doctor
openclaw channels status --probe

Die dokumentierte gesunde Basis umfasst eine laufende Runtime, einen erfolgreichen Connectivity-Probe und einen verbundenen Kanaltransport. Die genaue Ausgabe kann je nach Installation und Kanal-Capabilities variieren.

Öffne für den eigentlichen Nachrichtentest ein zweites Terminal:

openclaw logs --follow

Sende dann eine einzelne Testnachricht und beobachte genau den dazugehörigen Log-Eintrag. Beende die Log-Ansicht anschließend mit Ctrl-C.

Wenn bereits openclaw gateway status fehlschlägt, liegt das Problem noch nicht an Discord-Kanalregeln. Wenn der Gateway läuft, aber die Kanalprobe scheitert, prüfst du Token, Gateway-Umgebung und Discord-Verbindung.

5. DM-Pairing abschließen

Discord-DMs verwenden standardmäßig Pairing. Schreibe dem Bot eine Direktnachricht. Ein unbekannter Absender erhält einen Pairing-Code; die ursprüngliche Nachricht wird noch nicht verarbeitet.

Zeige offene Anfragen an und bestätige den Code:

openclaw pairing list discord
openclaw pairing approve discord <CODE>

Pairing-Codes laufen nach einer Stunde ab. Pro Kanal-Account können höchstens drei Anfragen gleichzeitig offen sein. Ist ein Code abgelaufen, sendest du dem Bot erneut eine DM und verwendest die neue Anfrage.

Erwartetes Ergebnis: Nach der Freigabe verarbeitet der Bot eine neue DM und antwortet. Die Freigabe gilt für Direktnachrichten; sie erteilt nicht automatisch Zugriff auf Guild-Channels.

6. Guild-Zugriff getrennt testen

Aktiviere im Discord-Client den Developer Mode und kopiere die Server-ID sowie deine User-ID. Für einen begrenzten Test setzt du eine Guild-Allowlist, verlangst eine Mention und erlaubst deinen Absender:

openclaw config set channels.discord.groupPolicy '"allowlist"' --strict-json
openclaw config set 'channels.discord.guilds["YOUR_SERVER_ID"].requireMention' true --strict-json
openclaw config set 'channels.discord.guilds["YOUR_SERVER_ID"].users' '["YOUR_USER_ID"]' --strict-json
openclaw config validate
openclaw gateway restart

Ersetze die Platzhalter durch die numerischen Discord-IDs und lasse die IDs als Strings stehen. Bei den String-Werten sind die inneren doppelten Anführungszeichen erforderlich, weil --strict-json gültiges JSON erwartet.

Teste anschließend im erlaubten Kanal eine eindeutige Mention, etwa @Bot antworte mit ping.

Erwartetes Ergebnis: Die Mention wird verarbeitet und die Antwort erscheint im Kanal. Eine erfolgreiche DM allein deckt diesen Guild-Test nicht ab, weil Pairing und Guild-Zugriff unterschiedliche Zugriffskontrollen verwenden.

Wenn du später kanalbezogene Regeln ergänzt, teste nach jeder Einschränkung erneut. Prüfe bei einem stillen Kanal sowohl die OpenClaw-Regel als auch die Discord-Permissions dieses konkreten Kanals.

7. Sichtbare Antworten richtig einordnen

Die Runtime kennt für Gruppen- und Kanalgespräche den Config-Pfad messages.groupChat.visibleReplies. Ohne abweichende globale Regel verwendet er standardmäßig automatic: Normale finale Antworten werden wie gewohnt im Raum veröffentlicht.

Der Modus message_tool hat eine andere Semantik. Dann muss der Agent für sichtbare Raumausgaben ausdrücklich message(action=send) verwenden; normaler finaler Text bleibt privat. Das ist nützlich für gezielt gesteuerte Ausgaben, aber beim Debugging setzt du hier nicht zuerst an.

Wenn Discord Typing anzeigt, der Lauf endet und trotzdem kein Beitrag erscheint, prüfe:

1. Ist messages.groupChat.visibleReplies ausdrücklich auf message_tool gesetzt?
2. Hat der Lauf tatsächlich das Message-Tool für den Discord-Raum verwendet?
3. Zeigen die Logs einen Zustell- oder Berechtigungsfehler?

Ist keine erzwungene Message-Tool-Ausgabe gewünscht, setzt du den Pfad auf automatic zurück:

openclaw config set messages.groupChat.visibleReplies '"automatic"' --strict-json
openclaw config validate
openclaw gateway restart

Sende danach im betroffenen Discord-Raum erneut eine Testnachricht. Erwartetes Ergebnis: Discord zeigt Typing, und die finale Antwort erscheint anschließend als normaler Beitrag im Kanal.

8. Slash Commands prüfen

Der Invite-Scope applications.commands erlaubt Discord die Registrierung nativer Befehle. OpenClaw verwendet für commands.native standardmäßig auto.

Prüfe nach dem Gateway-Neustart, ob Discord Befehle wie /help, /commands, /status oder /whoami anbietet. Diese Befehle funktionieren nur für autorisierte Absender. Ob Discord den Befehl anzeigt, sagt allein noch nichts darüber aus, ob der jeweilige Absender ihn auch ausführen darf.

Fehlen die Befehle vollständig, prüfst du zuerst den Invite-Scope und danach Gateway-Logs sowie Kanalstatus. Hast du commands.native bewusst deaktiviert, erwartet OpenClaw keine neue native Registrierung.

Fehlerbilder ohne Rätselraten

Symptom	Zuerst prüfen	Erwartete Abgrenzung
Bot fehlt im Server	Invite-URL und Scope bot	Invite-Problem, noch kein OpenClaw-Runtimefehler
Bot ist online, liest aber keine normale Guild-Nachricht	Message Content Intent, Kanalrechte und Mention-Regel	Discord-Event oder Zugriff wird blockiert
Kanalprobe scheitert nach Token-Wechsel	SecretRef, Service-Umgebung und Gateway-Neustart	Laufender Prozess sieht den neuen Token nicht
DM liefert nur einen Code	openclaw pairing list discord	Transport funktioniert, Freigabe fehlt
DM funktioniert, Guild bleibt still	Guild-Allowlist, Absender, Mention und Kanalrechte	DM-Pairing ist nicht die Ursache
Typing erscheint, aber kein Beitrag	Logs und messages.groupChat.visibleReplies	Verarbeitung und sichtbare Zustellung getrennt prüfen
Slash Commands fehlen	applications.commands, commands.native und Neustart	Registrierung oder Autorisierung eingrenzen
Threads bleiben still	Send Messages in Threads	Normale Sendeberechtigung reicht dort nicht

Sicher zurückrollen

Wenn du den Discord-Kanal nach einem fehlgeschlagenen Test deaktivieren möchtest, ohne die übrige OpenClaw-Konfiguration zu verändern, setzt du:

openclaw config set channels.discord.enabled false --strict-json
openclaw config validate
openclaw gateway restart

Wurde der Token offengelegt, reicht das Deaktivieren nicht. Rotiere ihn zusätzlich im Discord Developer Portal und aktualisiere anschließend die Variable in der Gateway-Umgebung.

Was ein vollständiger Test abdeckt

Ein vollständiger Discord-Test besteht aus getrennten Ergebnissen: Die Kanalprobe ist erfolgreich, eine freigegebene DM erhält eine Antwort, eine Mention im erlaubten Guild-Channel wird verarbeitet und ein autorisierter Slash Command funktioniert. Damit prüfst du Transport, Pairing, Guild-Zugriff und Command-Registrierung jeweils an der passenden Stelle.

Kernpunkte

• Intents, Serverrechte, Token, Pairing und Guild-Zugriff sind getrennte Fehlerquellen. Teste sie nacheinander.
• Ein Token-Wechsel wirkt für den laufenden Dienst nach dem Gateway-Neustart. Setze den Token über channels.discord.token als SecretRef.
• Validiere Config-Änderungen mit openclaw config validate und lade den Gateway anschließend neu.
• Eine freigegebene DM sagt nichts über den Guild-Zugriff aus: Pairing und Guild-Allowlist benötigen eigene Tests.
• Sichtbare Slash Commands betreffen die Registrierung; ob ein Absender sie ausführen darf, entscheidet die Autorisierung getrennt davon.

Weiterlesen

• Signal für OpenClaw: Pairing, Gruppen und sichere Replies
• Slack als Team-Frontend für OpenClaw-Agenten
• Matrix mit OpenClaw verbinden: Räume, Push Rules und sichere Replies
• Cron-Jobs, Heartbeats und Automationen