Discord Integration: Setup, Access Control, and Operations

OpenClaw links up with Discord through the official Discord gateway, acting as a bot. Both DMs and guild channels work.

• Pairing, DMs on Discord use pairing mode by default.

• Slash commands, How native commands behave, plus the command catalog.

• Channel troubleshooting, Diagnostics and repair steps that span channels.

What each page covers

• Discord setup, get the app installed, invite the bot, pair it, and set up a guild workspace.
• Discord access control, DM policy, guild allowlists, mention gating, role routing, and action gates.
• Discord message behavior, the runtime model, reply tags, link previews, ack reactions, and mention aliases.
• Discord threads and sessions, forum threads, history limits, subagent threads, and ACP bindings.
• Discord components and approvals, components v2 containers, interactions, and exec approvals.
• Discord events and operations, reaction and presence wakes, bot presence, proxying, and PluralKit.
• Discord voice channels, realtime voice conversations, auto-join, and voice message attachments.
• Discord voice transcripts and meeting notes, continuous capture, transcript storage, and automatic notes.
• Follow users in Discord voice, have the bot join, move, and leave voice channels alongside chosen users.
• Discord troubleshooting, blocked messages, intent errors, gateway timeouts, bot loops, and STT drops.

Where each section moved

Anchors for all section headings from the earlier single-page version are preserved on this page, so links already in use, like /channels/discord#voice-channels, still resolve. Each entry leads to the page where that content now lives.

• Quick setup
• Recommended: Set up a guild workspace
• Runtime model
• Forum channels
• Interactive components
• Access control and routing
• Guild channel maps are allowlists
• Applying access-policy changes
• Role-based agent routing
• Native commands and command auth
• Feature details
• Tools and action gates
• Components v2 UI
• Voice
• Voice channels
• Capture voice transcripts
• Meeting notes
• Follow users in voice
• Voice messages
• Troubleshooting
• Recommended: Set up a guild workspace
• Create a Discord application and bot
• Enable privileged intents
• Copy your bot token
• Generate an invite URL and add the bot to your server
• Enable Developer Mode and collect your IDs
• Allow DMs from server members
• Set your bot token securely (do not send it in chat)
• Configure OpenClaw and pair
• Ask your agent
• CLI / config
• Approve first DM pairing
• Ask your agent
• CLI
• Add your server to the guild allowlist
• Ask your agent
• Config
• Allow responses without @mention
• Ask your agent
• Config
• Plan for memory in guild channels
• Ask your agent
• Manual
• DM policy
• Access groups
• Guild policy
• Mentions and group DMs
• Introductions when joining a server
• Reply tags and native replies
• Link previews
• Live stream preview
• History, context, and thread behavior
• Thread-bound sessions for subagents
• Persistent ACP channel bindings
• Reaction notifications
• Online presence events
• Ack reactions
• Config writes
• Gateway proxy
• PluralKit support
• Aliases for outbound mentions
• Configuring presence
• Approvals within Discord
• Disallowed intents used, or the bot receives no guild messages
• Guild messages blocked when not expected
• Mention requirement disabled yet messages still blocked
• Discord turns that run long or replies that duplicate
• Warnings when gateway metadata lookups time out
• Restarts caused by a gateway READY timeout
• Mismatches found in the permissions audit
• Problems with DMs and pairing
• Loops between bots
• Voice STT failing with DecryptionFailed(...)

Configuration reference

For the main reference, see Configuration reference - Discord.

High-signal Discord fields

• startup/auth: enabled, token, applicationId, accounts.*, allowBots
• policy: groupPolicy, dmPolicy, allowFrom, dm.*, guilds.*, guilds.*.channels.*
• group introductions: joinIntro, accounts.*.joinIntro (default: true)
• command: commands.native, commands.allowFrom (global), configWrites, slashCommand.ephemeral
• gateway: proxy
• reply/history: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
• delivery: textChunkLimit (default 2000), maxLinesPerMessage (default 17)
• streaming: streaming.mode, streaming.chunkMode, streaming.preview.*, streaming.progress.*, streaming.block.* (the older flat keys streamMode, draftChunk, blockStreaming, blockStreamingCoalesce, chunkMode get migrated into streaming.* by openclaw doctor --fix)
• media: mediaMaxMb (limits outbound Discord uploads, default 100)
• actions: actions.*
• presence: activity, status, activityType, activityUrl, autoPresence.*
• features: threadBindings, top-level bindings[] (type: "acp"), pluralkit, execApprovals, intents, agentComponents.enabled, agentComponents.ttlMs, activities, responsePrefix

Discord Activities

Enable channels.discord.activities so the core show_widget tool can publish self-contained HTML widgets that open inside Discord. This block is opt-in. Discord registers the Activity plumbing statically, yet the current-channel presenter remains unavailable, and /discord/activity stays externally hidden behind the usual 404 until an enabled account has an available bot token, a resolved client secret, and an application ID. For Developer Portal, tunnel, security, and troubleshooting setup, see Discord Activities.

• activities.clientSecret: OAuth2 client secret for the Discord application; falls back to DISCORD_CLIENT_SECRET
• activities.applicationId: optional Activity application ID; defaults to the bot application ID learned at gateway startup

Safety and operations

• Bot tokens should be treated as secrets (DISCORD_BOT_TOKEN is preferred in supervised environments).
• DISCORD_API_URL overrides the process-wide, versioned Discord REST base (for example, https://discord.example.com/api/v10). That origin also serves OpenClaw for Gateway discovery, WebSocket connections, media, webhooks, OAuth, and command registration; while the override is set, requests do not fall back to public Discord. Plain HTTP/WS is accepted only on loopback, and Discord voice transport is unavailable with the override. Set it in the Gateway process environment or global runtime dotenv, not a workspace .env.
• Grant Discord permissions at the least-privilege level.
• When command deploy/state is stale, restart the gateway and re-check with openclaw channels status --probe.

Discord model-picker preferences and thread bindings use SQLite. Their old discord/model-picker-preferences.json and discord/thread-bindings.json files predate the July 2026 upgrade support window. Doctor preserves these files and reports recovery guidance instead of importing them. Keep a pre-update backup, upgrade through OpenClaw 2026.9.5, and run openclaw doctor --fix before installing the latest version. July SQLite state and the July command-deployment cache remain supported.

Related

• Discord Activities, Launch interactive HTML widgets inside Discord.

• Pairing, Pair a Discord user to the gateway.

• Reactions, Emoji reaction semantics for the message tool.

• Groups, Group chat and allowlist behavior.

• Channel routing, Route inbound messages to agents.

• Security, Threat model and hardening.

• Multi-agent routing, Map guilds and channels to agents.

• Slash commands, Native command behavior.