OpenClaw Discord troubleshooting

Discord failures come with better logs than most channels, and the OpenClaw docs match each symptom to the setting or log line behind it. Here is the list in the docs' order: intents, blocked guild messages, mention settings, long turns, gateway timeouts, permission audits, DMs, bot loops, and voice decryption.

Intents, guilds, mentions

• A disallowed-intents error or a bot that sees no guild messages means enabling Message Content, enabling Server Members when you depend on user or member resolution, and restarting the gateway after changing intents.
• For a guild message blocked unexpectedly, verify the group policy, the guild allowlist under the guilds map, that only listed channels are allowed once a channels map exists, and the mention requirement and patterns; the Control UI channel details and the channels status command warn when the effective policy is allowlist with no guilds configured, an explicit default-account guilds map overrides the top-level map even when empty, and the useful checks are the doctor, the status probe and the logs.
• If status reports a deferred configuration reload, wait for active work to finish and refresh: a successful channel stop and start does not apply unpublished configuration, the warning distinguishes waiting to publish from work deferred after publication, and connection health alone never confirms that a policy change applied.
• When the mention requirement is off but messages are still blocked, the common causes are an allowlist group policy without a matching guild or channel entry, the mention requirement set outside the guilds map or a channel entry, and a sender blocked by a guild or channel user allowlist.

Discord does not apply a channel-owned timeout to queued agent turns.

Turns, timeouts, audits, DMs

Long-running turns or duplicate replies show up as slow-listener and stuck-session logs; message listeners hand off immediately and queued Discord runs preserve per-session ordering until the session, tool or runtime lifecycle completes or aborts the work, because Discord applies no channel-owned timeout to queued turns. OpenClaw fetches the gateway bot metadata before connecting, transient failures fall back to Discord's default gateway URL with rate-limited logs, and the metadata timeout defaults to 30 seconds with an environment override for unusual hosts. It also waits for the gateway READY event at startup and after runtime reconnects, 15 seconds at startup and 30 on reconnect, with two environment overrides for multi-account setups whose startup staggering needs a longer window. The status probe's permission checks only work for numeric channel IDs, so slug keys still match at runtime but cannot be fully verified. For DM and pairing issues, check that DMs are enabled, that the DM policy is not disabled through the current or legacy key, and whether a pairing approval is still pending in pairing mode.

Bot loops and voice

• Bot-authored messages are ignored by default; if you enable bot acceptance, use strict mention and allowlist rules, and prefer the mentions mode that accepts only bot messages mentioning the bot, where reply-ping metadata alone does not count and a native mention or a configured text or transcript mention outside Markdown code is required.
• Whenever bot acceptance lets bot messages reach dispatch, Discord maps each event to an account, channel and bot-pair fact and the shared pair guard suppresses the pair once it crosses the budget, 20 events per 60-second sliding window with a 60-second cooldown that drops every further message in either direction, which stops runaway two-bot loops that Discord rate limits used to end and leaves single bots and one-shot replies alone; the default lives under the channel defaults with Discord-wide and per-account overrides taking precedence, and the docs' example lets one account listen only when mentioned while another listens to all bots with a mention alias for its partner and a tighter five-message budget with a 90-second cooldown.
• Voice speech-to-text drops with a decryption failure need OpenClaw 2026.2.24 or newer, the release that added the voice receive recovery logic, DAVE encryption left at its default of true, a decryption failure tolerance starting at the upstream default of 24 and tuned only if needed, and a watch on the logs for detected DAVE decrypt failures and the rejoin attempt, with logs collected and compared against the upstream discord.js history if failures continue after the automatic rejoin.

OpenClaw on Discord is the channel post these symptoms belong to, and OpenClaw Discord access control the allowlist layers behind most blocked messages.

Health is not policy

The deferred-reload note is the subtle one: a connected bot can still be running yesterday's policy, so the fix for a blocked message is sometimes to wait for the publication rather than to change anything. OpenClaw bot loop protection explains the shared pair guard the bot-loop budget belongs to, and OpenClaw Discord voice channels the voice channel features that the decryption fix protects.

On Diali

On Diali the Discord channel is connected from the dashboard and the runtime config is generated and replaced at each release, so the gateway, timeout and policy checks here are mostly ours to watch on the hosted side, while the intents, permissions and server settings stay on yours. Discord on Diali is the channel on Diali and Diali security the boundary that applies to every connected channel.

• Enable the intents, then restart; a connected bot can run stale policy.
• Mention settings live under guilds or a channel entry, nowhere else.
• Bot loops trip at 20 events a minute and cool down for a minute.