Setup OpenClaw with Discord - Complete Guide

Overview

Discord integration is one of the best ways to interact with your OpenClaw agents. Discord's organized channel structure makes it perfect for managing multiple agents, creating dedicated workspaces for different tasks, and enabling team collaboration.

Benefits

• Organized Conversations: Use separate channels for different agents and tasks
• Thread Support: Create focused threads for specific projects or research tasks
• Team Collaboration: Multiple team members can interact with agents
• Persistent History: All conversations are saved and searchable
• Rich Media: Share files, images, and formatted code easily
• Mobile Access: Use Discord mobile app to interact with agents anywhere

Use Cases

• Multi-Agent Teams: Assign different agents to different channels (e.g., Stark for development, Banner for research)
• Project Management: Create channels for specific projects with dedicated agent support
• Research Tasks: Use threads to keep research organized and focused
• Team Workflows: Enable team members to collaborate with shared agents

Prerequisites

• OpenClaw 3.2 or later installed and running
• Discord account
• Discord server where you have admin permissions (or ability to create one)
• Terminal access to your OpenClaw installation
• Basic understanding of Discord bot permissions

Step-by-Step Setup

Step 1: Create Discord Application

1. Navigate to discord.com/developers/applications
2. Click "New Application" in the top-right
3. Enter a name for your bot (e.g., "OpenClaw Agent", "Stark", "Banner")
4. Accept the Terms of Service
5. Click "Create"

Step 2: Configure Bot Settings

1. In the left sidebar, click "Bot"
2. Customize your bot:
   • Username: Change if desired
   • Icon: Upload a profile picture (optional)
   • Description: Add a description (optional)
3. Click "Save Changes"

Step 3: Enable Required Intents

⚠️ CRITICAL STEP - Your bot won't work without these:

1. Scroll down to "Privileged Gateway Intents"
2. Enable the following:
   • ✅ Server Members Intent
   • ✅ Message Content Intent
   • ✅ Presence Intent (optional, but recommended)
3. Click "Save Changes"

Why these are required:

• Server Members Intent: Allows bot to see server member information
• Message Content Intent: Allows bot to read message content (essential for responding)
• Presence Intent: Allows bot to see user online status

Step 4: Get Your Bot Token

1. In the Bot section, find "Token"
2. Click "Reset Token" (or "Copy" if this is your first time)
3. You may need to verify with 2FA or passkey
4. Copy the token immediately - you won't be able to see it again

⚠️ SECURITY WARNING:

• Never share this token publicly
• Never commit it to Git
• Never paste it in Discord channels
• If exposed, reset it immediately

Step 5: Configure OpenClaw

Recommended Method: Use OpenClaw's configuration interface (more reliable than asking the agent to set it up).

1. Open your terminal and connect to your OpenClaw server
2. Run the configuration command:

openclaw configure

3. Select "Local" when prompted for environment
4. Navigate to "Channels" → "Configure"
5. Select "Discord"

6. When prompted for "Discord bot token", paste your token:

   • Windows: Ctrl + Shift + V
   • Mac: Cmd + V
   • Linux: Ctrl + Shift + V or right-click → Paste

7. Configure channel access:

   • Select "Yes" to configure Discord to access channels
   • You'll set up specific channels in the next step

8. Configure pairing policy:

   • Allow DM pairing: Choose based on your needs
   • Pairing policy: Select your preferred security level

9. Select "Finished" when done

Step 6: Enable Developer Mode in Discord

To get channel IDs, you need Developer Mode enabled:

1. Open Discord
2. Click the gear icon (User Settings) in the bottom-left
3. Go to "Advanced" in the left sidebar
4. Enable "Developer Mode"
5. Close settings

Step 7: Create and Configure Channels

1. In your Discord server, create a new channel:

   • Right-click on your server name
   • Select "Create Channel"
   • Choose "Text Channel"
   • Name it (e.g., "stark-workspace", "agent-research")

