OpenClaw Discord Integration: Bot Setup and Gateway Intents Explained

Overview

Discord integration lets you chat with OpenClaw through a Discord bot, supporting both DM (direct message) and guild text channel communication. This guide covers creating a bot, understanding Gateway Intents, configuring DM security policies, and setting up guild channel access control — all based on the official OpenClaw documentation .

Prerequisites

• OpenClaw installed and running
• A Discord account
• A Discord server where you have admin permissions (for testing)

How It Works

Before diving in, it helps to understand how OpenClaw routes Discord messages:

• DM conversations collapse into a shared session ( agent:main:main ) with pairing-based security by default.
• Guild channel conversations are isolated per channel, using the pattern agent:<agentId>:discord:channel:<channelId> .
• Group DMs are ignored by default but can be enabled via channels.discord.dm.groupEnabled .

The gateway auto-starts when a valid token exists and enabled is not false .

Step 1: Create a Discord Application

Go to Discord Developer Portal

1. Visit Discord Developer Portal
2. Click New Application
3. Enter a name (e.g., "OpenClaw Assistant")
4. Click Create

Set Up the Bot

1. In your application, go to the Bot tab
2. Click Add Bot → Yes, do it!
3. Under Token , click Copy to copy your bot token

Important: Treat your bot token as a password. Never share it publicly. If exposed, regenerate it immediately.

Step 2: Enable Privileged Gateway Intents

Gateway Intents control what events your bot receives from Discord. OpenClaw requires specific privileged intents to function properly.

Required Intents

| Intent | Purpose | Required | |--------|---------|----------| | Message Content Intent | Read message text in guild channels | Required — without it, the bot shows "Used disallowed intents" errors or connects but fails to respond | | Server Members Intent | Member lookups and allowlist matching | Recommended — needed for allowlist-based access control |

Enabling Intents in Developer Portal

1. Go to Bot tab in Developer Portal
2. Scroll to Privileged Gateway Intents
3. Enable MESSAGE CONTENT INTENT (mandatory)
4. Enable SERVER MEMBERS INTENT (recommended)
5. Click Save Changes

Note: Bots in 100+ servers need Discord verification to use privileged intents.

Step 3: Generate Bot Invite URL

Configure OAuth2

1. Go to OAuth2 → URL Generator

2. Select scopes:

   • bot
   • applications.commands (required for native slash commands)

3. Select bot permissions:

   • View Channels
   • Send Messages
   • Read Message History
   • Embed Links
   • Attach Files
   • Add Reactions (optional but recommended)
   • Use External Emojis (optional)

Warning: Avoid granting Administrator permission unless you are actively debugging. Grant only what is necessary.

4. Copy the generated URL

Invite the Bot

1. Open the URL in your browser
2. Select your test server
3. Click Authorize

Get Numeric IDs

Enable Developer Mode in Discord (User Settings → App Settings → Advanced → Developer Mode) so you can right-click to copy guild, channel, and user IDs — you will need these for configuration.

Step 4: Configure OpenClaw

Option A: Environment Variable

Set the token as an environment variable:

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"

Option B: Configuration File

Edit your OpenClaw configuration file with the token directly:

{
  channels: {
    discord: {
      enabled: true,
      token: "YOUR_BOT_TOKEN"
    }
  }
}

Note: When both an environment variable and a configuration file token exist, the configuration file takes precedence.

Option C: Multi-Account Support

For running multiple bot accounts:

{
  channels: {
    discord: {
      accounts: [
        { token: "BOT_TOKEN_1", name: "assistant-1" },
        { token: "BOT_TOKEN_2", name: "assistant-2" }
      ]
    }
  }
}

Step 5: Start and Test

Start or restart the OpenClaw gateway:

openclaw gateway restart

Check channel status:

openclaw channels status --probe

Run diagnostics if something seems wrong:

openclaw doctor

For initial DM contact, the bot uses a pairing system by default — the sender receives a time-limited code (expires in 1 hour) that must be approved before the conversation begins.

DM Security Policies

OpenClaw provides three DM access control policies:

Pairing (Default)

Unknown senders receive a time-limited pairing code that expires after 1 hour. The code must be approved before the conversation can proceed.

{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "pairing"
      }
    }
  }
}

Allowlist

Only configured user IDs or usernames can send DMs:

{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "allowlist",
        allowFrom: ["123456789012345678", "username#1234"]
      }
    }
  }
}

Open

Anyone can send DMs (use with caution):

{
  channels: {
    discord: {
      dm: {
        enabled: true,
        policy: "open",
        allowFrom: ["*"]
      }
    }
  }
}

Guild Channel Configuration

Basic Guild Access Control

Restrict the bot to specific guilds and channels with mention requirements:

