105 lines
4.1 KiB
Markdown
105 lines
4.1 KiB
Markdown
---
|
|
summary: "Discord bot support status, capabilities, and configuration"
|
|
read_when:
|
|
- 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:
|
|
```json5
|
|
{
|
|
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`.
|