Discord Channel - PicoClaw

Discord integration allows your PicoClaw assistant to interact in Discord servers and channels. Setup requires creating a bot application and enabling proper intents.

Why Discord?

Community Focused: Perfect for team collaboration and communities
Rich Permissions: Fine-grained control over bot capabilities
Group Support: Configurable mention-only or always-respond modes
No Webhooks: Uses WebSocket Gateway (no server setup needed)

Prerequisites

A Discord account
Server admin permissions (to invite the bot)
PicoClaw installed with LLM provider configured
~10 minutes for setup

Setup Instructions

Create a Discord Application

Go to Discord Developer Portal
Click New Application
Give it a name (e.g., “PicoClaw Bot”)
Click Create

Create a Bot User

In your application, navigate to Bot in the left sidebar
Click Add Bot
Confirm by clicking Yes, do it!
Under the TOKEN section, click Reset Token and copy it

Keep this token secure! Anyone with access can control your bot. Never share it publicly or commit it to version control.

Enable Privileged Intents

Still in the Bot settings page:

Scroll down to Privileged Gateway Intents
Enable MESSAGE CONTENT INTENT (required to read messages)
(Optional) Enable SERVER MEMBERS INTENT if using member-based allow lists
Click Save Changes

MESSAGE CONTENT INTENT is mandatory for the bot to see message content. Without it, the bot will connect but won’t receive messages.

Get Your User ID

To restrict bot access:

Open Discord Settings → Advanced
Enable Developer Mode
Right-click your avatar or username
Select Copy User ID
Save this ID for the configuration

You can copy IDs of other users the same way to add them to allow_from.

Configure PicoClaw

Edit ~/.picoclaw/config.json:

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["YOUR_USER_ID"]
    }
  }
}

Replace:

token: Your bot token from the Developer Portal
allow_from: Your Discord user ID (or empty array [] for public access)

Invite the Bot to Your Server

Go back to your application in the Developer Portal
Navigate to OAuth2 → URL Generator
Under SCOPES, select:
- bot
Under BOT PERMISSIONS, select:
- Send Messages
- Read Message History
- (Optional) Attach Files if you want the bot to send files
- (Optional) Add Reactions for reaction features
Copy the generated URL at the bottom
Open the URL in your browser
Select your server and click Authorize

You need Manage Server permission on the Discord server to invite bots.

Start the Gateway

Run PicoClaw Gateway:

picoclaw gateway

You should see:

[INFO] discord: Connected to Discord Gateway

Test Your Bot

Go to your Discord server
Send a message in a channel where the bot has access
The bot should respond with AI-generated replies

Configuration Options

Basic Configuration

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["USER_ID_1", "USER_ID_2"]
    }
  }
}

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable Discord channel
`token`	string	Yes	Bot token from Discord Developer Portal
`allow_from`	array	No	List of allowed Discord user IDs (empty = allow all)
`group_trigger`	object	No	Configure group chat trigger behavior

Group Trigger Configuration

By default, the bot responds to all messages in channels. Use group_trigger to change this behavior:

Mention-Only Mode

Respond only when the bot is @mentioned:

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "group_trigger": {
        "mention_only": true
      }
    }
  }
}

Now the bot only responds when users type @YourBotName message.

Prefix-Based Triggers

Respond to messages starting with specific prefixes:

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "group_trigger": {
        "prefixes": ["!bot", "!ai"]
      }
    }
  }
}

The bot responds to:

!bot Hello there
!ai What's the weather?

But ignores:

Hello there (no prefix)

Combined Configuration

Use both mention and prefix triggers:

{
  "group_trigger": {
    "mention_only": true,
    "prefixes": ["!bot"]
  }
}

Bot responds to:

@YourBotName hello (mention)
!bot hello (prefix)

Access Control

Allow specific users:

{
  "allow_from": ["123456789012345678", "876543210987654321"]
}

Allow everyone (public bot):

{
  "allow_from": []
}

Public Discord bots can be abused if not properly rate-limited. Consider:

Enabling mention_only mode in public servers
Using prefix triggers to avoid spam
Monitoring API costs from your LLM provider

Features

Text Messages

The bot processes text messages and maintains conversation context per user and channel.

Direct Messages

Users can DM the bot directly for private conversations (if allow_from permits).

Multi-Server Support

One bot instance can serve multiple Discord servers simultaneously. Each server/channel maintains independent conversation context.

Channel Permissions

The bot respects Discord channel permissions. It will only respond in channels where it can:

Read messages
Send messages
Read message history

Troubleshooting

