​

Discord (Bot API)

​

Schnelle Einrichtung

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

{
  channels: {
    discord: {
      enabled: true,
      token: {
        source: "env",
        provider: "default",
        id: "DISCORD_BOT_TOKEN",
      },
    },
  },
}

DISCORD_BOT_TOKEN=...

openclaw pairing list discord
openclaw pairing approve discord <CODE>

​

Empfohlen: Einen Server-Workspace einrichten

{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        YOUR_SERVER_ID: {
          requireMention: true,
          users: ["YOUR_USER_ID"],
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      guilds: {
        YOUR_SERVER_ID: {
          requireMention: false,
        },
      },
    },
  },
}

​

Runtime-Modell

• Das Gateway verwaltet die Discord-Verbindung.
• Das Antwort-Routing ist deterministisch: Eingehende Discord-Nachrichten werden wieder an Discord beantwortet.
• Standardmäßig (session.dmScope=main) teilen direkte Chats die Hauptsitzung des Agenten (agent:main:main).
• Serverkanäle haben 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>), tragen aber weiterhin CommandTargetSessionKey zur gerouteten Gesprächssitzung.

​

Forum-Kanäle

• Senden Sie eine Nachricht an das Forum-Elternelement (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 einen Thread direkt zu erstellen. Übergeben Sie für Forum-Kanäle nicht --message-id.

openclaw message send --channel discord --target channel:<forumId> \
  --message "Topic title\nBody of the post"

openclaw message thread create --channel discord --target channel:<forumId> \
  --thread-name "Topic title" --message "Body of the post"

​

Interaktive Komponenten

• text, section, separator, actions, media-gallery, file
• Aktionszeilen erlauben bis zu 5 Buttons oder ein einzelnes Auswahlmenü
• Auswahlypen: string, user, role, mentionable, channel

• file-Blöcke müssen auf eine Anhangsreferenz zeigen (attachment://<filename>)
• Stellen Sie den Anhang über media/path/filePath bereit (eine 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

• 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

{
  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" },
          ],
        },
      ],
    },
  },
}

​

Zugriffssteuerung und Routing

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

​

Rollenbasiertes Agenten-Routing

{
  bindings: [
    {
      agentId: "opus",
      match: {
        channel: "discord",
        guildId: "123456789012345678",
        roles: ["111111111111111111"],
      },
    },
    {
      agentId: "sonnet",
      match: {
        channel: "discord",
        guildId: "123456789012345678",
      },
    },
  ],
}

​

Einrichtung im Developer Portal

​

Native Befehle und Befehlsauthentifizierung

• commands.native ist standardmäßig "auto" und für Discord aktiviert.
• Kanalbezogene Überschreibung: channels.discord.commands.native.
• commands.native=false entfernt ausdrücklich zuvor registrierte native Discord-Befehle.
• Die Authentifizierung nativer Befehle verwendet dieselben Discord-Allowlists/-Richtlinien wie die normale Nachrichtenverarbeitung.
• Befehle können in der Discord-Oberfläche dennoch für Benutzer sichtbar sein, die nicht autorisiert sind; die Ausführung erzwingt weiterhin OpenClaw-Authentifizierung und gibt „not authorized“ zurück.

• ephemeral: true

​

Funktionsdetails

{
  channels: {
    discord: {
      streaming: "partial",
    },
  },
}

{
  channels: {
    discord: {
      streaming: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph",
      },
    },
  },
}

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // Opt-in
      },
    },
  },
}

{
  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,
            },
          },
        },
      },
    },
  },
}

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

{
  channels: {
    discord: {
      proxy: "http://proxy.example:8080",
    },
  },
}

{
  channels: {
    discord: {
      accounts: {
        primary: {
          proxy: "http://proxy.example:8080",
        },
      },
    },
  },
}

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

{
  channels: {
    discord: {
      status: "idle",
    },
  },
}

{
  channels: {
    discord: {
      activity: "Focus time",
      activityType: 4,
    },
  },
}

{
  channels: {
    discord: {
      activity: "Live coding",
      activityType: 1,
      activityUrl: "https://twitch.tv/openclaw",
    },
  },
}

{
  channels: {
    discord: {
      autoPresence: {
        enabled: true,
        intervalMs: 30000,
        minUpdateIntervalMs: 15000,
        exhaustedText: "token exhausted",
      },
    },
  },
}

​

Tools und Action-Gates

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

​

Components v2 UI

• channels.discord.ui.components.accentColor setzt die Akzentfarbe, die von Discord-Komponentencontainern verwendet wird (Hex).
• Pro Konto festlegen mit channels.discord.accounts.<id>.ui.components.accentColor.
• embeds werden ignoriert, wenn components v2 vorhanden sind.

{
  channels: {
    discord: {
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
    },
  },
}

​

Sprachkanäle

• 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.

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
    },
  },
}

• voice.tts überschreibt messages.tts nur für die Sprachwiedergabe.
• Sprachtranskript-Turns leiten den Besitzerstatus aus Discord-allowFrom (oder dm.allowFrom) ab; Sprecher, die keine Besitzer sind, können nicht auf nur für Besitzer bestimmte Tools zugreifen (zum Beispiel gateway und cron).
• Voice ist standardmäßig aktiviert; setzen Sie channels.discord.voice.enabled=false, um es 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 nicht gesetzt.
• OpenClaw überwacht außerdem Fehler bei der Empfangsentschlüsselung und stellt die Verbindung automatisch wieder her, indem es den Sprachkanal nach wiederholten Fehlern in einem kurzen Zeitraum verlässt und erneut beitritt.
• Wenn Empfangslogs wiederholt DecryptionFailed(UnencryptedWhenPassthroughDisabled) anzeigen, könnte dies der Upstream-Fehler von @discordjs/voice sein, der in discord.js #11419 verfolgt wird.

​

Sprachnachrichten

• Geben Sie einen lokalen Dateipfad an (URLs werden abgelehnt).
• Lassen Sie Textinhalt weg (Discord erlaubt keinen Text zusammen mit einer Sprachnachricht in derselben Payload).
• Jedes Audioformat wird akzeptiert; OpenClaw konvertiert bei Bedarf in OGG/Opus.

message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)

​

Fehlerbehebung

openclaw doctor
openclaw channels status --probe
openclaw logs --follow

{
  channels: {
    discord: {
      accounts: {
        default: {
          eventQueue: {
            listenerTimeout: 120000,
          },
          inboundWorker: {
            runTimeoutMs: 1800000,
          },
        },
      },
    },
  },
}

​

Hinweise zur Konfigurationsreferenz

• Configuration reference - Discord

• 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
• Inbound-Worker: inboundWorker.runTimeoutMs
• Antwort/Verlauf: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
• Zustellung: textChunkLimit, chunkMode, maxLinesPerMessage
• Streaming: streaming (Legacy-Alias: streamMode), draftChunk, blockStreaming, blockStreamingCoalesce
• Medien/Wiederholung: mediaMaxMb, retry
  • mediaMaxMb begrenzt ausgehende Discord-Uploads (Standard: 8MB)
• Aktionen: actions.*
• Presence: activity, status, activityType, activityUrl
• UI: ui.components.accentColor
• Funktionen: threadBindings, oberste Ebene 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 nach dem Prinzip der geringsten Rechte.
• Wenn die Bereitstellung oder der Zustand von Befehlen veraltet ist, starten Sie das Gateway neu und prüfen Sie erneut mit openclaw channels status --probe.

​

Verwandt

• Pairing
• Groups
• Channel routing
• Security
• Multi-agent routing
• Troubleshooting
• Slash commands