Setting Up OpenClaw as a Discord Bot: Full Configuration Guide (2026)

ByL.B. Kaelin

Setting Up OpenClaw as a Discord Bot: Full Configuration Guide (2026)

Discord servers have become the de facto communication layer for communities, development teams, and AI enthusiasts. Adding an OpenClaw-powered bot turns that server into something more than a chat room. You can query your own documents, orchestrate multi-agent workflows, run scheduled tasks, and build custom automations that respond to natural language in real time.

The openclaw discord bot setup 2026 process requires a Discord application and bot token from the Developer Portal, configuration in your openclaw.json file, and careful attention to permissions and intents. This guide walks through every step, from creating the bot application to testing the connection. By the end, you will have a working Discord bot backed by OpenClaw’s agent infrastructure.

Prerequisites for OpenClaw Discord Bot Setup

Before you begin, make sure you have the following:

  • An OpenClaw instance. The instructions assume OpenClaw is already installed and running. If you need installation help, the OpenClaw docs cover setup on Linux, macOS, and Docker.
  • Discord server ownership or admin permissions. You need the “Manage Server” permission to add a bot to a server. Using a private test server is recommended for the initial setup.
  • Your server’s Guild ID. Enable Developer Mode in Discord settings (Advanced tab), then right-click your server name and select “Copy ID.” Save this value; you will need it in Step 4.
  • Basic familiarity with JSON editing. The OpenClaw configuration file uses JSON. A mis-placed comma will break the config.

Step 1: Create Your Discord Application and Bot

Every Discord bot starts as an application registered on the Discord Developer Portal. This is where you generate the bot token that OpenClaw uses to authenticate.

  1. Go to the Discord Developer Portal and log in with your Discord account.
  2. Click the blue “New Application” button in the top-right corner.
  3. Give the application a name (this will appear as your bot’s username once added to a server). For example, “My OpenClaw Bot.” Accept the terms and click “Create.”
  4. In the left sidebar, click “Bot” under Settings.
  5. Click “Add Bot” and confirm. You will now see the bot’s avatar, username, and token.
  6. Under the “Token” section, click “Reset Token” or “Copy” to retrieve your bot token. Copy this token and save it securely. You will never be able to see the full token again once you navigate away from this page. Keep it in a password manager, vault, or environment variable file. If you lose it, you will need to regenerate it.

The Discord Developer Portal calls this a token, but it functions as both a username and password for your bot. Treat it accordingly.

Step 2: Configure Bot Permissions and Intents

With the bot created, you need to configure two things: Privileged Gateway Intents and the OAuth2 permission scope. Getting either wrong is the most common cause of a bot that appears online but never responds.

Enable the Message Content Intent

On the Bot settings page, scroll down to the “Privileged Gateway Intents” section. You will see three toggles:

  • Presence Intent – Only needed if your bot monitors user presence status (online, idle, DND). Not required for basic operation.
  • Server Members Intent – Only needed if your bot tracks member join/leave events. Not required for basic operation.
  • Message Content Intent – Required. This must be enabled for OpenClaw to read the content of messages sent in your server. Without this intent, your bot can see that a message was sent but cannot see what it says.

Toggle “Message Content Intent” to ON. Click “Save Changes” at the bottom of the page.

Discord restricted this intent in 2022 to reduce data scraping. Only verified bots with a legitimate need are approved for more than 100 servers. For a personal or small-team bot, the toggle works immediately with no verification needed.

Configure the OAuth2 URL (Permissions)

You specify what your bot can do via the OAuth2 URL generator. This determines the permission integer and the scope that Discord applies when the bot joins a server.

  1. In the left sidebar, click “OAuth2” then “URL Generator.”
  2. Under “Scopes,” check the box for bot and optionally applications.commands if you plan to use slash commands.
  3. Under “Bot Permissions,” select the following permissions. These are the minimum needed for OpenClaw to function properly:
Permission Why It Is Needed
Send Messages The bot must be able to reply to users.
Read Message History Required for OpenClaw to see past messages in the channel.
Add Reactions OpenClaw uses reactions for status indicators and confirmation prompts.
Use Slash Commands If you plan to register custom slash commands for OpenClaw.
Embed Links Allows the bot to send rich link previews and embedded content.
Attach Files Needed if OpenClaw will send files (logs, documents, images).

Do not check “Administrator.” The principle of least privilege means your bot should have exactly the permissions it needs to function and nothing more. An Administrator-level bot is a single configuration mistake away from being a severe security liability.

The permission integer at the bottom of the page will auto-calculate as you check boxes. Save the generated URL; you use it in Step 3.

Step 3: Add the Bot to Your Server

With the OAuth2 URL generated, adding the bot to your Discord server takes one click.

  1. Copy the URL from the OAuth2 URL Generator. It will look something like: https://discord.com/oauth2/authorize?client_id=123456789&permissions=68608&scope=bot
  2. Paste it into a browser tab and navigate to it.
  3. Select the server you want to add the bot to from the dropdown. You must have “Manage Server” permission on that server.
  4. Click “Continue,” review the permissions, then click “Authorize.”
  5. Complete the CAPTCHA if prompted.

