Discord Bot Setup

Configure a Discord bot with WebSocket gateway, allowlists, and server permissions for NullClaw

Connect NullClaw to Discord via WebSocket gateway to create an AI assistant bot that responds to mentions and direct messages.

Prerequisites

• Discord account
• Discord server (guild) with admin permissions
• Developer Portal access for bot token

Quick Setup

1. Create Discord Application

   Go to Discord Developer Portal and create a new application.

2. Create Bot

   Navigate to “Bot” section, click “Add Bot”, and copy the bot token.

3. Enable Intents

   Enable “Message Content Intent” under “Privileged Gateway Intents”.

4. Invite Bot

   Use OAuth2 URL Generator with bot scope and required permissions, then open the URL to invite.

5. Configure NullClaw

   Add bot token and guild ID to ~/.nullclaw/config.json.

Configuration

Basic Setup

Edit ~/.nullclaw/config.json:

config.json

{
  "channels": {
    "discord": {
      "accounts": {
        "main": {
          "token": "your-discord-bot-token",
          "guild_id": "123456789012345678",
          "allow_from": ["username#1234"],
          "allow_bots": false
        }
      }
    }
  }
}

Complete Configuration

config.json

{
  "channels": {
    "discord": {
      "accounts": {
        "main": {
          "token": "MTIzNDU2Nzg5MDEyMzQ1Njc4.GhIJkL.MnOpQrStUvWxYz0123456789",
          "guild_id": "123456789012345678",
          "allow_from": ["alice#1234", "bob#5678"],
          "allow_bots": false,
          "require_mention": false,
          "intents": 37377,
          "account_id": "main"
        }
      }
    }
  }
}

Configuration Options

token (required)

Your Discord bot token from the Developer Portal:

"token": "MTIzNDU2Nzg5MDEyMzQ1Njc4.GhIJkL.MnOpQrStUvWxYz0123456789"

How to get bot token

1. Go to Discord Developer Portal
2. Create or select your application
3. Navigate to “Bot” section
4. Click “Reset Token” or view existing token
5. Copy the token (shown only once)

Never share your bot token publicly. It grants full access to your bot.

guild_id (optional)

Server ID where bot is active:

"guild_id": "123456789012345678"

If omitted, bot works in DMs and all servers where it’s invited.

How to find guild ID

1. Enable Developer Mode in Discord (User Settings → Advanced → Developer Mode)
2. Right-click your server icon
3. Select “Copy Server ID”

allow_from (required)

Usernames allowed to interact with bot:

Specific Users

"allow_from": ["alice#1234", "bob#5678"]

Only these users can interact with the bot.

Allow All

"allow_from": ["*"]

Anyone can interact (not recommended).

User IDs

"allow_from": ["123456789012345678"]

Use numeric Discord user IDs for precision.

Empty allow_from array denies ALL messages. Always specify at least one user or use ["*"].

allow_bots

Allow other bots to trigger your bot:

"allow_bots": false

• false (default): Ignore messages from bots
• true: Allow bot-to-bot interaction (use with caution)

require_mention

Require @mention to trigger bot in channels:

"require_mention": false

• false: Respond to all messages (respecting allow_from)
• true: Only respond when bot is mentioned with @BotName

intents

Gateway intents bitmask:

"intents": 37377

Default value 37377 includes:

• GUILDS (1)
• GUILD_MESSAGES (512)
• MESSAGE_CONTENT (32768)
• DIRECT_MESSAGES (4096)

Common intent combinations

• Basic messaging: 37377 (default)
• DMs only: 4096
• Guild only: 33281 (GUILDS + GUILD_MESSAGES + MESSAGE_CONTENT)

See Discord Intents for details.

Bot Permissions

When generating OAuth2 invite URL, select these permissions:

Send Messages

Required to respond

Read Message History

Access message context

View Channels

See channel content

Attach Files

Send images/files

Minimum permissions integer: 68608

Multiple Discord Bots

Run multiple Discord bots for different servers:

config.json

{
  "channels": {
    "discord": {
      "accounts": {
        "community": {
          "token": "TOKEN_1",
          "guild_id": "111111111111111111",
          "allow_from": ["*"]
        },
        "private": {
          "token": "TOKEN_2",
          "guild_id": "222222222222222222",
          "allow_from": ["admin#1234"]
        }
      }
    }
  }
}

Message Handling

Automatic Message Splitting

Discord limits messages to 2000 characters. NullClaw automatically:

• Splits long responses
• Sends multiple messages sequentially
• Preserves formatting

Typing Indicators

Bot sends typing indicators while processing:

• Automatically triggered on message receipt
• Stops when response is sent
• Repeats every 8 seconds for long operations

Attachments

Bot can receive and send:

• Images
• Text files
• Code snippets
• Other attachments

Running the Bot

Gateway Mode (Recommended)

Run all channels including Discord:

nullclaw gateway

Standalone Channel

Run only Discord channel:

nullclaw channel start discord

Check Status

# Check all channels
nullclaw channel status

# Run diagnostics
nullclaw doctor

Background Service

# Install as system service
nullclaw service install
nullclaw service start

# Check logs
journalctl -u nullclaw -f  # Linux
tail -f ~/Library/Logs/nullclaw.log  # macOS

Security Best Practices

Use Allowlists

Always restrict access:

"allow_from": ["trusted_user#1234"]

Disable Bot Interaction

Prevent bot loops:

"allow_bots": false

Encrypt Token

Enable secret encryption:

{
  "secrets": {
    "encrypt": true
  }
}

Limit Permissions

Only grant required Discord permissions (avoid Administrator).

Troubleshooting

Bot Not Connecting

1. Check Token

   Verify token is valid in Developer Portal

2. Check Intents

   Enable “Message Content Intent” in Developer Portal under Bot settings

3. Check Logs

   Run nullclaw gateway in foreground to see WebSocket errors

4. Verify Invite

   Ensure bot is invited to the server with correct permissions

Bot Not Responding

Common causes:

• Username not in allow_from
• Message Content Intent not enabled
• Bot lacking channel permissions
• require_mention: true but bot not mentioned

WebSocket Disconnections

NullClaw handles:

• Automatic reconnection
• Session resumption
• Heartbeat monitoring

If frequent disconnects occur:

# Check network stability
ping discord.com

# Review gateway logs
nullclaw channel status

Invalid Session

If you see “Invalid Session” errors:

1. Bot token may be invalidated
2. Intents may have changed
3. Re-copy token from Developer Portal
4. Restart NullClaw

Advanced Configuration

Channel-Specific Responses

Restrict bot to specific channels using Discord permissions:

1. In server settings, create a role for the bot
2. Deny “View Channel” in unwanted channels
3. Allow “View Channel” only where bot should respond

Slash Commands

NullClaw currently supports message-based interaction. Slash command support is planned.

Voice Channel Support

Voice channels are not currently supported. For voice transcription, use:

• Voice message attachments
• Upload audio files

Next Steps

Telegram Setup

Configure Telegram bot

Nostr Setup

Connect via Nostr protocol