Discord Setup

Discord is a powerful platform for AI agent interactions. With OpenClaw's Discord integration, you can chat with your agent, share files, and collaborate with others in a familiar chat environment.

This guide walks you through creating a Discord bot, configuring permissions, and connecting it to your OpenClaw instance.

What You Need

• A Discord account (free)
• A Discord server where you have admin rights
• Your OpenClaw instance running and accessible
• About 10 minutes

Step 1: Create a Discord Application

First, you need to create a Discord application and bot in the Discord Developer Portal.

Access the Developer Portal

1. Go to the Discord Developer Portal
2. Log in with your Discord account
3. Click "New Application" in the top right

Name Your Application

1. Give your application a name (e.g., "My OpenClaw Agent")
2. Click "Create"
3. Optional: Add a description and app icon

Step 2: Create a Bot User

Now convert your application into a bot that can join servers and send messages.

Enable the Bot

1. In the left sidebar, click "Bot"
2. Click "Add Bot" and confirm
3. Your bot is now created

Configure Bot Settings

1. Under "Privileged Gateway Intents", enable:
   • MESSAGE CONTENT INTENT (required to read messages)
   • SERVER MEMBERS INTENT (optional, for member info)
2. Click "Save Changes" at the bottom

Get Your Bot Token

1. In the Bot section, click "Reset Token"
2. Copy the token immediately (it won't be shown again)
3. Store it securely; you'll need it for OpenClaw configuration

Step 3: Configure OAuth2 and Invite the Bot

Your bot needs to be invited to your Discord server with the correct permissions.

Set Up OAuth2 Scopes

1. In the left sidebar, click "OAuth2" then "URL Generator"
2. Under "Scopes", select:
   • bot
   • applications.commands (optional, for slash commands)

Configure Bot Permissions

Under "Bot Permissions", select these minimum permissions:

• Send Messages
• Send Messages in Threads
• Embed Links
• Attach Files
• Read Message History
• Add Reactions
• Use Slash Commands
• Read Messages/View Channels

Generate and Use the Invite URL

1. Copy the generated URL at the bottom
2. Open the URL in your browser
3. Select your server from the dropdown
4. Click "Authorize"
5. Complete the CAPTCHA if prompted

Your bot should now appear in your server's member list as offline.

Step 4: Configure OpenClaw

Now connect your Discord bot to your OpenClaw instance.

Add Discord Plugin Configuration

Edit your OpenClaw configuration file (usually config.yaml or environment variables):

# Discord plugin configuration
plugins:
  entries:
    discord:
      enabled: true
      config:
        botToken: "YOUR_BOT_TOKEN_HERE"
        # Optional: restrict to specific channels
        allowedChannels:
          - "general"
          - "bot-commands"
        # Optional: require prefix for messages
        commandPrefix: "!"
        # Optional: default model for this channel
        defaultModel: "moonshot/kimi-k2.5"

Environment Variable Alternative

You can also use environment variables:

# In your .env file
OPENCLAW_DISCORD_TOKEN=YOUR_BOT_TOKEN_HERE
OPENCLAW_DISCORD_ENABLED=true

Restart OpenClaw

After configuration, restart your OpenClaw instance to load the Discord plugin:

# If using Docker Compose
docker compose restart

# If using systemd
sudo systemctl restart openclaw

Step 5: Test Your Setup

Verify everything is working correctly.

Check Bot Status

1. Look at your Discord server member list
2. Your bot should now show as online (green dot)
3. If still offline, check OpenClaw logs for errors

Send a Test Message

1. In your Discord server, go to a text channel
2. Send a message mentioning or addressing your bot
3. Wait for a response from your OpenClaw agent

# Example test messages
Hello bot, what can you do?
@MyBotName what is the weather today?
!help

Advanced Configuration

Channel-Specific Settings

Different channels can have different behaviors:

plugins:
  entries:
    discord:
      enabled: true
      config:
        botToken: "YOUR_TOKEN"
        channelConfigs:
          "general":
            model: "moonshot/kimi-k2.5"
            systemPrompt: "You are a helpful assistant."
          "coding-help":
            model: "anthropic/claude-sonnet-4"
            systemPrompt: "You are a coding expert."
          "admin":
            model: "openai/gpt-5.4"
            allowedUsers:
              - "admin_user_id_123"

Thread Support

Enable thread creation for long conversations:

config:
  botToken: "YOUR_TOKEN"
  autoCreateThreads: true
  threadAutoArchiveDuration: 1440  # 24 hours

Direct Message Support

Allow users to DM your bot directly:

config:
  botToken: "YOUR_TOKEN"
  allowDirectMessages: true
  dmRateLimitPerUser: 10  # messages per minute

Troubleshooting

Bot Shows Offline

• Check token: Verify the bot token is correct in config
• Check logs: Look for Discord connection errors in OpenClaw logs
• Restart: Ensure OpenClaw fully restarted after config changes

Bot Does Not Respond to Messages

• MESSAGE CONTENT INTENT: Verify this is enabled in Discord Developer Portal
• Permissions: Check the bot has Read Messages and Send Messages permissions
• Channel access: Ensure bot has access to the channel you're testing in
• Command prefix: If using a prefix, make sure your message starts with it

Rate Limiting

If you see rate limit errors:

• Reduce message frequency
• Enable message queueing in config
• Consider Discord Nitro for higher limits

Slash Commands Not Working

• Re-invite bot with applications.commands scope
• Wait up to an hour for commands to sync globally
• Or set a specific test guild for instant sync

Best Practices

Security

• Store bot token in environment variables, never in code
• Use separate bots for development and production
• Regularly rotate tokens (reset and update)
• Restrict bot to specific channels if possible

Performance

• Use thread mode for long conversations to keep channels clean
• Set up rate limiting to prevent abuse
• Consider model routing for cost optimization
• Enable context compaction for long sessions

User Experience

• Set a clear bot name and avatar
• Use status messages to show when the bot is thinking
• Configure typing indicators for better feedback
• Set up help commands for users

Summary

Discord integration brings OpenClaw into a familiar chat environment. Create a bot application, configure the necessary permissions and intents, invite it to your server, and configure OpenClaw with your bot token.

With advanced features like channel-specific models, thread support, and DM handling, you can build sophisticated AI-powered Discord experiences.