On this page
🏆 Why Discord?
| Advantage | Details |
|---|---|
| Thread isolation | Each thread gets its own session context — perfect for separate conversations. Use /focus and /unfocus. |
| Rich formatting | Code blocks, embeds, reactions, file attachments — all supported natively. |
| No public IP needed | Uses WebSocket gateway (not webhooks). Works behind NAT like Telegram. |
| Multi-server | One bot can serve multiple Discord servers with per-server policies. |
| Always on desktop | If you're a developer already in Discord all day, your AI is right there. |
| Session TTL | Thread-bound sessions with configurable time-to-live for automatic cleanup. |
🤖 Create a Discord application & bot
- Go to discord.com/developers/applications
- Click “New Application” → name it (e.g., “OpenClaw”)
- Go to the Bot tab → click “Reset Token” → copy the bot token
- Under the Bot tab: set Public Bot OFF (unless you want anyone to add it), and Message Content Intent ON (required)
⚠️ Save the token immediately. Discord only shows it once. If you lose it, you'll need to reset and generate a new one. Store it in a password manager.
🔑 Privileged intents
Under your app's Bot tab, enable these Gateway Intents:
| Intent | Required? | Why |
|---|---|---|
| Message Content | ✅ Required | Without this, the bot can't read message text — only metadata |
| Server Members | Optional | Needed if you want the bot to resolve usernames/roles |
| Presence | Optional | Not needed for most setups |
⚠️ This is the #1 Discord issue. If your bot connects but ignores messages, Message Content Intent is probably disabled. The bot receives events but the message body is empty.
📨 Invite the bot to your server
Go to the OAuth2 → URL Generator tab:
- Under Scopes, check:
bot - Under Bot Permissions, check: Send Messages, Read Message History, Use Slash Commands, Embed Links, Attach Files, Add Reactions, Create Public Threads, Send Messages in Threads, Manage Messages (optional)
- Copy the generated URL and open it in your browser
- Select your server and authorize
# Minimum permission integer for the invite URL:
# 397284550656
# Includes: Send/Read/Threads/Embeds/Files/Reactions/SlashCommands
⚙️ Configure OpenClaw
// ~/.openclaw/openclaw.json
{
"channels": {
"discord": {
"enabled": true,
"token": "YOUR_DISCORD_BOT_TOKEN",
"dmPolicy": "pairing",
"groupPolicy": "open",
"autoArchiveDuration": 4320 // 1h=60, 1d=1440, 3d=4320, 1w=10080 (v2026.3.11)
}
}
}
Alternatively use the env var: DISCORD_BOT_TOKEN=...
Restart the gateway: openclaw gateway restart
💡 Note: Discord uses
groupPolicy for server channels (they're technically groups). Set to "open" for your personal server, or "allowlist" if the bot is in shared servers.🧵 Thread-based sessions
Discord's killer feature for OpenClaw: each thread gets its own isolated session with separate conversation history.
Focus / Unfocus
/focus — Lock the agent to this thread (it ignores other channels)
/unfocus — Release the agent back to normal routing
Session TTL
{
"session": {
"threadBindings": {
"enabled": true,
"ttlHours": 24
}
}
}
Thread sessions auto-expire after the TTL, freeing up context. Use /session ttl 48h to override per-thread.
Agents in threads
/agents — List available agents in the current thread
# Useful for multi-agent setups where different agents
# handle different topics
⚡ Slash commands & special commands
| Command | Description |
|---|---|
/status | Session status — model, tokens used, cost |
/model | Switch AI model mid-conversation |
/reset | Reset conversation context |
/focus | Lock agent to current thread |
/unfocus | Release agent from thread lock |
/agents | List available agents (multi-agent setups) |
/session ttl <duration> | Set session timeout for this thread |
/activation always | Agent responds to all messages (current session only) |
💡 Tip:
/activation always only affects the current session. To persist it, set it in your config's channel settings.✨ Supported features
| Feature | Status | Notes |
|---|---|---|
| Text messages | ✅ Full | Markdown, code blocks, embeds |
| Thread sessions | ✅ Full | Isolated context per thread with TTL |
| Images / attachments | ✅ Full | Send and receive files, images, code |
| Reactions | ✅ Full | Agent can add/read reactions |
| Slash commands | ✅ Full | All OpenClaw commands available |
| DMs | ✅ Full | Direct messages with pairing/allowlist |
| Voice channels | ❌ No | Text only — voice channels not supported |
| Embeds | ✅ Full | Rich embed responses with formatting |
| Pins | ✅ Read | Agent can reference pinned messages |
🌐 Multi-server routing
If your bot is in multiple Discord servers, control access per-server:
{
"channels": {
"discord": {
"groupPolicy": "allowlist",
"groups": {
"1234567890": {
"requireMention": false,
"activation": "always"
},
"*": {
"requireMention": true
}
}
}
}
}
The numeric IDs are Discord server (guild) IDs. Right-click a server → Copy Server ID (enable Developer Mode in Discord settings first).
🔧 Troubleshooting
| Problem | Fix |
|---|---|
| Bot is online but doesn't respond | Message Content Intent is disabled. Enable it in the Discord Developer Portal → Bot tab. |
| Bot can't see messages | Check bot has Read Message History permission in the channel. |
| “Missing Access” error | Bot lacks permissions. Re-invite with the correct permission integer. |
| Slash commands not showing | Can take up to 1 hour for Discord to propagate. Or re-invite the bot. |
| HTTP proxy issues | If using a proxy, set HTTP_PROXY env var. Discord adapter honors proxy settings for app-id and allowlist resolution. |
| Thread sessions lost on restart | Session state doesn't persist across gateway restarts by default. Configure persistence in session settings. |