2. Get the channel ID:

   • Right-click on the channel name
   • Select "Copy Channel ID"

3. Add the channel to OpenClaw:

   • In the OpenClaw configuration, paste the channel ID when prompted
   • Repeat for additional channels

Step 8: Restart OpenClaw Gateway

After configuration, restart the gateway to apply changes:

openclaw gateway restart

Wait for the confirmation message that the gateway has restarted successfully.

Step 9: Generate Bot Invite Link

1. Go back to discord.com/developers/applications

2. Select your application

3. Click "OAuth2" in the left sidebar

4. Click "URL Generator"

5. Select scopes:

   • ✅ bot
   • ✅ applications.commands

6. Select bot permissions:

   • ✅ Administrator (easiest, but see security note below)

   OR for more granular control:

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

7. Copy the generated URL at the bottom

Security Note: Administrator permission is convenient but gives full server access. For production use, prefer specific permissions.

Step 10: Invite Bot to Your Server

1. Paste the invite URL in your browser
2. Select your server from the dropdown
3. Click "Continue"
4. Review permissions
5. Click "Authorize"
6. Complete the CAPTCHA verification

Your bot should now appear in your server's member list!

Step 11: Test the Integration

1. Go to the channel you configured
2. Send a message to your bot:

@YourBotName hello

Or simply:

hello

3. The bot should respond within a few seconds

If the bot doesn't respond, see the Troubleshooting section below.

Configuration Examples

Single Agent Setup

Perfect for personal use:

# OpenClaw configuration
Channel: #agent-workspace
Pairing: Open (no restrictions)

Multi-Agent Team Setup

Different agents in different channels:

# Agent 1: Stark (Development)
Channel: #stark-dev
Pairing: Allowlist

# Agent 2: Banner (Research)
Channel: #banner-research
Pairing: Allowlist

# Agent 3: Jarvis (General)
Channel: #jarvis-general
Pairing: Open

Team Collaboration Setup

Multiple team members with shared agents:

# Main agent channel
Channel: #team-agent
Pairing: Allowlist (team members only)

# Subtask channels
Channel: #presentations
Channel: #research
Channel: #code-review

Advanced Features

Using Threads

Threads keep conversations organized:

1. Right-click on any message in your channel
2. Select "Create Thread"
3. Name your thread (e.g., "Research Task: AI Models")
4. Start chatting in the thread

Your agent will respond within the thread, keeping the main channel clean.

Benefits:

• Focused conversations
• Easy to find past discussions
• Main channel stays organized
• Multiple parallel tasks

Configuring Bot Behavior

You can customize how your bot responds:

@YourBot configure yourself to always respond without needing @mentions in this channel

Or:

@YourBot only respond when I @mention you

Multiple Bots in One Server

Assign different bots to different channels:

1. Create multiple Discord applications (one per bot)
2. Configure each with OpenClaw using different channel IDs
3. Each bot operates independently in its assigned channel

Security Best Practices

✅ DO:

• Store bot token in .env file (see Security Guide)
• Use specific permissions instead of Administrator when possible
• Enable Developer Mode only when needed
• Use allowlist pairing for team environments
• Create separate bots for different security contexts
• Regularly review bot permissions and access

❌ DON'T:

• Never share bot tokens in Discord or other chat platforms
• Don't use Administrator permission in production without good reason
• Don't add bots to public servers without proper security
• Don't share invite links publicly if using sensitive data
• Don't skip the Message Content Intent - bot won't work

Token Security

If your bot token is exposed:

1. Go to Discord Developer Portal
2. Navigate to your application → Bot
3. Click "Reset Token"
4. Update your OpenClaw .env file:

nano ~/.openclaw/.env
# Update DISCORD_BOT_TOKEN=new_token_here

5. Restart OpenClaw gateway:

openclaw gateway restart

Common Issues and Solutions

Issue 1: Bot Doesn't Respond

Symptoms:

