Skip to main content
ClawAgoraClawAgora
返回博客

How to Deploy a Discord AI Agent for Community Management: A Template-First Approach

ClawAgora Team·

Why Discord communities need AI agents

Running a Discord server past a few hundred members becomes a full-time job. Messages come in at all hours. New members ask the same questions. Spam bots evolve faster than regex filters can catch them. Arguments escalate while moderators are asleep.

Traditional Discord bots help, but they are rigid. They match patterns, execute commands, and have no understanding of context. When someone posts "I want to kill this bug in my code," a keyword-based bot might flag it as a threat. An AI agent reads context and moves on.

The shift from bots to agents is not about replacing moderators -- it is about giving them a capable assistant that handles the repetitive 80% (welcome messages, FAQ answers, spam removal, role assignment) so humans can focus on the 20% that requires judgment (conflict resolution, community strategy, edge cases).

This guide walks through building a Discord community management agent as a reusable workspace template.

Architecture overview

Discord Gateway (WebSocket)
        |
        v
[Discord MCP Server]
        |
        v
[AI Agent Runtime]
        |
        +----> SOUL.md (personality, rules, guardrails)
        |
        +----> Skills
        |       ├── moderation.md
        |       ├── welcome-onboarding.md
        |       ├── faq-responder.md
        |       └── engagement-tracker.md
        |
        +----> Knowledge Base
                ├── faq-entries.md
                ├── community-guidelines.md
                └── role-descriptions.md

The agent connects to Discord through an MCP server that wraps the Discord Bot API. Events flow in (messages, member joins, reactions), the agent processes them against its SOUL.md rules and skills, and actions flow back out (send message, assign role, delete message).

Template directory structure

discord-community-agent/
├── SOUL.md                        # Agent personality + moderation guardrails
├── AGENTS.md                      # Agent capabilities and boundaries
├── skills/
│   ├── moderation.md              # Content moderation workflow
│   ├── welcome-onboarding.md      # New member welcome sequence
│   ├── faq-responder.md           # FAQ matching and response
│   └── engagement-tracker.md      # Activity monitoring and reporting
├── knowledge/
│   ├── faq-entries.md             # Curated Q&A pairs
│   ├── community-guidelines.md   # Server rules for moderation reference
│   └── role-descriptions.md       # What each role means and how to earn it
├── .openclaw/
│   └── mcp.json                   # Discord MCP server config
├── .env.example                   # Required tokens and config
└── README.md                      # Setup instructions

Setting up the Discord MCP server

Create a Discord Application

Before configuring the MCP server, you need a Discord bot:

  1. Go to the Discord Developer Portal
  2. Create a new application
  3. Navigate to Bot settings, create a bot, and copy the token
  4. Under OAuth2, generate an invite URL with the required permissions
  5. Invite the bot to your server

MCP configuration

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-discord"],
      "env": {
        "DISCORD_BOT_TOKEN": "${DISCORD_BOT_TOKEN}",
        "DISCORD_GUILD_ID": "${DISCORD_GUILD_ID}"
      }
    }
  }
}

This gives the agent access to Discord tools:

  • discord_send_message -- Post a message to a channel
  • discord_delete_message -- Remove a message (moderation)
  • discord_add_role -- Assign a role to a member
  • discord_remove_role -- Remove a role from a member
  • discord_kick_member -- Kick a user from the server
  • discord_ban_member -- Ban a user from the server
  • discord_get_channel_messages -- Read recent messages
  • discord_create_thread -- Spin off a discussion thread
  • discord_add_reaction -- React to a message

Environment variables

# .env.example
DISCORD_BOT_TOKEN=MTIz...          # Bot token from Discord Developer Portal
DISCORD_GUILD_ID=1234567890        # Your server (guild) ID
MOD_LOG_CHANNEL=mod-log            # Channel for moderation action logs
WELCOME_CHANNEL=welcome            # Channel for new member greetings
FAQ_CHANNEL=help                   # Channel the FAQ responder monitors
MOD_ROLE=Moderator                 # Role to ping for escalations
MUTE_ROLE=Muted                    # Role that restricts message permissions

Writing the SOUL.md

The SOUL.md is the most important file in a community management agent template. It defines the agent's personality, communication style, and -- critically -- the boundaries of what it can and cannot do.

# Community Manager Agent

You are the community manager for the {{SERVER_NAME}} Discord server.
You help maintain a welcoming, productive community by handling
moderation, onboarding, and frequently asked questions.

