clawdbot/docs/discord.md

summary, read_when

summary	read_when
Discord bot support status, capabilities, and configuration	Working on Discord provider features

Discord (Bot API)

Updated: 2026-01-06

Status: production-ready for DMs + guild channels via the Discord gateway.

What it is

• Discord bot provider owned by the Gateway.
• Deterministic routing: replies always go back to Discord.
• DMs share the agent's main session; guild channels are isolated (discord:channel:<id>).

Setup (fast path)

1. Create a Discord application + bot.
2. Enable intents: Message Content (required), Server Members (recommended).
3. Invite the bot to your server with message permissions.
4. Configure the token (env or config) and start the gateway.

Example:

{
  discord: {
    enabled: true,
    token: "YOUR_BOT_TOKEN",
    dm: { policy: "pairing" },
    guilds: { "*": { requireMention: true } }
  }
}

Access control (DMs + guilds)

DMs:

• Default: discord.dm.policy = "pairing".
• Unknown senders receive a pairing code; messages are ignored until approved.
• Approve via:
  • clawdbot pairing list --provider discord
  • clawdbot pairing approve --provider discord <CODE>
• Pairing is the default token exchange for Discord DMs. Details: https://docs.clawd.bot/pairing

Guild channels:

• discord.groupPolicy = open | allowlist | disabled.
• discord.guilds (per-guild) + channels (per-channel) act as allowlists.
• Mentions are required by default; override per guild/channel.

How it works (behavior)

• Inbound messages are normalized into the shared provider envelope.
• Optional guild context history is injected before the current message.
• Replies always route back to the same channel or DM.

Commands + reply threading

• Native commands: commands.native = true (registers / commands).
• Text commands: commands.text = true (standalone /... messages).
• Threaded replies: controlled by discord.replyToMode using reply tags.

Media + limits

• Files supported up to discord.mediaMaxMb (default 8 MB).
• Outbound chunking controlled by discord.textChunkLimit.

Delivery targets (CLI/cron)

• DMs: user:<id>
• Guild channels: channel:<channelId>

Configuration reference (Discord)

Full configuration: https://docs.clawd.bot/configuration

Provider options:

• discord.enabled: enable/disable provider startup.
• discord.token: bot token (env: DISCORD_BOT_TOKEN).
• discord.groupPolicy: open | allowlist | disabled (default: open).
• discord.textChunkLimit: outbound chunk size (chars).
• discord.mediaMaxMb: inbound/outbound media cap (MB).
• discord.historyLimit: number of recent guild messages injected as context.
• discord.replyToMode: off | first | all.
• discord.actions.reactions: enable reaction tool actions.
• discord.actions.stickers: enable sticker actions.
• discord.actions.polls: enable poll actions.
• discord.actions.permissions: enable permission inspection actions.
• discord.actions.messages: enable message read/send/edit/delete actions.
• discord.actions.threads: enable thread actions.
• discord.actions.pins: enable pin actions.
• discord.actions.search: enable search actions.
• discord.actions.memberInfo: enable member info actions.
• discord.actions.roleInfo: enable role info actions.
• discord.actions.roles: enable role management actions.
• discord.actions.channelInfo: enable channel info actions.
• discord.actions.voiceStatus: enable voice status actions.
• discord.actions.events: enable event actions.
• discord.actions.moderation: enable moderation actions.
• discord.dm.enabled: enable/disable DMs.
• discord.dm.policy: pairing | allowlist | open | disabled (default: pairing).
• discord.dm.allowFrom: DM allowlist (ids/usernames). open requires "*".
• discord.dm.groupEnabled: enable group DMs.
• discord.dm.groupChannels: group DM allowlist.
• discord.guilds: per-guild rules:
  • slug, requireMention, reactionNotifications, users, channels.*.

Related global options:

• routing.groupChat.mentionPatterns.
• commands.native, commands.text, commands.useAccessGroups.
• messages.responsePrefix, messages.ackReaction, messages.ackReactionScope.