• Bot is online but doesn't reply to messages
• No reaction to @mentions

Solutions:

1. Check Message Content Intent:

   • Go to Discord Developer Portal → Bot
   • Verify "Message Content Intent" is enabled
   • Save changes and restart OpenClaw gateway

2. Verify channel configuration:

   openclaw configure
   # Check that channel ID is correct
   

3. Check bot permissions in channel:

   • Right-click channel → Edit Channel → Permissions
   • Ensure bot role has "Read Messages" and "Send Messages"

4. Restart gateway:

   openclaw gateway restart
   

Issue 2: Bot Shows Offline

Symptoms:

• Bot appears offline in member list
• No presence indicator

Solutions:

1. Check token validity:

   • Token may have been reset
   • Verify token in .env file matches Discord Developer Portal

2. Check OpenClaw status:

   openclaw status
   

3. Review logs:

   openclaw logs
   

4. Restart OpenClaw:

   openclaw restart
   

Issue 3: Permission Errors

Symptoms:

• "Missing Permissions" errors
• Bot can't send messages or attachments

Solutions:

1. Check bot role position:

   • Server Settings → Roles
   • Ensure bot role is above any restricted roles

2. Check channel permissions:

   • Right-click channel → Edit Channel → Permissions
   • Add bot role with required permissions

3. Re-invite bot with correct permissions:

   • Generate new invite URL with proper permissions
   • Remove old bot and re-invite

Issue 4: Configuration Fails

Symptoms:

• OpenClaw configure crashes
• "Gateway failed to start" errors

Solutions:

1. Use manual configuration instead of asking agent:

   openclaw configure
   # Follow prompts manually
   

2. Check for conflicting configurations:

   cat ~/.openclaw/config.yaml
   # Look for duplicate Discord entries
   

3. Reset configuration:

   openclaw configure --reset
   # Reconfigure from scratch
   

Issue 5: Bot Responds to Everyone

Symptoms:

• Bot responds to all server members
• No pairing restrictions working

Solutions:

1. Configure pairing policy:

   openclaw configure
   # Channels → Configure → Discord → Pairing policy
   

2. Set up allowlist:

   @YourBot configure pairing to allowlist mode
   @YourBot add user @Username to allowlist
   

3. Use channel permissions:

   • Make channel private
   • Only add authorized users

Troubleshooting Checklist

Before asking for help, verify:

• OpenClaw version is 3.2 or later
• Discord bot has Message Content Intent enabled
• Discord bot has Server Members Intent enabled
• Bot token is correctly stored in .env file
• Channel ID is correct (copied from Discord with Developer Mode)
• OpenClaw gateway has been restarted after configuration
• Bot has proper permissions in the Discord channel
• Bot is online in Discord member list
• No firewall blocking OpenClaw's connection

Advanced Configuration

Custom Bot Personality

Configure your bot's personality and behavior:

@YourBot from now on, respond in a professional tone and always provide code examples when discussing programming

Webhook Integration

For advanced use cases, combine Discord webhooks with OpenClaw:

1. Create webhook in Discord channel settings
2. Configure OpenClaw to post updates via webhook
3. Use for notifications, status updates, etc.

Multi-Server Setup

Run the same bot across multiple servers:

1. Use the same bot token
2. Configure different channel IDs per server
3. Each server can have different pairing policies

Related Guides

• Security Best Practices - Secure your bot token
• Telegram Setup - Alternative messaging platform
• Notion Integration - Connect to Notion for task management
• API Integration Guide - Add more capabilities

Additional Resources

• Discord Developer Documentation
• Discord Bot Best Practices
• OpenClaw Discord Integration Docs

---

Video Tutorial: Watch the complete setup guide

Need Help? Join the OpenClaw community Discord for support.

Pro Tip: Discord's thread feature is incredibly powerful for keeping multiple tasks organized. Create a thread for each major task or project to maintain clean, focused conversations with your agent.