Discord (Bot API)

Status: ready for DMs and guild channels via the official Discord gateway.

Quick setup

1. Create a Discord bot and enable intents

   Create an application in the Discord Developer Portal, add a bot, then enable:

   • Message Content Intent
   • Server Members Intent (required for role allowlists and role-based routing; recommended for name-to-ID allowlist matching)
2. Configure token

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

   Env fallback for the default account:

   DISCORD_BOT_TOKEN=...
   

3. Invite the bot and start gateway

   Invite the bot to your server with message permissions.

   openclaw gateway
   

4. Approve first DM pairing

   openclaw pairing list discord
   openclaw pairing approve discord <CODE>
   

   Pairing codes expire after 1 hour.

Runtime model

• Gateway owns the Discord connection.
• Reply routing is deterministic: Discord inbound replies back to Discord.
• By default (session.dmScope=main), direct chats share the agent main session (agent:main:main).
• Guild channels are isolated session keys (agent:<agentId>:discord:channel:<channelId>).
• Group DMs are ignored by default (channels.discord.dm.groupEnabled=false).
• Native slash commands run in isolated command sessions (agent:<agentId>:discord:slash:<userId>), while still carrying CommandTargetSessionKey to the routed conversation session.

Interactive components

OpenClaw supports Discord components v2 containers for agent messages. Use the message tool with a components payload. Interaction results are routed back to the agent as normal inbound messages and follow the existing Discord replyToMode settings.

Supported blocks:

• text, section, separator, actions, media-gallery, file
• Action rows allow up to 5 buttons or a single select menu
• Select types: string, user, role, mentionable, channel

Modal forms:

• Add components.modal with up to 5 fields
• Field types: text, checkbox, radio, select, role-select, user-select
• OpenClaw adds a trigger button automatically

Example:

{
  channel: "discord",
  action: "send",
  to: "channel:123456789012345678",
  message: "Optional fallback text",
  components: {
    text: "Choose a path",
    blocks: [
      {
        type: "actions",
        buttons: [
          { label: "Approve", style: "success" },
          { 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" },
          ],
        },
      ],
    },
  },
}

Access control and routing

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

Role-based agent routing

Use bindings[].match.roles to route Discord guild members to different agents by role ID. Role-based bindings accept role IDs only and are evaluated after peer or parent-peer bindings and before guild-only bindings. If a binding also sets other match fields (for example peer + guildId + roles), all configured fields must match.

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

Developer Portal setup

Native commands and command auth

• commands.native defaults to "auto" and is enabled for Discord.
• Per-channel override: channels.discord.commands.native.
• commands.native=false explicitly clears previously registered Discord native commands.
• Native command auth uses the same Discord allowlists/policies as normal message handling.
• Commands may still be visible in Discord UI for users who are not authorized; execution still enforces OpenClaw auth and returns "not authorized".

See Slash commands for command catalog and behavior.

Feature details

{
  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; needed for private systems
      },
    },
  },
}

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

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

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

Tools and action gates

Discord message actions include messaging, channel admin, moderation, presence, and metadata actions.

Core examples:

• messaging: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• reactions: react, reactions, emojiList
• moderation: timeout, kick, ban
• presence: setPresence

Action gates live under channels.discord.actions.*.

Default gate behavior:

Components v2 UI

OpenClaw uses Discord components v2 for exec approvals and cross-context markers. Discord message actions can also accept components for custom UI (advanced; requires Carbon component instances), while legacy embeds remain available but are not recommended.

• channels.discord.ui.components.accentColor sets the accent color used by Discord component containers (hex).
• Set per account with channels.discord.accounts.<id>.ui.components.accentColor.
• embeds are ignored when components v2 are present.

Example:

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

Voice messages

Discord voice messages show a waveform preview and require OGG/Opus audio plus metadata. OpenClaw generates the waveform automatically, but it needs ffmpeg and ffprobe available on the gateway host to inspect and convert audio files.

Requirements and constraints:

• Provide a local file path (URLs are rejected).
• Omit text content (Discord does not allow text + voice message in the same payload).
• Any audio format is accepted; OpenClaw converts to OGG/Opus when needed.

Example:

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

Troubleshooting

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

Configuration reference pointers

Primary reference:

• Configuration reference - Discord

High-signal Discord fields:

• startup/auth: enabled, token, accounts.*, allowBots
• policy: groupPolicy, dm.*, guilds.*, guilds.*.channels.*
• command: commands.native, commands.useAccessGroups, configWrites
• reply/history: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
• delivery: textChunkLimit, chunkMode, maxLinesPerMessage
• media/retry: mediaMaxMb, retry
• actions: actions.*
• presence: activity, status, activityType, activityUrl
• UI: ui.components.accentColor
• features: pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

Safety and operations

• Treat bot tokens as secrets (DISCORD_BOT_TOKEN preferred in supervised environments).
• Grant least-privilege Discord permissions.
• If command deploy/state is stale, restart gateway and re-check with openclaw channels status --probe.

Related

• Pairing
• Channel routing
• Troubleshooting
• Slash commands