## Personality
- Friendly but professional. Not overly casual, not robotic.
- Use the community's tone -- if the server is technical,
  keep responses precise. If it is casual, match that energy.
- Never use condescending language when moderating.
  "Hey, that message does not align with our guidelines"
  beats "You violated rule #4."

## Core responsibilities
1. **Moderation**: Monitor messages for guideline violations.
   Auto-remove clear violations, flag borderline cases for humans.
2. **Onboarding**: Welcome new members, explain the server
   structure, assign initial roles based on self-identification.
3. **FAQ**: Answer common questions from the knowledge base.
   Never fabricate answers -- if unsure, escalate to a human.
4. **Engagement**: Track inactive members, post weekly summaries,
   surface trending discussion topics.

## Moderation guardrails

### Auto-remove (high confidence)
- Spam links (known spam domains, excessive link posting)
- Slurs and hate speech (exact match or phonetic variants)
- Explicit NSFW content in non-NSFW channels
- Messages from accounts less than 24 hours old containing links

### Flag for review (medium confidence)
- Heated arguments with personal attacks
- Potential self-promotion that might be genuine contribution
- Off-topic discussions in focused channels
- Messages that could be satire or sarcasm

### Ignore (low confidence)
- Mildly off-topic casual conversation
- Strong opinions expressed respectfully
- Profanity that is not directed at individuals
- Cultural references you are unsure about

## Hard limits -- NEVER do these
- NEVER ban a member without posting the reason in {{MOD_LOG_CHANNEL}}
- NEVER moderate messages from users with the {{MOD_ROLE}} role
- NEVER DM users about moderation actions -- always use the public
  mod-log for transparency
- NEVER share private moderation discussions from staff channels
- NEVER guess answers to technical questions -- escalate to humans
- NEVER engage with trolls beyond a single warning

Building the skills

Skill 1: Content moderation

# Content Moderation

## Trigger
Every new message in monitored channels.

## Process

### Step 1: Classify the message
Evaluate the message against community guidelines stored in
knowledge/community-guidelines.md.

Assign a confidence level:
- **High** (>90%): Clear violation, no ambiguity
- **Medium** (50-90%): Possible violation, context-dependent
- **Low** (<50%): Probably fine

### Step 2: Act based on confidence

**High confidence violation:**
1. Delete the message immediately
2. Post to {{MOD_LOG_CHANNEL}}:

[Auto-Moderation] Removed message from @username in #channel Reason: {specific guideline violated} Content: {first 100 chars of message} Action: Message deleted

3. If this is the user's 3rd+ violation in 7 days,
apply {{MUTE_ROLE}} for 24 hours

**Medium confidence:**
1. Add a 👀 reaction to the message
2. Post to {{MOD_LOG_CHANNEL}}:

[Review Needed] Flagged message from @username in #channel Reason: {why it was flagged} Content: {first 100 chars} Action: Flagged for human review -- @Moderator


**Low confidence:**
- No action. Do not log.

### Step 3: Track patterns
Maintain a rolling count of violations per user.
After 3 violations in a week, notify {{MOD_ROLE}} with
a summary of the user's recent behavior.

Skill 2: Welcome and onboarding

# Welcome & Onboarding

## Trigger
When a new member joins the server (member_join event).

## Welcome Sequence

### Step 1: Send welcome message (in {{WELCOME_CHANNEL}})

Welcome to {{SERVER_NAME}}, @username! 👋

Here is how to get started:

  1. Head to #rules and read our community guidelines
  2. Introduce yourself in #introductions
  3. Pick your roles in #role-selection

Have questions? Drop them in #help and I will do my best to answer, or ping @Moderator for anything I cannot handle.


### Step 2: Check for role selection (after 10 minutes)
If the new member has not selected any roles in
#role-selection after 10 minutes, send a gentle nudge:

Hey @username -- just a reminder to pick your roles in #role-selection so you can access the right channels. No rush, just making sure you do not miss it!


### Step 3: First-day check-in (after 24 hours)
If the member has not sent any messages after 24 hours:

Hey @username, welcome back! If you are looking for a place to start, #introductions is a great spot. Or feel free to lurk -- no pressure. 😊


## Role Assignment Rules
- Members self-select roles via reactions in #role-selection
- Available roles are defined in knowledge/role-descriptions.md
- The agent confirms role assignment with a brief message

