Troubleshooting
Used disallowed intents or bot sees no guild messages
Used disallowed intents or bot sees no guild messages
- enable Message Content Intent
- enable Server Members Intent when you depend on user/member resolution
- restart gateway after changing intents
Guild messages blocked unexpectedly
Guild messages blocked unexpectedly
- verify
groupPolicy - verify guild allowlist under
channels.discord.guilds - if a guild
channelsmap exists, only listed channels are allowed - verify
requireMentionbehavior and mention patterns
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:Require mention false but still blocked
Require mention false but still blocked
Common causes:
groupPolicy="allowlist"without matching guild/channel allowlistrequireMentionconfigured in the wrong place (must be underchannels.discord.guildsor a channel entry)- sender blocked by guild/channel
usersallowlist
Long-running Discord turns or duplicate replies
Long-running Discord turns or duplicate replies
Typical logs:
Slow listener detected ...stuck session: sessionKey=agent:...:discord:... state=processing ...
Gateway metadata lookup timeout warnings
Gateway metadata lookup timeout warnings
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.Gateway READY timeout restarts
Gateway READY timeout restarts
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.Permissions audit mismatches
Permissions audit mismatches
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 and pairing issues
DM and pairing issues
- DM disabled:
channels.discord.dm.enabled=false - DM policy disabled:
channels.discord.dmPolicy="disabled"(legacy:channels.discord.dm.policy) - awaiting pairing approval in
pairingmode
Bot to bot loops
Bot to bot loops
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 windowwindowSeconds: 60— sliding window lengthcooldownSeconds: 60— once the budget trips, every additional bot-to-bot message in either direction is dropped for one minute
channels.defaults.botLoopProtection, then override Discord when a legitimate workflow needs more headroom. Precedence is:channels.discord.accounts.<account>.botLoopProtectionchannels.discord.botLoopProtectionchannels.defaults.botLoopProtection- built-in defaults
maxEventsPerWindow, windowSeconds, and cooldownSeconds keys.Voice STT drops with DecryptionFailed(...)
Voice STT drops with DecryptionFailed(...)
- 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 detecteddiscord 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