Discord (Bot API)

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

Pairing

Discord DMs default to pairing mode.

Slash commands

Native command behavior and command catalog.

Channel troubleshooting

Cross-channel diagnostics and repair flow.

Quick setup

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)

Configure token

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

Env fallback for the default account:

DISCORD_BOT_TOKEN=...

Invite the bot and start gateway

Invite the bot to your server with message permissions.

openclaw gateway

Approve first DM pairing

openclaw pairing list discord
openclaw pairing approve discord <CODE>

Pairing codes expire after 1 hour.

Token resolution is account-aware. Config token values win over env fallback. DISCORD_BOT_TOKEN is only used for the default account.

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

File attachments:

file blocks must point to an attachment reference (attachment://<filename>)
Provide the attachment via media/path/filePath (single file); use media-gallery for multiple files
Use filename to override the upload name when it should match the attachment reference

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

DM policy
Guild policy
Mentions and group DMs

channels.discord.dmPolicy controls DM access (legacy: channels.discord.dm.policy):

pairing (default)
allowlist
open (requires channels.discord.allowFrom to include "*"; legacy: channels.discord.dm.allowFrom)
disabled

If DM policy is not open, unknown users are blocked (or prompted for pairing in pairing mode).DM target format for delivery:

user:<id>
<@id> mention

Bare numeric IDs are ambiguous and rejected unless an explicit user/channel target kind is provided.

Guild handling is controlled by channels.discord.groupPolicy:

open
allowlist
disabled

Secure baseline when channels.discord exists is allowlist.allowlist behavior:

guild must match channels.discord.guilds (id preferred, slug accepted)
optional sender allowlists: users (IDs or names) and roles (role IDs only); if either is configured, senders are allowed when they match users OR roles
if a guild has channels configured, non-listed channels are denied
if a guild has no channels block, all channels in that allowlisted guild are allowed

Example:

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

If you only set DISCORD_BOT_TOKEN and do not create a channels.discord block, runtime fallback is groupPolicy="open" (with a warning in logs).

Guild messages are mention-gated by default.Mention detection includes:

explicit bot mention
configured mention patterns (agents.list[].groupChat.mentionPatterns, fallback messages.groupChat.mentionPatterns)
implicit reply-to-bot behavior in supported cases

requireMention is configured per guild/channel (channels.discord.guilds...).Group DMs:

default: ignored (dm.groupEnabled=false)
optional allowlist via dm.groupChannels (channel IDs or slugs)

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

Create app and bot

Discord Developer Portal -> Applications -> New Application
Bot -> Add Bot
Copy bot token

Privileged intents

In Bot -> Privileged Gateway Intents, enable:

Message Content Intent
Server Members Intent (recommended)

Presence intent is optional and only required if you want to receive presence updates. Setting bot presence (setPresence) does not require enabling presence updates for members.

OAuth scopes and baseline permissions

OAuth URL generator:

scopes: bot, applications.commands

Typical baseline permissions:

View Channels
Send Messages
Read Message History
Embed Links
Attach Files
Add Reactions (optional)

Avoid Administrator unless explicitly needed.

Copy IDs

Enable Discord Developer Mode, then copy:

server ID
channel ID
user ID

Prefer numeric IDs in OpenClaw config for reliable audits and probes.

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

Reply tags and native replies

Discord supports reply tags in agent output:

[[reply_to_current]]
[[reply_to:<id>]]

Controlled by channels.discord.replyToMode:

off (default)
first
all

Note: off disables implicit reply threading. Explicit [[reply_to_*]] tags are still honored.Message IDs are surfaced in context/history so agents can target specific messages.

History, context, and thread behavior

Guild history context:

channels.discord.historyLimit default 20
fallback: messages.groupChat.historyLimit
0 disables

DM history controls:

channels.discord.dmHistoryLimit
channels.discord.dms["<user_id>"].historyLimit

Thread behavior:

Discord threads are routed as channel sessions
parent thread metadata can be used for parent-session linkage
thread config inherits parent channel config unless a thread-specific entry exists

Channel topics are injected as untrusted context (not as system prompt).

Reaction notifications

Per-guild reaction notification mode:

off
own (default)
all
allowlist (uses guilds.<id>.users)

Reaction events are turned into system events and attached to the routed Discord session.

Ack reactions

ackReaction sends an acknowledgement emoji while OpenClaw is processing an inbound message.Resolution order:

channels.discord.accounts.<accountId>.ackReaction
channels.discord.ackReaction
messages.ackReaction
agent identity emoji fallback (agents.list[].identity.emoji, else ”👀”)

Notes:

Discord accepts unicode emoji or custom emoji names.
Use "" to disable the reaction for a channel or account.

Config writes

Channel-initiated config writes are enabled by default.This affects /config set|unset flows (when command features are enabled).Disable:

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

Gateway proxy

Route Discord gateway WebSocket traffic through an HTTP(S) proxy with channels.discord.proxy.

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

Per-account override:

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

PluralKit support

Enable PluralKit resolution to map proxied messages to system member identity:

{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // optional; needed for private systems
      },
    },
  },
}