{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          requireMention: true,
          channels: {
            "CHANNEL_ID": {
              enabled: true
            }
          }
        }
      }
    }
  }
}

Important: requireMention must be configured under the guild or channel level, not at the top-level Discord configuration.

Per-Channel Settings

You can configure allowlists and skill restrictions per channel:

{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          channels: {
            "CHANNEL_ID_1": {
              enabled: true,
              requireMention: true
            },
            "CHANNEL_ID_2": {
              enabled: true,
              requireMention: false
            }
          }
        }
      }
    }
  }
}

Configuration Parameters

Message Settings

| Parameter | Default | Description | |-----------|---------|-------------| | textChunkLimit | 2000 | Maximum characters per outbound message chunk | | chunkMode | — | Set to split on blank lines (paragraph boundaries) before applying length limits | | maxLinesPerMessage | 17 | Maximum lines per message | | mediaMaxMb | 8 | Maximum media file size in MB |

Context History

{
  channels: {
    discord: {
      historyLimit: 20  // Number of recent messages included as context (default: 20, set to 0 to disable)
    }
  }
}

Reply Threading

Native reply threading is off by default. Enable it with:

{
  channels: {
    discord: {
      replyToMode: "on"  // Enable native reply threading
    }
  }
}

Use reply tags in agent responses to control threading behavior:

• [[reply_to_current]] — reply to the message being handled
• [[reply_to:<message_id>]] — reply to a specific message

Reaction Notifications

Configure reaction event notifications per guild:

{
  channels: {
    discord: {
      guilds: {
        "GUILD_ID": {
          reactionNotifications: "own"  // Options: "off", "own", "all", "allowlist"
        }
      }
    }
  }
}

Tool Actions

The agent can invoke a discord tool to perform actions within Discord. Most actions are enabled by default, except roles and moderation which default to disabled.

Available Actions

| Category | Actions | |----------|---------| | Reactions | react, sticker, poll | | Messages | readMessages, sendMessage, editMessage, deleteMessage, searchMessages | | Threads | threadCreate, threadList, threadReply | | Pins | pinMessage, unpinMessage, listPins | | Channels | channelInfo, channelList | | Members | memberInfo, roleInfo, permissions | | Roles | roleAdd, roleRemove (disabled by default) | | Moderation | timeout, kick, ban (disabled by default) | | Other | emojiList, voiceStatus, eventList, eventCreate, setPresence |

Advanced Features

PluralKit Support

When enabled, OpenClaw resolves proxied messages to their underlying system members, displaying senders as "Member (PK:System)" to prevent accidental Discord pings.

Exec Approval Button UI

In DM conversations, OpenClaw can present exec approval buttons for interactive confirmation of tool actions.

Retry Configuration

Outbound API calls automatically retry on rate limits using Discord's retry_after header with exponential backoff. Configure retry behavior via channels.discord.retry parameters.

Troubleshooting

Bot is Online But Not Responding

1. Check Message Content Intent: Without this intent, the bot connects but cannot read message text. Go to Developer Portal → Bot → Privileged Gateway Intents and ensure MESSAGE CONTENT INTENT is enabled.

2. Verify channel permissions: Ensure the bot has View Channels and Send Messages permissions in the target channel.

3. Check mention requirements: If requireMention is enabled for the guild or channel, you must @mention the bot.

4. Check guild/channel allowlists: Verify the channel is not blocked by allowlist configuration.

"Used Disallowed Intents" Error

This means required intents are not enabled in the Developer Portal:

1. Go to Developer Portal → Bot → Privileged Gateway Intents
2. Enable MESSAGE CONTENT INTENT
3. Save and restart the OpenClaw gateway

DMs Not Working

1. Verify dm.enabled is not set to false
2. Check the DM policy — if set to "allowlist", ensure the user ID is included
3. If using "pairing" policy, check if the pairing code has expired (1-hour limit)

Diagnostic Commands

Use built-in diagnostic tools to identify issues:

# Run full diagnostics
openclaw doctor

# Check channel status with connection probe
openclaw channels status --probe

Best Practices

1. Treat bot tokens as passwords — use environment variables on supervised hosts, never commit tokens to source control.
2. Grant only necessary permissions — avoid Administrator unless actively debugging.
3. Use pairing or allowlist DM policies — the "open" policy should only be used for public-facing bots with appropriate rate limiting.
4. Enable Server Members Intent if using allowlist-based access control for more reliable member matching.
5. Use requireMention in busy guilds to prevent the bot from responding to every message.
6. Restart the gateway with --force if it gets stuck: openclaw gateway restart --force .

Next Steps

• WhatsApp integration guide
• Telegram integration guide
• Troubleshooting common errors