You should now see the bot appear in your server’s member list, usually in the “Offline” section until OpenClaw connects to it.

If you need to add the bot to additional servers later, you can generate a new OAuth2 URL at any time with the same permissions.

Step 4: Configure OpenClaw for Discord

This is where OpenClaw learns about your Discord bot. Everything goes into the OpenClaw configuration file, typically named openclaw.json.

Locating the Config File

The default location depends on your installation:

  • Linux/macOS: ~/.openclaw/openclaw.json or $XDG_CONFIG_HOME/openclaw/openclaw.json
  • Docker: The path mapped to the config volume during container setup
  • Custom: Wherever your OPENCLAW_CONFIG_DIR environment variable points

If you do not have a channels section in your config, you will add one. If you already have other channels configured (Telegram, Slack), you will add a Discord entry alongside them.

The Discord Channel Configuration

Open the openclaw.json file in a text editor and locate or create the "channels" array inside the configuration object. Add a new entry for Discord with the following structure:

{
  "channels": [
    {
      "type": "discord",
      "name": "my-server-bot",
      "token": "YOUR_BOT_TOKEN",
      "guild": "YOUR_GUILD_ID",
      "filter": {
        "allow": [
          "channel-id-1",
          "channel-id-2"
        ]
      }
    }
  ]
}

Replace the placeholders:

  • YOUR_BOT_TOKEN – The token you copied from the Discord Developer Portal. Keep this in quotes.
  • YOUR_GUILD_ID – The server ID you copied in the prerequisites. This ensures OpenClaw connects to the correct server.
  • channel-id-1, channel-id-2 – The Discord channel IDs where OpenClaw should listen and respond. To get a channel ID, right-click the channel in Discord (Developer Mode must be enabled) and select “Copy ID.”

If you want OpenClaw to respond to any channel it has access to, omit the "filter" block entirely. For most setups, channel filtering is strongly recommended to prevent the bot from processing message traffic in general or off-topic channels.

Restart OpenClaw

After saving the configuration file, restart OpenClaw for the changes to take effect:

openclaw gateway restart

Check the gateway logs to confirm the Discord plugin loaded successfully:

openclaw gateway logs --tail

You should see a log line indicating the Discord channel plugin has connected. If you see an authentication error, double-check the token and guild ID.

Step 5: Test and Verify

Once OpenClaw restarts, the bot should appear online in your Discord server. Test it with a simple message in one of the allowed channels.

  1. Open Discord and navigate to a channel that OpenClaw is configured to listen to.
  2. Send a message mentioning the bot or asking a question. For example: @MyOpenClawBot what time is it?
  3. The bot should respond within a few seconds. If it does, your setup is working.

What to Check If the Bot Does Not Respond

  • Is the bot online? Check the member list in Discord. If it shows “Offline,” OpenClaw is not connected. Verify the token and guild ID in openclaw.json and check gateway logs.
  • Is Message Content Intent enabled? This is the most common issue. Go back to the Discord Developer Portal, Bot settings, and verify the Message Content Intent toggle is ON and you clicked “Save Changes.”
  • Is the channel allowed? If you used a filter.allow list, confirm the channel ID is correct and the bot has permission to read and send messages in that channel.
  • Are there rate limit issues? If you made many API calls quickly during testing, Discord may be rate-limiting the bot temporarily. Wait 30 seconds and try again.

Useful Discord Bot Configurations

Once the basic connection works, you can tailor OpenClaw’s Discord behavior with these configuration options.

Channel Filtering

The "filter" block supports both allow and deny lists:

"filter": {
  "allow": ["general-channel-id"],
  "deny": ["bot-spam-id"]
}

If only allow is specified, OpenClaw responds only in those channels. If only deny is specified, OpenClaw responds everywhere except the denied channels. Using both at once is valid; the deny list takes precedence if a channel appears in both.

This is especially useful in large servers where you want OpenClaw available in dedicated bot channels without cluttering general discussion.

Thread-Bound Sessions

For multi-turn conversations, OpenClaw supports persistent Discord thread sessions. When you spawn a session with thread support, OpenClaw creates a dedicated thread for each conversation rather than continuing in the main channel.

In OpenClaw’s ACP harness configuration (used when setting up custom agent workflows), add thread: true to the sessions_spawn configuration:

"sessions_spawn": {
  "discord": {
    "thread": true,
    "auto_close_minutes": 60
  }
}

With threads enabled, each user conversation gets its own thread under the original message. This keeps long-running agent interactions organized and prevents wall-of-text pollution in main channels.

DM Mode

OpenClaw can also respond to direct messages. If the bot has DM access to a user, they can message the bot privately. This is useful for one-on-one assistant interactions that do not belong in a public channel. No special configuration is needed for DMs; the bot responds to any message it can read as long as the channel plugin is connected.

