OpenClaw Discord Channel Health Check: Pairing Is Not Delivery

May 2, 2026 · Tutorial

The bot is visible in the server. A Discord DM may even have produced an OpenClaw pairing code. Then you mention the bot in a guild channel and nothing comes back. It is tempting to regenerate the token or repeat the invite. That usually tests the wrong layer.

OpenClaw uses pairing for inbound DM access. Guild delivery has its own policy: the server must be allowed, the channel may need to be listed, the sender may be filtered, and the message may need an explicit bot mention. A connected Discord gateway can therefore coexist with a silent channel. The OpenClaw pairing documentation says that approving a DM grants direct-message access only; it does not grant group access.

This tutorial follows that boundary through setup, a narrow test, live checks, logs, routing, and recovery. The commands and expected results come from documentation opened on September 13, 2026. No local Gateway was run, so the acceptance test is a procedure for your instance, not a claimed hands-on result.

Before you start

• Have shell access to the machine running the OpenClaw Gateway, using the profile and account that own the Discord connection.
• Use a private test server or an unused channel where permission overwrites can be changed safely. Discord's bot guide recommends testing a server-installed app away from active users.
• Be able to install an app in the target server. Discord says a server-installed app must be authorized by a member with MANAGE_GUILD.
• Keep the bot token in a password manager or server-only environment variable. Discord treats tokens like passwords; OpenClaw says not to send one in chat.
• Enable Developer Mode and collect your user ID, server ID, and one numeric test-channel ID. Numeric IDs matter because OpenClaw's permission probe cannot fully audit slug-based channel keys.

Use one acceptance condition: after the Gateway restart, your user mentions the bot in the chosen channel and the bot replies in that same channel. A green status line is useful evidence, but it is not this test.

Connect Discord in a controlled order

1. Create the application and bot

In the Discord Developer Portal, create an application and open its Bot page. Enable Message Content Intent for normal guild messages. Enable Server Members Intent if OpenClaw must resolve members or roles, use role allowlists, or use a channel-audience access group. Presence Intent is optional for presence updates. These requirements appear in OpenClaw's Discord setup guide and Discord's Gateway intent reference.

Enable only the intents the configuration needs. If an intent changes, restart the Gateway; the Discord troubleshooting page calls out that restart.

2. Install the bot with least privilege

Use the Discord OAuth2 install link with the bot and applications.commands scopes. OpenClaw lists View Channels, Send Messages, Read Message History, Embed Links, and Attach Files as the baseline for normal text channels. Add Send Messages in Threads for thread or forum workflows. Discord's OAuth2 and permissions documentation separates app scopes from the server and channel permissions granted after installation.

Check the bot's role and the test channel's permission overwrites. A channel-level deny can override a server-level allow, so OpenClaw cannot fix a Discord permission overwrite from its own configuration.

3. Give OpenClaw a readable token

The documented setup path uses an environment-backed SecretRef. Keep the dry run; it catches a malformed patch before changing active configuration.

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
cat > discord.patch.json5 <<'JSON5'
{
  channels: {
    discord: {
      enabled: true,
      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" }
    }
  }
}
JSON5
openclaw config patch --file ./discord.patch.json5 --dry-run
openclaw config patch --file ./discord.patch.json5
openclaw gateway

A managed service may not inherit your shell. The setup guide says to install it from a shell where the variable is set or store it in ~/.openclaw/.env. Do not commit the token or put it in a patch file that will be shared.

4. Pair the DM, then stop calling that guild access

With the Gateway running, DM the bot. The default setup returns a pairing code. The pairing page documents this channel-name command pattern and lists Discord as supported:

openclaw pairing list discord
openclaw pairing approve discord <CODE>

Use --account <id> for multiple Discord accounts. Approval allows that user to converse in DMs; it does not add a server to the guild allowlist or override groupPolicy, channel maps, or sender filters.

5. Allow one guild and one channel

For the first guild test, keep the policy narrow and require a mention. Use IDs so the same values can be checked in Discord and by OpenClaw's probe:

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

The Discord access-control reference documents this boundary. A guild channel map is an allowlist: unlisted channels are denied. Without that map, all channels in the allowlisted guild are allowed. The users list is an additional sender gate.

Apply the configuration and restart or reload the Gateway using your existing service method. Test only after the new policy is active. Start with an explicit mention rather than opening ambient replies while you diagnose.

Make the first test explicit

In the chosen channel, mention the bot in a short message. As a diagnostic model, this checks the smallest useful path: Discord emits the message, the bot can see the channel, OpenClaw accepts the guild and sender, mention gating passes, an agent is selected, and the reply returns to Discord.

