openclaw/docs/channels/discord.md

summary	read_when	title
Discord bot setup, config keys, components, voice, and troubleshooting	Working on Discord channel features	Discord

OpenClaw connects to Discord as a bot over the official Discord gateway. DMs and guild channels are supported.

Discord DMs default to pairing mode. Native command behavior and command catalog. Cross-channel diagnostics and repair flow.

What each page covers

• Discord setup — install the app, invite the bot, pair it, and prepare a guild workspace.
• Discord access control — DM policy, guild allowlists, mention gating, role routing, and action gates.
• Discord message behavior — 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 — make the bot join, move, and leave voice channels with selected users.
• Discord troubleshooting — blocked messages, intent errors, gateway timeouts, bot loops, and STT drops.

Where each section moved

Every section heading from the previous single-page version keeps its anchor here, so an existing link such as /channels/discord#voice-channels still resolves. Each entry points at the page that now holds the content.

• 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
• Outbound mention aliases
• Presence configuration
• Approvals in Discord
• Used disallowed intents or bot sees no guild messages
• Guild messages blocked unexpectedly
• Require mention false but still blocked
• Long-running Discord turns or duplicate replies
• Gateway metadata lookup timeout warnings
• Gateway READY timeout restarts
• Permissions audit mismatches
• DM and pairing issues
• Bot to bot loops
• Voice STT drops with DecryptionFailed(...)

Configuration reference

Primary reference: Configuration reference - Discord.

• 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.* (legacy flat streamMode, draftChunk, blockStreaming, blockStreamingCoalesce, chunkMode keys are migrated into streaming.* by openclaw doctor --fix)
• media: mediaMaxMb (caps 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, heartbeatVisibility, responsePrefix

Discord Activities

Set channels.discord.activities to let the core show_widget tool post self-contained HTML widgets that open inside Discord. The block is opt-in. Discord registers the Activity plumbing statically, but the current-channel presenter stays unavailable and /discord/activity remains externally hidden behind the normal 404 until an enabled account has an available bot token, resolved client secret, and application ID. See Discord Activities for the Developer Portal, tunnel, security, and troubleshooting setup.

• 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

• Treat bot tokens as secrets (DISCORD_BOT_TOKEN preferred in supervised environments).
• DISCORD_API_URL overrides the process-wide, versioned Discord REST base (for example, https://discord.example.com/api/v10). OpenClaw also uses that origin for Gateway discovery, WebSocket connections, media, webhooks, OAuth, and command registration; requests do not fall back to public Discord while the override is set. 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 least-privilege Discord permissions.
• If command deploy/state is stale, restart the gateway and re-check with openclaw channels status --probe.

Related

Launch interactive HTML widgets inside Discord. Pair a Discord user to the gateway. Emoji reaction semantics for the `message` tool. Group chat and allowlist behavior. Route inbound messages to agents. Threat model and hardening. Map guilds and channels to agents. Native command behavior.