Rate Limits and Scale Considerations

Discord enforces API rate limits that affect how OpenClaw behaves at scale. Understanding these limits will save you debugging time later.

Global Rate Limit

All bots are subject to a global rate limit of 50 API requests per second. OpenClaw’s Discord plugin respects this limit internally, but if you have custom integrations or scripts that make additional API calls, you may hit it. The API responds with a 429 Too Many Requests status and includes a Retry-After header when you do.

Per-Channel and Per-Guild Limits

In addition to the global limit, Discord throttles by resource. Sending messages to the same channel too quickly can trigger a per-channel cooldown. OpenClaw queues outgoing messages to avoid this, but high-frequency reply scenarios (polling, bulk announcements) can cause visible delays.

Practical Scaling

  • Single server, moderate use: OpenClaw with Discord handles this comfortably. You are unlikely to notice rate limits.
  • Multiple servers: Each guild requires a separate entry in the channels array with its own guild ID and optional filter configuration. OpenClaw multiplexes across them, but the total API call volume adds up.
  • Heavy automation: If OpenClaw is running scheduled tasks that post to Discord frequently (every few seconds), batch your messages or use webhooks instead of per-message API calls.
  • Agent-driven workflows: When multiple subagents or ACP sessions reply in Discord simultaneously, message ordering is not guaranteed. Consider thread sessions to keep conversations isolated.

Security: Protecting Your Bot Token

The bot token is the single credential that authenticates your bot to Discord. If someone obtains it, they can connect their own client as your bot, read messages in every channel the bot has access to, and send messages as your bot.

Token Storage Best Practices

  • Never commit the token to a git repository. Add openclaw.json to your .gitignore file or use environment variables for sensitive fields.
  • Use environment variable substitution. OpenClaw supports ${DISCORD_BOT_TOKEN} syntax in openclaw.json for reading values from environment variables. Set the variable in your shell profile or systemd environment file instead of hardcoding the token.
  • Restrict file permissions. If you store the token in openclaw.json, set the file to readable only by the user running OpenClaw: chmod 600 ~/.openclaw/openclaw.json.
  • Use a secrets manager. For production deployments, consider HashiCorp Vault, AWS Secrets Manager, or Bitwarden Secrets Manager with OpenClaw’s secrets provider.

If Your Token Is Exposed

If you accidentally commit a token to a public repo or share it in a log file:

  1. Go to the Discord Developer Portal, Bot settings page.
  2. Click “Reset Token.” This immediately invalidates the old token.
  3. Update openclaw.json with the new token.
  4. Restart OpenClaw.
  5. Investigate how the token was exposed to prevent recurrence.

A bot token cannot be used to access your personal Discord account or any servers the bot has not been added to, but within the servers the bot inhabits, it has all the permissions you granted it. Act quickly.

Troubleshooting Common Issues

Even with careful setup, things can go wrong. Here are the most common problems and their fixes.

Bot Shows Online but Does Not Respond

This is almost always the Message Content Intent. Confirm it is enabled in the Discord Developer Portal under Bot settings. If you enabled it after the bot was already running, restart OpenClaw. The intent toggle does not take effect retroactively; the bot must re-establish its WebSocket connection.

Bot Does Not Appear in the Channel Member List

OpenClaw is either not running, not connected to Discord, or the bot was not properly invited to the server. Check three things:

  • Is OpenClaw running? Run openclaw gateway status.
  • Is the token correct? A mismatch causes an authentication failure at connection time.
  • Is the guild ID correct? If OpenClaw connects to a different server than expected, the bot will appear online in that server but not yours. Use the URL-based invite to add the bot to the correct server.

Bot Responds in Wrong Channels

The filter block is either missing or configured incorrectly. Review the channel IDs in your filter.allow array. Channel IDs are numeric strings between 17 and 19 digits. If you accidentally copied a message ID or user ID instead of a channel ID, the filter will not match any channel and the bot may respond everywhere (if no allow list exists) or nowhere (if an allow list exists with incorrect IDs).

Errors in Gateway Logs

Common log messages and their meanings:

  • "Failed to authenticate with Discord" – Token is invalid, expired (after reset), or belongs to a different bot application.
  • "Guild not found" – The guild ID does not match any server the bot has been added to. Verify the ID and that the bot invitation was completed.
  • "Rate limited, backing off" – Normal. OpenClaw handles backoff automatically. If this appears frequently, reduce the volume of outgoing messages.

Slash Commands Do Not Work

If you configured OpenClaw with slash command support but the commands do not appear in Discord:

  • Confirm applications.commands was checked in the OAuth2 scopes when you generated the invite URL.
  • Re-invite the bot to the server using a URL that includes the applications.commands scope.
  • Slash command registration can take up to an hour to propagate to all servers. On the first invite, it usually registers within a minute.

Sources

Related Reading

Similar Posts