Debugging OpenClaw on Discord: application IDs, intents, and double messages

Discord is one of the more reliable channels for an OpenClaw agent because it has a real bot API backed by Discord's gateway, but the setup has a few sharp edges and a handful of bugs that recur across versions. Almost every Discord issue falls into one of a few buckets: the bot application is not configured the way OpenClaw expects, the bot cannot see message content, the gateway never reaches READY, replies are duplicated, or a dependency broke the WebSocket connection. The OpenClaw Discord channel docs cover pairing, guild allowlists, and multi account setups; this guide focuses on the failures people hit after that.

"Failed to resolve Discord application id"

This is the classic first run error (issue #2203). A Discord bot is an application you create in the Discord Developer Portal, and OpenClaw needs both the bot token and the application (client) ID to register slash commands and identify itself. The error almost always means the application ID is missing from your config, or you pasted the bot token where the app ID belongs.

In the Developer Portal, open your application, copy the Application ID from the General Information page, and copy the bot token from the Bot page. They are different values and both are required. Put them in your Discord channel config under channels.discord.applicationId and channels.discord.token (or per account under channels.discord.accounts), then restart the gateway. If you have more than one bot, double check you did not cross the token and ID from two different applications, which produces the same error.

For a fresh invite, use the OAuth2 URL generator in the portal: select the bot scope, pick permissions like View Channels, Send Messages, Read Message History, and open the generated URL to add the bot to your server. OpenClaw still needs the token and application ID in config separately; the invite URL only grants server membership.

Gateway error 4014 and the Message Content Intent

If the gateway logs show 4014 or Disallowed intent(s): MESSAGE_CONTENT, Discord rejected your connection because the bot requested an intent you did not enable in the portal. Discord documents privileged intents in the gateway intents guide. Message Content Intent is the one OpenClaw needs to read what people typed in server channels.

In the Developer Portal, open the Bot page and enable Message Content Intent under Privileged Gateway Intents. Enable Server Members Intent too if you use role or user allowlists in OpenClaw config. Save, restart the gateway, and confirm the bot reconnects without 4014.

Enabling it is what makes the bot work, and it is also the point where the bot starts receiving the full text of every message in the channels it can see, not only the ones that mention it. That is why the guild allowlist in the next section matters as much as the toggle does. Use it to keep the bot scoped to the channels and people you meant to include rather than every conversation on the server.

If the bot shows online but ignores messages in a channel, the cause is still often the intent (especially on servers with more than 100 members, where Discord enforces the privileged intent rule strictly). After enabling it, reinvite the bot or restart the gateway so the new intent takes effect. While you are there, confirm the bot was invited with permission to read and send messages in the specific channel. Discord's permissions reference explains how channel overwrites can block a bot that looks fine at the server level.

Silent in your server

OpenClaw defaults to a guild allowlist model. If you only set DISCORD_BOT_TOKEN without configuring channels.discord.guilds, runtime fallbacks may leave your server outside the allowlist even though DMs work after pairing. Add your guild ID under channels.discord.guilds with the channels and users you want, as shown in the Discord channel docs. The groups configuration guide explains how groupPolicy: "allowlist" interacts with per guild channel maps.

Common config shapes:

{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        YOUR_SERVER_ID: {
          requireMention: true,
          users: ["YOUR_USER_ID"],
        },
      },
    },
  },
}

If the bot responds when @mentioned but ignores plain messages, requireMention: true is doing its job. Set requireMention: false for that guild if you want always on replies, which works best when the server is just you or a circle that all expects the agent to be listening. On a busier server it means the agent reads and may act on every message posted, so most people leave the gate on and widen the users list above to cover who should be able to call the bot instead.

For DMs, complete the pairing flow: send the bot a DM, approve the code with openclaw pairing approve discord CODE, and check channels.discord.dmPolicy if DMs stay blocked.

Stuck at "awaiting gateway readiness"

A distinct failure mode is the bot logging client initialized as …; awaiting gateway readiness and never reaching logged in to discord. This tracked to a race in the @buape/carbon Discord client OpenClaw uses: the gateway plugin's async registerClient was not awaited, so Identify could be dropped while metadata fetches were still in flight (#56492). Raw WebSocket tests from the same machine can succeed in under a second while Carbon hangs, which tells you the token and network are fine and the bug is in client lifecycle (#77668).

Update to a build that includes the gateway heartbeat scheduler fix on main (commit b5c33bc204 per #77668). Restart the gateway and run openclaw channels status --probe. If you are blocked on an older release, some users reported that starting the gateway with verbose logging changed timing enough to complete the handshake; treat that as a temporary workaround, not the fix.

Duplicate replies

Duplicate messages are a recurring Discord complaint, and there are a couple of distinct causes. The cleanest one to rule out is running the bot twice: if a background gateway service is already connected and you also start one by hand, both answer every message. Check with openclaw gateway status and stop the duplicate.

Beyond that, there are genuine open bugs in this area, including generated images double sending attachments after a media handoff (#88307) and tool progress lines leaking into Discord output in certain states (#88341). OpenClaw's Discord streaming mode (channels.discord.streaming) edits a single preview message for tool progress by default; misconfigured streaming or an older delivery bug can look like duplicate replies. Run openclaw doctor --fix to normalize legacy streaming keys, then update if duplicates persist after ruling out two gateways.

Install fails with "Cannot find module"

Discord support is a plugin, and its dependencies are a common reason a version bump fails to install. A recent example was the install breaking with Cannot find module '@buape/carbon' (issue #62994), where the Discord extension's package did not resolve cleanly during install. When this happens, the fix is usually to reinstall on a current release rather than patch the dependency by hand, since these are corrected upstream quickly. If you are wiring Discord into a fresh box, the broader install troubleshooting guide covers the Node and module errors that hit at this stage.

WebSocket breaks after an update

If your Discord bot suddenly drops its connection, one open issue to check is ws version 8.21.0, which breaks the Discord gateway WebSocket under Node 22 (#88330). This is the kind of break that looks like your config rotted when nothing of yours changed. If Discord connectivity died right after an update and the logs point at the WebSocket layer, this is a candidate, and the resolution is a version where the dependency is pinned correctly, so update once a fix lands rather than downgrading Node.

Debugging order

When Discord misbehaves, walk this sequence. If the bot never starts, fix application ID and token first, then check for 4014 in logs and enable Message Content Intent. If the bot is online but silent in a server, check guild allowlist and requireMention before you touch model config.

If logs stall at awaiting gateway readiness, update for the Carbon lifecycle fix. If every message gets two replies, check for duplicate gateway processes, then update for known delivery bugs. openclaw channels status --probe and openclaw logs --follow belong in every pass.

That order saves time because Discord surfaces the same symptom for different root causes. A missing intent and a missing guild allowlist both look like "the bot ignores me."

The managed option

The Developer Portal steps are not hard, but they are a detour: create an application, copy two different secrets, flip a privileged intent, invite the bot with the right scopes, configure guild allowlists, and keep the plugin's dependencies installing cleanly through every update. If you would rather not do that, Operator.io runs OpenClaw with Discord connected as a managed channel, so you skip the application ID, the intent toggles, and the plugin install, and the agent is reachable in Discord from the start. You can try it free and skip the portal entirely, or work back through the fixes above to get your own bot connected.