OpenClaw Discord-Integration: Bot-Einrichtung und Gateway Intents erklaert

Ueberblick

Die Discord-Integration ermoeglicht es Ihnen, ueber einen Discord-Bot mit OpenClaw zu chatten. Unterstuetzt werden sowohl DM (Direktnachrichten) als auch Textkanaele auf Servern. Diese Anleitung behandelt das Erstellen eines Bots, das Verstaendnis von Gateway Intents, die Konfiguration von DM-Sicherheitsrichtlinien und die Einrichtung der Zugriffskontrolle fuer Server-Kanaele — alles basierend auf der offiziellen OpenClaw-Dokumentation.

Voraussetzungen

• OpenClaw installiert und laufend
• Ein Discord-Konto
• Ein Discord-Server, auf dem Sie Admin-Berechtigungen haben (zum Testen)

Funktionsweise

Bevor Sie loslegen, ist es hilfreich zu verstehen, wie OpenClaw Discord-Nachrichten weiterleitet:

• DM-Konversationen werden in einer gemeinsamen Sitzung (agent:main:main) zusammengefasst und verwenden standardmaessig kopplungsbasierte Sicherheit.
• Server-Kanal-Konversationen sind pro Kanal isoliert und folgen dem Muster agent:<agentId>:discord:channel:<channelId>.
• Gruppen-DMs werden standardmaessig ignoriert, koennen aber ueber channels.discord.dm.groupEnabled aktiviert werden.

Das Gateway startet automatisch, wenn ein gueltiger Token vorhanden ist und enabled nicht auf false gesetzt ist.

Schritt 1: Discord-Anwendung erstellen

Gehen Sie zum Discord Developer Portal

1. Besuchen Sie das Discord Developer Portal
2. Klicken Sie auf New Application
3. Geben Sie einen Namen ein (z.B. "OpenClaw Assistant")
4. Klicken Sie auf Create

Bot einrichten

1. Gehen Sie in Ihrer Anwendung zum Bot-Tab
2. Klicken Sie auf Add Bot → Yes, do it!
3. Unter Token klicken Sie auf Copy, um Ihren Bot-Token zu kopieren

Wichtig: Behandeln Sie Ihren Bot-Token wie ein Passwort. Teilen Sie ihn niemals oeffentlich. Falls er offengelegt wird, generieren Sie ihn sofort neu.

Schritt 2: Privilegierte Gateway Intents aktivieren

Gateway Intents steuern, welche Ereignisse Ihr Bot von Discord empfaengt. OpenClaw benoetigt bestimmte privilegierte Intents, um korrekt zu funktionieren.

Erforderliche Intents

| Intent | Zweck | Erforderlich | |--------|-------|--------------| | Message Content Intent | Nachrichtentext in Server-Kanaelen lesen | Erforderlich — ohne diesen zeigt der Bot "Used disallowed intents"-Fehler an oder verbindet sich, antwortet aber nicht | | Server Members Intent | Mitgliederabfragen und Allowlist-Abgleich | Empfohlen — wird fuer Allowlist-basierte Zugriffskontrolle benoetigt |

Intents im Developer Portal aktivieren

1. Gehen Sie zum Bot-Tab im Developer Portal
2. Scrollen Sie zu Privileged Gateway Intents
3. Aktivieren Sie MESSAGE CONTENT INTENT (obligatorisch)
4. Aktivieren Sie SERVER MEMBERS INTENT (empfohlen)
5. Klicken Sie auf Save Changes

Hinweis: Bots auf 100+ Servern benoetigen eine Discord-Verifizierung, um privilegierte Intents nutzen zu koennen.

Schritt 3: Bot-Einladungs-URL generieren

OAuth2 konfigurieren

1. Gehen Sie zu OAuth2 → URL Generator

2. Waehlen Sie Scopes:

   • bot
   • applications.commands (erforderlich fuer native Slash-Befehle)

3. Waehlen Sie Bot-Berechtigungen:

   • View Channels
   • Send Messages
   • Read Message History
   • Embed Links
   • Attach Files
   • Add Reactions (optional, aber empfohlen)
   • Use External Emojis (optional)

Warnung: Vermeiden Sie die Vergabe der Administrator-Berechtigung, es sei denn, Sie debuggen aktiv. Vergeben Sie nur das Noetigste.

4. Kopieren Sie die generierte URL

Bot einladen

1. Oeffnen Sie die URL in Ihrem Browser
2. Waehlen Sie Ihren Testserver
3. Klicken Sie auf Authorize

Numerische IDs ermitteln

Aktivieren Sie den Entwicklermodus in Discord (Benutzereinstellungen → App-Einstellungen → Erweitert → Entwicklermodus), damit Sie per Rechtsklick Server-, Kanal- und Benutzer-IDs kopieren koennen — diese benoetigen Sie fuer die Konfiguration.