Skill 3: FAQ responder

# FAQ Responder

## Trigger
Messages in {{FAQ_CHANNEL}} that end with a question mark
or contain keywords matching FAQ entries.

## Process

### Step 1: Match the question
Compare the incoming message against entries in
knowledge/faq-entries.md. Use semantic matching --
"how do I get started?" should match "What are the first
steps for new users?"

### Step 2: Respond or escalate

**If a confident match is found (>80% similarity):**
Reply in the same channel or thread:

Great question! Here is what I know:

{answer from knowledge base}

If this does not fully answer your question, you can ping @Moderator for more help.


**If no confident match is found:**

I am not sure about that one -- let me flag it for the team. @Moderator, can someone help with this?

Also log the unmatched question for future FAQ updates.

### Step 3: Track popular questions
Maintain a count of how often each FAQ entry is triggered.
Report the top 10 weekly in {{MOD_LOG_CHANNEL}} so the
team can update documentation accordingly.

Skill 4: Engagement tracking

# Engagement Tracker

## Weekly Report (every Sunday at 6 PM)

### Metrics to gather:
1. **Message volume**: Total messages this week vs. last week
2. **Active members**: Unique users who posted this week
3. **New members**: Members who joined this week
4. **Departures**: Members who left this week
5. **Top channels**: Most active channels by message count
6. **Top contributors**: Most active members (by message count)
7. **Moderation actions**: Total warnings, mutes, kicks, bans

### Report format (post to {{MOD_LOG_CHANNEL}}):

Weekly Community Report — Week of March 17, 2026

📊 Activity Messages: 2,847 (+12% vs last week) Active members: 342 / 1,205 total (28.4%)

👋 Membership Joined: 47 new members Left: 8 members Net growth: +39

📣 Top Channels

  1. #general (623 messages)
  2. #help (412 messages)
  3. #showcase (289 messages)

🛡️ Moderation Auto-removed: 12 messages Flagged for review: 7 messages Mutes: 2 | Kicks: 0 | Bans: 0

📝 Top Unresolved Questions (FAQ gaps)

  1. "How do I reset my API key?" (asked 8 times)
  2. "Is there a mobile app?" (asked 5 times)

The event flow in practice

Here is how the full system responds to a typical sequence of events:

New Member Joins
      |
      v
[welcome-onboarding skill]
      |
      +----> Post welcome message to #welcome
      +----> Schedule 10-min role reminder
      +----> Schedule 24-hour check-in
      |
      v
Member Posts in #help
      |
      v
[faq-responder skill]
      |
      +----> Match against knowledge base
      |       |
      |       +-- Match found --> Reply with answer
      |       +-- No match ----> Escalate to @Moderator
      |
      v
Member Posts in #general
      |
      v
[moderation skill]
      |
      +----> Classify message
      |       |
      |       +-- High confidence violation --> Delete + log
      |       +-- Medium confidence ---------> Flag for review
      |       +-- Low confidence ------------> Pass through
      |
      v
Sunday 6 PM
      |
      v
[engagement-tracker skill]
      |
      +----> Gather weekly metrics
      +----> Post report to mod-log

Scaling the agent

Multiple server support

If you manage multiple Discord servers, extend the template with server-specific knowledge bases:

discord-community-agent/
├── knowledge/
│   ├── servers/
│   │   ├── server-alpha/
│   │   │   ├── faq-entries.md
│   │   │   ├── community-guidelines.md
│   │   │   └── role-descriptions.md
│   │   └── server-beta/
│   │       ├── faq-entries.md
│   │       ├── community-guidelines.md
│   │       └── role-descriptions.md

The agent reads the DISCORD_GUILD_ID environment variable and loads the corresponding knowledge base directory.

Integrating with external services

The Discord agent template becomes significantly more powerful when combined with other MCP servers:

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-discord"],
      "env": {
        "DISCORD_BOT_TOKEN": "${DISCORD_BOT_TOKEN}",
        "DISCORD_GUILD_ID": "${DISCORD_GUILD_ID}"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-notion"],
      "env": {
        "NOTION_API_KEY": "${NOTION_API_KEY}"
      }
    }
  }
}

With GitHub connected: when someone reports a bug in Discord, the agent creates a GitHub issue automatically. With Notion connected: the agent updates a community knowledge base when new FAQ entries are approved.

Knowledge base maintenance

The FAQ knowledge base is only useful if it stays current. Add a maintenance skill:

