> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nullclaw/nullclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Create Discord Application">
    Go to [Discord Developer Portal](https://discord.com/developers/applications) and create a new application.
  </Step>

  <Step title="Create Bot">
    Navigate to "Bot" section, click "Add Bot", and copy the bot token.
  </Step>

  <Step title="Enable Intents">
    Enable "Message Content Intent" under "Privileged Gateway Intents".
  </Step>

  <Step title="Invite Bot">
    Use OAuth2 URL Generator with `bot` scope and required permissions, then open the URL to invite.
  </Step>

  <Step title="Configure NullClaw">
    Add bot token and guild ID to `~/.nullclaw/config.json`.
  </Step>
</Steps>

## Configuration

### Basic Setup

Edit `~/.nullclaw/config.json`:

```json config.json theme={null}
{
  "channels": {
    "discord": {
      "accounts": {
        "main": {
          "token": "your-discord-bot-token",
          "guild_id": "123456789012345678",
          "allow_from": ["username#1234"],
          "allow_bots": false
        }
      }
    }
  }
}
```

### Complete Configuration

```json config.json theme={null}
{
  "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:

```json theme={null}
"token": "MTIzNDU2Nzg5MDEyMzQ1Njc4.GhIJkL.MnOpQrStUvWxYz0123456789"
```

<Accordion title="How to get bot token">
  1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
  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)
</Accordion>

<Warning>
  Never share your bot token publicly. It grants full access to your bot.
</Warning>

### guild\_id (optional)

Server ID where bot is active:

```json theme={null}
"guild_id": "123456789012345678"
```

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

<Accordion title="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"
</Accordion>

### allow\_from (required)

Usernames allowed to interact with bot:

<Tabs>
  <Tab title="Specific Users">
    ```json theme={null}
    "allow_from": ["alice#1234", "bob#5678"]
    ```

    Only these users can interact with the bot.
  </Tab>

  <Tab title="Allow All">
    ```json theme={null}
    "allow_from": ["*"]
    ```

    Anyone can interact (not recommended).
  </Tab>

  <Tab title="User IDs">
    ```json theme={null}
    "allow_from": ["123456789012345678"]
    ```

    Use numeric Discord user IDs for precision.
  </Tab>
</Tabs>

<Warning>
  Empty `allow_from` array denies ALL messages. Always specify at least one user or use `["*"]`.
</Warning>

### allow\_bots

Allow other bots to trigger your bot:

```json theme={null}
"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:

```json theme={null}
"require_mention": false
```

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

### intents

Gateway intents bitmask:

```json theme={null}
"intents": 37377
```

Default value `37377` includes:

* `GUILDS` (1)
* `GUILD_MESSAGES` (512)
* `MESSAGE_CONTENT` (32768)
* `DIRECT_MESSAGES` (4096)

<Accordion title="Common intent combinations">
  - **Basic messaging**: `37377` (default)
  - **DMs only**: `4096`
  - **Guild only**: `33281` (GUILDS + GUILD\_MESSAGES + MESSAGE\_CONTENT)

  See [Discord Intents](https://discord.com/developers/docs/topics/gateway#gateway-intents) for details.
</Accordion>

## Bot Permissions

When generating OAuth2 invite URL, select these permissions:

<CardGroup cols={2}>
  <Card title="Send Messages" icon="message">
    Required to respond
  </Card>

  <Card title="Read Message History" icon="clock">
    Access message context
  </Card>

  <Card title="View Channels" icon="eye">
    See channel content
  </Card>

  <Card title="Attach Files" icon="paperclip">
    Send images/files
  </Card>
</CardGroup>

Minimum permissions integer: `68608`

## Multiple Discord Bots

Run multiple Discord bots for different servers:

```json config.json theme={null}
{
  "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:

```bash theme={null}
nullclaw gateway
```

### Standalone Channel

Run only Discord channel:

```bash theme={null}
nullclaw channel start discord
```

### Check Status

```bash theme={null}
# Check all channels
nullclaw channel status

# Run diagnostics
nullclaw doctor
```

### Background Service

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Use Allowlists">
    Always restrict access:

    ```json theme={null}
    "allow_from": ["trusted_user#1234"]
    ```
  </Accordion>

  <Accordion title="Disable Bot Interaction">
    Prevent bot loops:

    ```json theme={null}
    "allow_bots": false
    ```
  </Accordion>

  <Accordion title="Encrypt Token">
    Enable secret encryption:

    ```json theme={null}
    {
      "secrets": {
        "encrypt": true
      }
    }
    ```
  </Accordion>

  <Accordion title="Limit Permissions">
    Only grant required Discord permissions (avoid Administrator).
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Bot Not Connecting

<Steps>
  <Step title="Check Token">
    Verify token is valid in Developer Portal
  </Step>

  <Step title="Check Intents">
    Enable "Message Content Intent" in Developer Portal under Bot settings
  </Step>

  <Step title="Check Logs">
    Run `nullclaw gateway` in foreground to see WebSocket errors
  </Step>

  <Step title="Verify Invite">
    Ensure bot is invited to the server with correct permissions
  </Step>
</Steps>

### 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:

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Telegram Setup" href="/guides/telegram" icon="telegram">
    Configure Telegram bot
  </Card>

  <Card title="Nostr Setup" href="/guides/nostr" icon="bolt">
    Connect via Nostr protocol
  </Card>
</CardGroup>