Schritt 4: OpenClaw konfigurieren

Option A: Umgebungsvariable

Setzen Sie den Token als Umgebungsvariable:

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"

Option B: Konfigurationsdatei

Bearbeiten Sie Ihre OpenClaw-Konfigurationsdatei mit dem Token direkt:

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

Hinweis: Wenn sowohl eine Umgebungsvariable als auch ein Token in der Konfigurationsdatei existieren, hat die Konfigurationsdatei Vorrang.

Option C: Multi-Account-Unterstuetzung

Fuer den Betrieb mehrerer Bot-Konten:

{
  channels: {
    discord: {
      accounts: [
        { token: "BOT_TOKEN_1", name: "assistant-1" },
        { token: "BOT_TOKEN_2", name: "assistant-2" }
      ]
    }
  }
}

Schritt 5: Starten und testen

Starten oder starten Sie das OpenClaw-Gateway neu:

openclaw gateway restart

Kanalstatus pruefen:

openclaw channels status --probe

Fuehren Sie eine Diagnose durch, falls etwas nicht stimmt:

openclaw doctor

Beim ersten DM-Kontakt verwendet der Bot standardmaessig ein Kopplungssystem — der Absender erhaelt einen zeitlich begrenzten Code (laeuft nach 1 Stunde ab), der genehmigt werden muss, bevor die Konversation beginnt.

DM-Sicherheitsrichtlinien

OpenClaw bietet drei DM-Zugriffskontrollrichtlinien:

Kopplung (Standard)

Unbekannte Absender erhalten einen zeitlich begrenzten Kopplungscode, der nach 1 Stunde ablaeuft. Der Code muss genehmigt werden, bevor die Konversation fortgesetzt werden kann.

{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "pairing"
      }
    }
  }
}

Allowlist

Nur konfigurierte Benutzer-IDs oder Benutzernamen koennen DMs senden:

{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "allowlist",
        allowFrom: ["123456789012345678", "username#1234"]
      }
    }
  }
}

Offen

Jeder kann DMs senden (mit Vorsicht verwenden):

{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "open",
        allowFrom: ["*"]
      }
    }
  }
}

Server-Kanal-Konfiguration

Grundlegende Server-Zugriffskontrolle

Beschraenken Sie den Bot auf bestimmte Server und Kanaele mit Erwaenungsanforderungen:

{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          requireMention: true,
          channels: {
            "CHANNEL_ID": {
              enabled: true
            }
          }
        }
      }
    }
  }
}

Wichtig: requireMention muss auf Server- oder Kanalebene konfiguriert werden, nicht auf der obersten Ebene der Discord-Konfiguration.

Kanalspezifische Einstellungen

Sie koennen Allowlists und Skill-Einschraenkungen pro Kanal konfigurieren:

{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          channels: {
            "CHANNEL_ID_1": {
              enabled: true,
              requireMention: true
            },
            "CHANNEL_ID_2": {
              enabled: true,
              requireMention: false
            }
          }
        }
      }
    }
  }
}

Konfigurationsparameter

Nachrichteneinstellungen

| Parameter | Standard | Beschreibung | |-----------|----------|-------------| | textChunkLimit | 2000 | Maximale Zeichenanzahl pro ausgehender Nachricht | | chunkMode | — | Auf Aufteilung an Leerzeilen (Absatzgrenzen) setzen, bevor Laengenlimits angewendet werden | | maxLinesPerMessage | 17 | Maximale Zeilenanzahl pro Nachricht | | mediaMaxMb | 8 | Maximale Mediendateigroesse in MB |

Kontextverlauf

{
  channels: {
    discord: {
      historyLimit: 20  // Number of recent messages included as context (default: 20, set to 0 to disable)
    }
  }
}

Antwort-Threading

Natives Antwort-Threading ist standardmaessig deaktiviert. Aktivieren Sie es mit:

{
  channels: {
    discord: {
      replyToMode: "on"  // Enable native reply threading
    }
  }
}

Verwenden Sie Antwort-Tags in Agent-Antworten, um das Threading-Verhalten zu steuern:

• [[reply_to_current]] — auf die gerade bearbeitete Nachricht antworten
• [[reply_to:<message_id>]] — auf eine bestimmte Nachricht antworten

Reaktionsbenachrichtigungen

Konfigurieren Sie Reaktionsereignis-Benachrichtigungen pro Server:

{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          reactionNotifications: "own"  // Options: "off", "own", "all", "allowlist"
        }
      }
    }
  }
}

Tool-Aktionen

