Discord Setup

Complete guide to connecting Discord with OpenClaw

Discord is a popular platform for communities and gaming. OpenClaw connects to Discord using the Bot API via channels.discord.js, providing DMs, server channels, and rich Discord features. New here? Use the Discord quickstart (Developer Portal, intents, token, first message) before diving into voice, threads, and stream previews below.

Stable v2026.5.20: Voice sessions can follow configured Discord users into voice channels (allowed-channel checks, multi-user handoff)—see release notes. Optional bounded IDENTITY.md/USER.md/SOUL.md context in realtime voice instructions (voice.realtime.bootstrapContextFiles: [] to disable).

Recent channel features (2026.2.21): Voice channel join/leave/status via /vc and auto-join configuration for realtime voice; thread-bound subagent sessions with per-thread focus/list controls; stream preview mode for live draft replies (partial/block options, configurable chunking); configurable lifecycle status reactions (queued/thinking/tool/done/error) with emoji and timing overrides; forum available_tags updates via channel edit actions; configurable ephemeral defaults for slash-command responses. Channel topics are included in trusted inbound metadata on new sessions.

Quick Setup

Setting up Discord requires creating a bot application:

  1. Create bot application in Discord Developer Portal
  2. Get your bot token
  3. Invite bot to your server
  4. Configure in OpenClaw
  5. Start chatting!

Creating a Discord Bot

Step 1: Create Application

  1. Go to Discord Developer Portal
  2. Click "New Application"
  3. Enter a name for your bot
  4. Click "Create"

Step 2: Create Bot

  1. Go to "Bot" section
  2. Click "Add Bot"
  3. Confirm creation
  4. Copy the bot token

Step 3: Configure Bot

Set bot options:

  • Enable "Message Content Intent" (required)
  • Set bot username and avatar
  • Configure other settings as needed

Inviting Bot to Server

Step 1: Generate Invite URL

  1. Go to "OAuth2" → "URL Generator"
  2. Select "bot" scope
  3. Select permissions:
    • Send Messages
    • Read Message History
    • Use Slash Commands (optional)
    • Attach Files
    • Embed Links
  4. Copy the generated URL

Step 2: Invite Bot

  1. Open the invite URL
  2. Select your server
  3. Authorize the bot
  4. Bot should appear in your server

Configuring OpenClaw

Basic Configuration

Discord Config 
{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN_HERE"
    }
  }
}

Setting Token

Add your bot token:

  1. Get token from Discord Developer Portal
  2. Add to configuration file
  3. Or set via environment variable: DISCORD_BOT_TOKEN

Discord Features

Direct Messages

  • Send and receive DMs
  • Rich embeds
  • File attachments
  • Reactions

Server Channels

  • Join text channels
  • Mention-based activation (default)
  • Channel allowlists
  • Reply threading
  • Rich embeds

Media Support

  • Images and attachments
  • Voice messages with waveform previews (from local audio files)
  • File uploads
  • Rich embeds
  • Reactions

You can configure the bot's presence status, activity type, and custom status (e.g. "Playing…" or "Listening to…") in config.

Advanced Configuration

Server Configuration

Server Config 
{
  "channels": {
    "discord": {
      "guilds": {
        "123456789012345678": {
          "channels": ["general", "support"]
        }
      }
    }
  }
}

Channel Configuration

Channel Config 
{
  "channels": {
    "discord": {
      "guilds": {
        "123456789012345678": {
          "channels": {
            "general": {
              "requireMention": true
            },
            "support": {
              "requireMention": false,
              "activation": "always"
            }
          }
        }
      }
    }
  }
}

Security & Permissions

Bot Permissions

Required permissions:

  • Send Messages
  • Read Message History
  • Attach Files
  • Embed Links
  • Use External Emojis (optional)

Bot Token Security

Keep your bot token secure:

  • Never share your token
  • Store in configuration file
  • Use environment variables if needed
  • Regenerate token if compromised

Troubleshooting Discord

Bot Not Responding

If bot doesn't respond:

  1. Verify bot token is correct
  2. Check Gateway is running
  3. Verify bot is online in Discord
  4. Check bot permissions
  5. Review Gateway logs

Can't Read Messages

If bot can't read messages:

  1. Check "Message Content Intent" is enabled
  2. Verify bot permissions
  3. Check channel permissions
  4. Ensure bot is in the channel

Permission Errors

If you get permission errors:

  1. Check bot role permissions
  2. Verify channel permissions
  3. Re-invite bot with correct permissions
  4. Check bot's role position

Best Practices

  • Use Channel Allowlists - Control which channels bot can access
  • Enable Mention Gating - For server channels
  • Secure Token - Keep bot token private
  • Set Proper Permissions - Only grant needed permissions
  • Monitor Logs - Check for issues

Keep going