Bot connects but doesn’t respond

Cause: Missing MESSAGE CONTENT INTENT Solution:

Go to Discord Developer Portal → Your App → Bot
Scroll to Privileged Gateway Intents
Enable MESSAGE CONTENT INTENT
Click Save Changes
Restart picoclaw gateway

”Missing Access” or “Missing Permissions” errors

Cause: Bot lacks required permissions in the channel Solution:

Check the bot’s role permissions in server settings
Ensure the bot role has:
- Read Messages
- Send Messages
- Read Message History
Check channel-specific permission overrides

Bot is online but doesn’t see messages

Possible causes:

Intent not enabled: Enable MESSAGE CONTENT INTENT (see above)
Allow list: Check if your user ID is in allow_from
Wrong channel: Bot might not have access to the channel
Group trigger: Check if mention_only is enabled and you forgot to @mention

”Invalid Token” error

Cause: Incorrect or expired bot token Solution:

Go to Developer Portal → Your App → Bot
Click Reset Token
Copy the new token
Update config.json with the new token
Restart gateway

Check Gateway logs

picoclaw gateway

Look for Discord-related errors in the output.

Advanced Configuration

Per-Server Settings

Currently, PicoClaw uses global configuration for all Discord servers. To have different behavior per server, you would need to run multiple bot instances with different tokens.

Multiple Bots

You can run multiple Discord bots by:

Creating multiple applications in Developer Portal
Using different configuration files:

PICOCLAW_CONFIG=/path/to/bot1-config.json picoclaw gateway
PICOCLAW_CONFIG=/path/to/bot2-config.json picoclaw gateway

Using with Docker

Docker deployments work the same way:

docker compose -f docker/docker-compose.yml --profile gateway up -d

Make sure your docker/data/config.json has the Discord configuration.

Privacy & Security

Security Best Practices:

Never share your bot token
Never commit tokens to git repositories
Use allow_from to restrict access for personal bots
Regenerate token immediately if compromised
Monitor bot activity in Discord’s Developer Portal
Review audit logs for unexpected behavior

Message Privacy

Discord bots can see:

All messages in channels where they have access
Message history (if Read Message History is enabled)
User IDs, usernames, and avatars
Server information

Be mindful of:

What data your LLM provider logs
What conversation context is stored locally
Privacy expectations of server members

Complete Example

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "gpt4"
    }
  },
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "your-api-key"
    }
  ],
  "channels": {
    "discord": {
      "enabled": true,
      "token": "MTIzNDU2Nzg5MDEyMzQ1Njc4.GaBcDe.FgHiJkLmNoPqRsTuVwXyZaBcDeFgHiJkLmNoPqRs",
      "allow_from": ["123456789012345678"],
      "group_trigger": {
        "mention_only": true
      }
    }
  }
}

Next Steps

Telegram Channel

Easier alternative with simpler setup

WhatsApp Channel

Connect via WhatsApp

Channel Overview

Compare all available channels

Configuration

Advanced configuration options

Get Started

Core Concepts

Commands

Configuration

Chat Channels

Features

Deployment

Advanced

​Why Discord?

​Prerequisites

​Setup Instructions

​Configuration Options

​Basic Configuration

​Group Trigger Configuration

​Mention-Only Mode

​Prefix-Based Triggers

​Combined Configuration

​Access Control

​Features

​Text Messages

​Direct Messages

​Multi-Server Support

​Channel Permissions

​Troubleshooting

​Bot connects but doesn’t respond

​”Missing Access” or “Missing Permissions” errors

​Bot is online but doesn’t see messages

​”Invalid Token” error

​Check Gateway logs

​Advanced Configuration

​Per-Server Settings

​Multiple Bots

​Using with Docker

​Privacy & Security

​Message Privacy

​Complete Example

​Next Steps

Telegram Channel

WhatsApp Channel

Channel Overview

Configuration

Build docs developers (and LLMs) love

Why Discord?

Prerequisites

Setup Instructions

Configuration Options

Basic Configuration

Group Trigger Configuration

Mention-Only Mode

Prefix-Based Triggers

Combined Configuration

Access Control

Features

Text Messages

Direct Messages

Multi-Server Support

Channel Permissions

Troubleshooting

Bot connects but doesn’t respond

”Missing Access” or “Missing Permissions” errors

Bot is online but doesn’t see messages

”Invalid Token” error

Check Gateway logs

Advanced Configuration

Per-Server Settings

Multiple Bots

Using with Docker

Privacy & Security

Message Privacy

Complete Example

Next Steps