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

Ein Discord-Bot kann online erscheinen und trotzdem keine Nachrichten verarbeiten. Der Online-Status zeigt zunächst nur, dass eine Verbindung besteht. Fehlt der Message Content Intent, erreicht der Nachrichteninhalt den Bot nicht; kommt das Event an, können anschließend Kanalrechte oder OpenClaw-Zugriffsregeln die Verarbeitung stoppen.

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

Was du vor dem Start brauchst

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 Kanal kannst du zunächst sicherstellen, dass Discord die Nachricht zustellt, und danach prüfen, ob OpenClaw sie wegen einer Mention- oder Zugriffsregel verwirft.

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.

Danach muss im Bot-Bereich eine Bot-Identität existieren und der Message Content Intent aktiv sein.

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.

Die Prüfung ist bestanden, wenn openclaw config validate ohne Schemafehler endet und der Token nicht als Klartext in der Konfiguration steht.

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 den vorgesehenen Kanal: Ein Serverrecht hilft nicht, wenn ein Kanal es durch einen Override verweigert.

Der Invite funktioniert, sobald der Bot im Testserver erscheint, den Testkanal sehen kann und dort Nachrichten senden darf.

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 die Runtime mit der dokumentierten Diagnosefolge:

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

Gesund ist die Basis, wenn die Runtime läuft und die Kanalprobe den Discord-Transport als verbunden meldet. Die genaue Ausgabe kann je nach Installation und Kanal-Capabilities variieren.

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

openclaw logs --follow

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

Scheitert bereits openclaw gateway status, prüfst du zuerst den Dienst selbst. Läuft der Gateway, aber die Kanalprobe schlägt fehl, kontrollierst du, ob der Prozess die aktuelle Token-SecretRef auflösen kann.

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.

Nach der Freigabe muss der Bot eine neue DM verarbeiten und beantworten. Diese Freigabe gilt nur für Direktnachrichten und öffnet keinen Guild-Channel.

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.

Wenn die Antwort im Kanal erscheint, funktionieren die Guild-Regel für diesen Server und die Freigabe deines Nutzers. Eine erfolgreiche DM beweist das nicht, weil Pairing und Guild-Zugriff getrennte Kontrollen sind.

Ergänzt du später kanalbezogene Regeln, testest du nach jeder Einschränkung erneut. Bleibt ein Kanal still, kontrollierst du zuerst seinen OpenClaw-Eintrag und danach den Discord-Override dieses 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 erneut eine Testnachricht im betroffenen Raum. Discord sollte zunächst Typing anzeigen und anschließend die finale Antwort als normalen Kanalbeitrag veröffentlichen.

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. Eine sichtbare Auswahl beweist daher noch nicht, dass dein Nutzer den gewählten Befehl ausführen darf.

Fehlen die Befehle vollständig, kontrollierst du zunächst den Invite-Scope. Danach zeigen Kanalstatus und Gateway-Logs, ob die Registrierung scheitert. 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 mit Scope bot	Invite-Problem, noch kein OpenClaw-Runtimefehler
Bot ist online, liest aber keine normale Guild-Nachricht	Kommt das Event mit Inhalt an?	Danach Kanalzugriff und Mention-Anforderung prüfen
Kanalprobe scheitert nach Token-Wechsel	Löst der Gateway die neue SecretRef auf?	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	Gilt die Guild-Regel für diesen Nutzer und Kanal?	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	Invite-Scope, danach Gateway-Log	Registrierung 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 Test liefert vier getrennte Belege:

1. Die Kanalprobe meldet einen verbundenen Discord-Transport.
2. Eine freigegebene DM erhält eine Antwort.
3. Eine Mention im erlaubten Guild-Channel wird verarbeitet.
4. Ein autorisierter Slash Command funktioniert.

Schlägt nur einer dieser Schritte fehl, setzt du die Diagnose an dieser Ebene fort, statt die gesamte Einrichtung neu zu beginnen.

Der praktische Punkt

• Prüfe zuerst, ob Discord das Nachrichtenereignis liefert. Erst danach sind OpenClaw-Regeln relevant.
• Ein Token-Wechsel erreicht den laufenden Dienst nur, wenn dessen Umgebung die neue SecretRef auflösen kann.
• Nach jeder Config-Änderung folgen Validierung und Gateway-Neustart.
• Eine freigegebene DM öffnet keinen Guild-Channel; dafür gilt eine eigene Zugriffsregel.
• Sichtbare Slash Commands belegen die Registrierung, nicht die Berechtigung des Absenders.

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