Discord Bot Setup

Set up a Discord bot to interact with OpenClaw via Discord.

Discord uses the official Discord Bot API - create a bot application and get a bot token.

Prerequisites

A Discord account
Ability to create Discord applications
A Discord server (guild) for testing

Create Discord Bot Application

Go to Discord Developer Portal: https://discord.com/developers/applications
Create New Application:
- Click "New Application"
- Name: OpenClaw Bot (or your preferred name)
- Click "Create"
Create Bot User:
- Go to Bot section (left sidebar)
- Click "Add Bot" → "Yes, do it!"
- Copy the Bot Token (save it securely)

Enable Required Intents

MESSAGE CONTENT INTENT is required! Without it, the bot cannot read message content and won't respond to any messages.

Stay in Bot section
Scroll to "Privileged Gateway Intents"
Enable MESSAGE CONTENT INTENT (required!)
Enable SERVER MEMBERS INTENT (recommended)
Click "Save Changes"

Generate Bot Invite URL

Go to OAuth2 → URL Generator
Select Scopes:
- bot
- applications.commands
Select Bot Permissions:
- View Channels
- Send Messages
- Read Message History
- Embed Links
- Attach Files
- Add Reactions
Copy the generated URL

Invite Bot to Server

Open the generated URL in your browser
Select your test server
Click "Authorize"
Complete the captcha if prompted

Get Discord IDs

Discord uses numeric IDs for servers, channels, and users.

Enable Developer Mode

Discord → User Settings → Advanced
Enable Developer Mode

Copy IDs (right-click and select "Copy ID"):

Server ID: Right-click server name → Copy Server ID
Channel ID: Right-click channel (e.g., #general) → Copy Channel ID
Your User ID: Right-click your username → Copy User ID

Add Discord Configuration

Set environment variable:

~/.openclaw/.env

# Discord Bot Token
DISCORD_BOT_TOKEN=YOUR_BOT_TOKEN_HERE

Update configuration file ~/.openclaw/openclaw.json:

{
  "channels": {
    "discord": {
      "enabled": true,
      "dm": {
        "enabled": true,
        "policy": "allowlist",
        "allowFrom": ["123456789012345678"]
      },
      "groupPolicy": "allowlist",
      "guilds": {
        "987654321098765432": {
          "requireMention": false,
          "users": ["123456789012345678"],
          "channels": {
            "111222333444555666": {
              "allow": true,
              "requireMention": false
            }
          }
        }
      }
    }
  },
  "plugins": {
    "entries": {
      "discord": {
        "enabled": true
      }
    }
  }
}

Replace with your IDs:

YOUR_BOT_TOKEN_HERE - Your Discord bot token
123456789012345678 - Your Discord user ID
987654321098765432 - Your server (guild) ID
111222333444555666 - Your channel ID

Configuration Options

Field	Description	Default
`dm.enabled`	Enable direct message support	`true`
`dm.policy`	Access control: `allowlist`, `pairing`, `open`, `disabled`	`pairing`
`dm.allowFrom`	Discord user IDs allowed to DM	`[]`
`groupPolicy`	Server channel policy: `allowlist`, `open`, `disabled`	`allowlist`
`guilds.<id>.requireMention`	Require @mention to respond in server	`true`
`guilds.<id>.users`	User IDs allowed in this server	`[]`
`guilds.<id>.channels.<id>.allow`	Allow bot in this channel	`false`
`guilds.<id>.channels.<id>.requireMention`	Require mention in this channel	`true`

Mention vs No-Mention Mode

With `requireMention: true` (Recommended)

Bot only responds when @mentioned:

@YourBot hello

Prevents bot from responding to every message
Better for multi-user servers
Recommended for shared channels

With `requireMention: false` (Testing Only)

Bot responds to every message in allowed channels.

Can be noisy in active channels
Good for private testing channels

Verify Setup

Start Gateway

cd /path/to/aiq-openclaw
export DISCORD_BOT_TOKEN=YOUR_TOKEN
node scripts/run-node.mjs gateway

Expected Log Output

[discord] [default] starting provider (@YourBot)
[discord] logged in to discord as 1234567890123456789

Check Status

pnpm openclaw channels status --probe

Expected output:

Discord default: enabled, configured, running, works

Test Discord Bot

Test in DM

Find bot in server member list
Click bot → "Message"
Send: Hello ArmorIQ!
Bot should respond (if your user ID is in allowlist)

Test in Server Channel

Go to configured channel
If requireMention: false, send: hello
If requireMention: true, send: @YourBot hello
Bot should respond

Troubleshooting

Bot doesn't respond

Check:

MESSAGE CONTENT INTENT is enabled (required!)
Bot token is correct (starts with MTQ... or similar)
Bot was invited to server with correct permissions
User/channel IDs are in configuration
If requireMention: true - you must @mention the bot
Look for "logged in to discord" in logs

Solution:

# Check logs
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep discord

# Verify bot token
echo $DISCORD_BOT_TOKEN

Missing MESSAGE CONTENT INTENT

Error: Bot receives messages but content is empty

Fix:

Go to Discord Developer Portal
Select your application → Bot
Enable MESSAGE CONTENT INTENT
Click "Save Changes"
Restart gateway

Bot offline in server

Check:

Bot token is valid
Gateway is running
No errors in logs about Discord connection

Solution:

# Regenerate bot token if needed
# Discord Developer Portal → Bot → Reset Token

Permission errors

Error: Missing Access or Missing Permissions

Fix:

Re-invite bot with correct permissions
Check bot role has required permissions in server settings
Verify channel permissions allow bot to read/send messages

Security Best Practices

Use Allowlist Policy

SAFE - Only specific users in allowed channels:

{
  "channels": {
    "discord": {
      "dm": {
        "policy": "allowlist",
        "allowFrom": ["123456789012345678"]
      },
      "groupPolicy": "allowlist",
      "guilds": {
        "987654321098765432": {
          "requireMention": true,
          "users": ["123456789012345678"]
        }
      }
    }
  }
}

❌ DANGEROUS - Anyone on server can interact:

{
  "channels": {
    "discord": {
      "dm": { "policy": "open" },
      "groupPolicy": "open"  // NEVER DO THIS!
    }
  }
}

Require Mentions in Shared Channels

Set requireMention: true in shared channels to prevent the bot from responding to every message.

Token Storage

Store tokens securely in environment:

~/.openclaw/.env

Never commit tokens to version control!

Rate Limits

Discord has rate limits. If you exceed them:

Wait before retrying
Implement backoff strategies
Monitor logs for rate limit warnings

OpenClaw handles basic rate limiting automatically.

Next Steps

Discord configured!

Configure additional channels:

Discord Setup