If that works, test an unmentioned message only if you want ambient replies. Set requireMention: false under the relevant guild or channel entry, not at an unrelated root level. Do not use another bot as the only test: OpenClaw ignores bot-authored messages by default. If bot messages are intentional, the troubleshooting docs recommend stricter mention and allowlist controls such as allowBots: "mentions".

Run the health checks in order

Run the read-only checks, then keep the log stream open while sending the mention. The channels CLI reference, health reference, and logs reference define these command boundaries.

For this symptom, use openclaw channels status --probe --channel discord, then openclaw health --verbose, then openclaw logs --follow --local-time during the mention test. The general troubleshooting guide separates runtime, connectivity, capability, sender approval, and log evidence.

Read the failure as a layer

The channel is configured but not running

If status reports running: false, lifecycle: blocked, or a plugin-load error, the problem is below Discord permissions. Run openclaw doctor, repair the reported dependency or plugin issue, restart, and probe again. After an update, openclaw doctor --fix may be appropriate for stale configuration or plugin state. Save the current configuration before applying it.

The transport is connected but guild messages are blocked

Check the effective account configuration:

• groupPolicy must allow the guild.
• The server ID must be under channels.discord.guilds, or the account-specific guild map if it overrides the root.
• If a channels map exists, the test channel must be listed.
• The sender must pass configured users or roles filters.
• requireMention must be checked at the guild or channel level.

drop guild message (mention required points to mention gating. blocked or allowlist points to an access rule. Inspect IDs before disabling filtering; the block is often the useful evidence.

Discord sees the bot, but OpenClaw sees no usable guild message

Check Message Content Intent. Discord says it controls access to message content fields and documents Gateway close code 4014 for an unconfigured or unapproved privileged intent. OpenClaw calls the intent required for normal guild messages. Server Members Intent matters for user or role resolution. Enable only what is needed, restart, and repeat the explicit mention test.

A mention is still a useful narrow diagnostic because Discord documents an exception for messages that mention the app. It does not prove that unmentioned ambient messages will work.

The logs show typing or token usage, but no Discord post

Check whether the room uses messages.groupChat.visibleReplies: "message_tool". In that mode, the agent may observe an event and post only through the message tool. For ordinary requests, use visibleReplies: "automatic" unless quiet observation is deliberate. A tool-only room also needs an agent profile that includes the message tool. This is a reply-policy issue, not a Discord transport repair.

The probe disagrees with a channel that appears to work

OpenClaw says permission checks in channels status --probe require numeric channel IDs. Slug keys may work at runtime without being fully probeable. Use Developer Mode to collect the numeric ID and rerun the probe; record a slug audit mismatch as a probe limitation, not proof that Discord is broken.

The DM works, but the reply reaches the wrong place

Inspect routing after access has passed. OpenClaw's channel-routing documentation says replies return to the channel where the message arrived. In a multi-account setup, set an explicit default account. The agent-bindings documentation says bindings choose an agent after channel access has been accepted; they do not grant Discord access.

Apply a fix, then verify it was published

After editing the guild or channel map, rerun the dry-run patch, restart the Gateway, and repeat the same explicit mention test. If the Discord troubleshooting page reports a deferred configuration reload, wait for active work to finish and refresh status. A successful stop or start does not prove that an unpublished policy change is active.

If the change made the channel worse, reapply the last known-good configuration instead of deleting the whole Discord block. A guild access rollback is separate from DM pairing. If the token appeared in a transcript, patch file, or shared log, regenerate it from Discord's Bot page, update the environment or SecretRef, restart, and repeat the health check.

The short diagnosis

Ask four questions in order: is the Gateway live, can Discord deliver a readable message, does OpenClaw allow this guild/channel/sender, and does the selected agent have a visible reply path? channels status --probe, health --verbose, the logs, and one explicit mention answer those questions without turning every silent channel into a token reset.

Sources

1. OpenClaw: Discord setup. Accessed 2026-09-13.
2. OpenClaw: Discord access control. Accessed 2026-09-13.
3. OpenClaw: Discord troubleshooting. Accessed 2026-09-13.
4. OpenClaw: Channel troubleshooting. Accessed 2026-09-13.
5. OpenClaw: General troubleshooting. Accessed 2026-09-13.
6. OpenClaw CLI: channels. Accessed 2026-09-13.
7. OpenClaw CLI: health. Accessed 2026-09-13.
8. OpenClaw CLI: logs. Accessed 2026-09-13.
9. OpenClaw: Pairing. Accessed 2026-09-13.
10. OpenClaw repository: Channel routing. Accessed 2026-09-13.
11. OpenClaw repository: Agent bindings. Accessed 2026-09-13.
12. Discord: OAuth2 and permissions. Accessed 2026-09-13.
13. Discord: Gateway and privileged intents. Accessed 2026-09-13.
14. Discord: Building your first Discord bot. Accessed 2026-09-13.