# Knowledge Base Maintenance

## When a new question is answered by a human moderator
1. Capture the question and the moderator's answer
2. Format it as a FAQ entry
3. Post to a #faq-review channel for approval
4. Once approved (moderator reacts with ✅), add to
   knowledge/faq-entries.md

## Monthly knowledge audit
1. List all FAQ entries that have not been triggered in 60 days
2. Post the list to the mod team for review
3. Archive or update stale entries

Security considerations

Community management agents interact with real people in real time. Security mistakes can harm your community.

1. Token security

Never commit your Discord bot token. Use environment variables and .env files excluded from version control. Rotate tokens immediately if they are ever exposed.

2. Permission scoping

Request only the Discord permissions your agent actually needs. A FAQ-only agent should not have ban permissions. If you later add moderation skills, update the bot's permissions at that point.

3. Rate limiting awareness

Discord's API has strict rate limits. The agent should:

  • Batch operations where possible
  • Implement exponential backoff on 429 responses
  • Never loop through all members or all messages without pagination

4. Content logging boundaries

If your agent logs messages for moderation, be clear with your community about what is logged and why. Many regions have data protection laws (GDPR, CCPA) that apply to message logging. The template includes a privacy notice you can customize for your community rules channel.

5. Escalation paths

The agent must always have a way to escalate to humans. Code a hard rule: if the agent is uncertain about a moderation action, it flags rather than acts. A false positive (removing a legitimate message) is far more damaging to community trust than a few minutes delay in catching a violation.

Deploying the template

Local development

# Pull the template
clawagora template pull discord-community-agent:1.0.0
cd discord-community-agent

# Configure environment
cp .env.example .env
# Edit .env with your Discord bot token and server ID

# Test the agent locally
# The agent connects to Discord and starts processing events

Managed hosting

For production communities, you want the agent running 24/7 with automatic restarts and monitoring. Managed hosting platforms handle this -- deploy once and the agent stays online without manual intervention.

When deploying to managed hosting, you get:

  • Automatic restarts on crashes
  • Log aggregation for moderation auditing
  • Environment variable management (no .env files on disk)
  • Scaling if you manage high-traffic servers

Browse existing Discord community management templates on platforms like ClawAgora, or push your own customized version for other server admins to discover and deploy.

FAQ

How is an AI agent different from a traditional Discord bot?

Traditional Discord bots execute hardcoded commands -- a user types /ban and the bot bans someone. An AI agent understands context, makes judgments, and takes multi-step actions autonomously. A community management agent can read a message, determine if it violates guidelines based on nuanced rules in its SOUL.md, decide on the appropriate response (warn, mute, or escalate), explain its reasoning, and log the action -- all without a human typing a command. The agent's behavior is defined in natural language through its SOUL.md and skills, making it far more adaptable than code-based bot logic.

What Discord permissions does the agent need?

At minimum, the bot needs: Read Messages/View Channels, Send Messages, Manage Messages (for moderation), Kick Members, Ban Members (if you want moderation enforcement), Manage Roles (for role-based onboarding), and Read Message History. Use the principle of least privilege -- only grant what your specific workflow requires. If your agent only handles FAQ and onboarding, skip the moderation permissions entirely.

Can the agent moderate content in real time without being too aggressive?

Yes, and this is where the SOUL.md guardrails are critical. You define a confidence threshold -- the agent only takes automatic action on clear violations (spam links, slurs, explicit content) and flags borderline cases for human review. The template includes a three-tier moderation system: auto-remove (high confidence violations), flag for review (medium confidence), and ignore (low confidence). You tune these thresholds based on your community's tolerance level.

How do I keep the agent from hallucinating answers to community questions?

The template restricts the agent to a curated knowledge base. The FAQ skill only answers questions that match entries in a knowledge file you maintain. If the agent cannot find a confident match, it responds with a templated "I am not sure about that -- let me ping a team member" message and tags a human moderator. This prevents the agent from making up answers while still being helpful for known questions.

What happens if the agent goes down or makes a mistake?

The template includes a fallback system. If the agent process crashes, Discord events queue up and are processed when the agent restarts -- no messages are lost. For mistakes, every moderation action includes an "undo" window where human moderators can reverse the action. The agent also logs every action to a designated mod-log channel with its reasoning, making it easy to audit and correct. If deploying on managed hosting, you get automatic restarts and uptime monitoring.