Discord troubleshooting

• enable Message Content Intent
• enable Server Members Intent when you depend on user/member resolution
• restart gateway after changing intents

• verify groupPolicy
• verify guild allowlist under channels.discord.guilds
• if a guild channels map exists, only listed channels are allowed
• verify requireMention behavior and mention patterns

The Control UI channel details and openclaw channels status warn when the effective policy is allowlist but no guilds are configured. Add your server under channels.discord.guilds, or the account's guilds map when overridden. An explicit channels.discord.accounts.default.guilds map also overrides the top-level map, even when the account map is empty.

If status reports a deferred configuration reload, wait for active work to finish and refresh. A successful channel stop/start does not apply unpublished configuration. The warning distinguishes waiting to publish configuration from channel work deferred after publication; connection health alone does not confirm that a policy change has applied.

Useful checks:

openclaw doctoropenclaw channels status --probeopenclaw logs --follow

Common causes:

• groupPolicy="allowlist" without matching guild/channel allowlist
• requireMention configured in the wrong place (must be under channels.discord.guilds or a channel entry)
• sender blocked by guild/channel users allowlist

Typical logs:

• Slow listener detected ...
• stuck session: sessionKey=agent:...:discord:... state=processing ...

Discord does not apply a channel-owned timeout to queued agent turns. Message listeners hand off immediately, and queued Discord runs preserve per-session ordering until the session/tool/runtime lifecycle completes or aborts the work.

OpenClaw fetches Discord /gateway/bot metadata before connecting. Transient failures fall back to Discord's default gateway URL and are rate-limited in logs.

The metadata timeout defaults to 30 seconds. OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS can override it for unusual host environments.

OpenClaw waits for Discord's gateway READY event during startup and after runtime reconnects. Multi-account setups with startup staggering can need a longer startup READY window than the default.

Startup waits 15 seconds and runtime reconnects wait 30 seconds. OPENCLAW_DISCORD_READY_TIMEOUT_MS and OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS remain available for unusual host environments.

channels status --probe permission checks only work for numeric channel IDs.

If you use slug keys, runtime matching can still work, but probe cannot fully verify permissions.

• DM disabled: channels.discord.dm.enabled=false
• DM policy disabled: channels.discord.dmPolicy="disabled" (legacy: channels.discord.dm.policy)
• awaiting pairing approval in pairing mode

By default bot-authored messages are ignored.

If you set channels.discord.allowBots=true, use strict mention and allowlist rules to avoid loop behavior. Prefer channels.discord.allowBots="mentions" to only accept bot messages that mention the bot. In "mentions" mode, reply-ping metadata alone does not count. Bot replies need an active native mention or a configured text/transcript mention outside Markdown code.

OpenClaw also ships shared bot loop protection. Whenever allowBots lets bot-authored messages reach dispatch, Discord maps the inbound event to (account, channel, bot pair) facts and the generic pair guard suppresses the pair after it crosses the configured event budget. The guard prevents runaway two-bot loops that previously had to be stopped by Discord rate limits; it does not affect single-bot deployments or one-shot bot replies that stay under the budget.

Default settings (active when allowBots is set):

• maxEventsPerWindow: 20 -- bot pair can exchange 20 messages within the sliding window
• windowSeconds: 60 -- sliding window length
• cooldownSeconds: 60 -- once the budget trips, every additional bot-to-bot message in either direction is dropped for one minute

Configure the shared default once under channels.defaults.botLoopProtection, then override Discord when a legitimate workflow needs more headroom. Precedence is:

• channels.discord.accounts.<account>.botLoopProtection
• channels.discord.botLoopProtection
• channels.defaults.botLoopProtection
• built-in defaults

Discord uses the generic maxEventsPerWindow, windowSeconds, and cooldownSeconds keys.

{channels: {defaults: {  botLoopProtection: {    maxEventsPerWindow: 20,    windowSeconds: 60,    cooldownSeconds: 60,  },},discord: {  // Optional Discord-wide override. Account blocks override individual  // fields and inherit omitted fields from here.  botLoopProtection: {    maxEventsPerWindow: 4,  },  accounts: {    alpha: {      // Alpha listens to other bots only when they mention it.      allowBots: "mentions",    },    bravo: {      // Bravo listens to all bot-authored Discord messages.      allowBots: true,      mentionAliases: {        // Lets Bravo write an Alpha Discord mention with the configured user id.        Alpha: "ALPHA_DISCORD_USER_ID",      },      botLoopProtection: {        // Allow up to five messages per minute before suppressing the pair.        maxEventsPerWindow: 5,        windowSeconds: 60,        cooldownSeconds: 90,      },    },  },},},}

• keep OpenClaw current (openclaw update) so the Discord voice receive recovery logic is present
• confirm channels.discord.voice.daveEncryption=true (default)
• start from channels.discord.voice.decryptionFailureTolerance=24 (upstream default) and tune only if needed
• watch logs for:
  • discord voice: DAVE decrypt failures detected
  • discord voice: repeated decrypt failures; attempting rejoin
• if failures continue after automatic rejoin, collect logs and compare against the upstream DAVE receive history in discord.js #11419 and discord.js #11449