Der Agent kann ein discord-Tool aufrufen, um Aktionen innerhalb von Discord auszufuehren. Die meisten Aktionen sind standardmaessig aktiviert, mit Ausnahme von Rollen und Moderation, die standardmaessig deaktiviert sind.

Verfuegbare Aktionen

| Kategorie | Aktionen | |-----------|----------| | Reaktionen | react, sticker, poll | | Nachrichten | readMessages, sendMessage, editMessage, deleteMessage, searchMessages | | Threads | threadCreate, threadList, threadReply | | Pins | pinMessage, unpinMessage, listPins | | Kanaele | channelInfo, channelList | | Mitglieder | memberInfo, roleInfo, permissions | | Rollen | roleAdd, roleRemove (standardmaessig deaktiviert) | | Moderation | timeout, kick, ban (standardmaessig deaktiviert) | | Sonstiges | emojiList, voiceStatus, eventList, eventCreate, setPresence |

Erweiterte Funktionen

PluralKit-Unterstuetzung

Wenn aktiviert, loest OpenClaw weitergeleitete Nachrichten zu ihren zugrundeliegenden System-Mitgliedern auf und zeigt Absender als "Member (PK:System)" an, um versehentliche Discord-Pings zu vermeiden.

Exec-Genehmigungsbutton-UI

In DM-Konversationen kann OpenClaw Exec-Genehmigungsbuttons fuer die interaktive Bestaetigung von Tool-Aktionen anzeigen.

Wiederholungskonfiguration

Ausgehende API-Aufrufe werden bei Rate Limits automatisch unter Verwendung von Discords retry_after-Header mit exponentiellem Backoff wiederholt. Konfigurieren Sie das Wiederholungsverhalten ueber die channels.discord.retry-Parameter.

Fehlerbehebung

Bot ist online, antwortet aber nicht

1. Message Content Intent pruefen: Ohne diesen Intent verbindet sich der Bot, kann aber keinen Nachrichtentext lesen. Gehen Sie zum Developer Portal → Bot → Privileged Gateway Intents und stellen Sie sicher, dass MESSAGE CONTENT INTENT aktiviert ist.

2. Kanalberechtigungen ueberpruefen: Stellen Sie sicher, dass der Bot im Zielkanal die Berechtigungen View Channels und Send Messages hat.

3. Erwaenungsanforderung pruefen: Wenn requireMention fuer den Server oder Kanal aktiviert ist, muessen Sie den Bot per @Erwaehnung ansprechen.

4. Server-/Kanal-Allowlists pruefen: Stellen Sie sicher, dass der Kanal nicht durch die Allowlist-Konfiguration blockiert wird.

"Used Disallowed Intents"-Fehler

Dies bedeutet, dass erforderliche Intents im Developer Portal nicht aktiviert sind:

1. Gehen Sie zum Developer Portal → Bot → Privileged Gateway Intents
2. Aktivieren Sie MESSAGE CONTENT INTENT
3. Speichern Sie und starten Sie das OpenClaw-Gateway neu

DMs funktionieren nicht

1. Stellen Sie sicher, dass dm.enabled nicht auf false gesetzt ist
2. Pruefen Sie die DM-Richtlinie — bei "allowlist" muss die Benutzer-ID enthalten sein
3. Bei Verwendung der "pairing"-Richtlinie pruefen Sie, ob der Kopplungscode abgelaufen ist (1-Stunden-Limit)

Diagnosebefehle

Verwenden Sie die integrierten Diagnosetools, um Probleme zu identifizieren:

# Run full diagnostics
openclaw doctor

# Check channel status with connection probe
openclaw channels status --probe

Best Practices

1. Behandeln Sie Bot-Tokens wie Passwoerter — verwenden Sie Umgebungsvariablen auf verwalteten Hosts und committen Sie niemals Tokens in die Versionskontrolle.
2. Vergeben Sie nur notwendige Berechtigungen — vermeiden Sie Administrator, es sei denn, Sie debuggen aktiv.
3. Verwenden Sie Kopplungs- oder Allowlist-DM-Richtlinien — die "open"-Richtlinie sollte nur fuer oeffentliche Bots mit entsprechendem Rate Limiting verwendet werden.
4. Aktivieren Sie Server Members Intent, wenn Sie Allowlist-basierte Zugriffskontrolle verwenden, fuer zuverlaessigeren Mitgliederabgleich.
5. Verwenden Sie requireMention in stark frequentierten Servern, um zu verhindern, dass der Bot auf jede Nachricht antwortet.
6. Starten Sie das Gateway mit --force neu, wenn es haengt: openclaw gateway restart --force.

Naechste Schritte

• WhatsApp-Integrationsanleitung
• Telegram-Integrationsanleitung
• Haeufige Fehler beheben