Notes:

allowlists can use pk:<memberId>
member display names are matched by name/slug
lookups use original message ID and are time-window constrained
if lookup fails, proxied messages are treated as bot messages and dropped unless allowBots=true

Presence configuration

Presence updates are applied only when you set a status or activity field.Status only example:

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

Activity example (custom status is the default activity type):

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

Streaming example:

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

Activity type map:

0: Playing
1: Streaming (requires activityUrl)
2: Listening
3: Watching
4: Custom (uses the activity text as the status state; emoji is optional)
5: Competing

Exec approvals in Discord

Discord supports button-based exec approvals in DMs and can optionally post approval prompts in the originating channel.Config path:

channels.discord.execApprovals.enabled
channels.discord.execApprovals.approvers
channels.discord.execApprovals.target (dm | channel | both, default: dm)
agentFilter, sessionFilter, cleanupAfterResolve

When target is channel or both, the approval prompt is visible in the channel. Only configured approvers can use the buttons; other users receive an ephemeral denial. Approval prompts include the command text, so only enable channel delivery in trusted channels. If the channel ID cannot be derived from the session key, OpenClaw falls back to DM delivery.If approvals fail with unknown approval IDs, verify approver list and feature enablement.Related docs: Exec approvals

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:

Action group	Default
reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions	enabled
roles	disabled
moderation	disabled
presence	disabled

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

Used disallowed intents or bot sees no guild messages

enable Message Content Intent
enable Server Members Intent when you depend on user/member resolution
restart gateway after changing intents

Guild messages blocked unexpectedly

verify groupPolicy
verify guild allowlist under channels.discord.guilds
if guild channels map exists, only listed channels are allowed
verify requireMention behavior and mention patterns

Useful checks:

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

Require mention false but still blocked

Common causes:

groupPolicy="allowlist" without matching guild/channel allowlist
requireMention configured in the wrong place (must be under channels.discord.guilds or channel entry)
sender blocked by guild/channel users allowlist

Permissions audit mismatches

channels status --probe permission checks only work for numeric channel IDs.If you use slug keys, runtime matching can still work, but probe cannot fully verify permissions.

DM and pairing issues

DM disabled: channels.discord.dm.enabled=false
DM policy disabled: channels.discord.dmPolicy="disabled" (legacy: channels.discord.dm.policy)
awaiting pairing approval in pairing mode

Bot to bot loops

By default bot-authored messages are ignored.If you set channels.discord.allowBots=true, use strict mention and allowlist rules to avoid loop behavior.

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.

Overview

Messaging platforms

Configuration

Discord

Discord (Bot API)

Pairing

Slash commands

Channel troubleshooting

Quick setup

Runtime model

Interactive components

Access control and routing

Role-based agent routing

Developer Portal setup

Native commands and command auth

Feature details

Tools and action gates

Components v2 UI

Voice messages

Troubleshooting

Configuration reference pointers

Safety and operations

Overview

Messaging platforms

Configuration

​Discord (Bot API)

Pairing

Slash commands

Channel troubleshooting

​Quick setup

​Runtime model

​Interactive components

​Access control and routing

​Role-based agent routing

​Developer Portal setup

​Native commands and command auth

​Feature details

​Tools and action gates

​Components v2 UI

​Voice messages

​Troubleshooting

​Configuration reference pointers

​Safety and operations

​Related

Discord (Bot API)

Quick setup

Runtime model

Interactive components

Access control and routing

Role-based agent routing

Developer Portal setup

Native commands and command auth

Feature details

Tools and action gates

Components v2 UI

Voice messages

Troubleshooting

Configuration reference pointers

Safety and operations

Related