OpenClaw Discord Bot: Complete Setup Guide (2026)

Last updated: May 1, 2026 · By the LobsterDome Editorial Team · 10 min read

OpenClaw is a personal AI assistant that lives on your machine — but with the Discord integration, it becomes available anywhere you and your team are chatting. Whether you want your AI agent answering questions in your community server, helping your dev team with code lookups, or acting as an always-on assistant in a private channel, the OpenClaw Discord bot setup takes less than five minutes once you know the steps.

{/* SEO IMAGE SUGGESTIONS:

• Add screenshot of Discord Developer Portal 'New Application' button with alt='Discord Developer Portal New Application screen'
• Add screenshot of Bot token page with alt='Discord Bot token page showing token copy button'
• Add screenshot of openclaw.json config snippet with alt='OpenClaw Discord plugin configuration example'
• Add screenshot of bot responding in Discord channel with alt='OpenClaw bot responding to @mention in Discord' */}

This guide covers everything: creating the Discord application, wiring up your openclaw.json config, inviting the bot to your server, and troubleshooting the most common problems people run into. If you're in a hurry, jump straight to the Quick-Start section below.

Table of Contents

1. Quick-Start: Under 5 Minutes
2. Prerequisites
3. Step-by-Step Setup
   • Step 1 – Create a Discord Application & Bot
   • Step 2 – Copy Your Bot Token
   • Step 3 – Configure openclaw.json
   • Step 4 – Invite the Bot to Your Server
   • Step 5 – Pair with OpenClaw
4. Permissions & Security Best Practices
5. Advanced Configuration
6. Real-World Use Cases
7. OpenClaw vs Other Discord AI Bots
8. Troubleshooting Common Issues
9. FAQ

Quick-Start: Under 5 Minutes

Impatient? Here's the shortest path to a working bot.

1. Go to discord.com/developers/applications → New Application → name it → save.
2. Open Bot tab → Add Bot → copy the token.
3. Add to your openclaw.json (see below).
4. Restart OpenClaw.
5. Use the OAuth2 URL to invite the bot to your server.
6. Type @YourBot hello in any channel — done.

For the full walkthrough with security notes, read on.

Prerequisites

Before starting the OpenClaw Discord bot setup, make sure you have:

• OpenClaw installed and running on your host machine (v1.4+ recommended). See the OpenClaw Installation Guide if you haven't done this yet.
• A Discord account with the ability to create applications (free, no Nitro required).
• Server permissions — you need Manage Server or higher on the Discord server you're adding the bot to, or be the server owner.
• Your openclaw.json config file accessible — usually at ~/.openclaw/openclaw.json on Linux/macOS or %APPDATA%\openclaw\openclaw.json on Windows.
• Node.js 18+ installed (OpenClaw bundles this, so if OpenClaw runs, you're fine).

💡 Not sure which version of OpenClaw you're running? Execute openclaw --version in your terminal. The Discord plugin requires OpenClaw 1.2.0 or later.

Step-by-Step OpenClaw Discord Bot Setup

Step 1 – Create a Discord Application & Bot

1. Navigate to the Discord Developer Portal and log in.
2. Click New Application in the top-right corner.
3. Give your application a name — something like OpenClaw or Hal (whatever you want the bot to appear as). Click Create.
4. In the left sidebar, click Bot.
5. Click Add Bot → confirm with Yes, do it!
6. Under the bot's username, toggle the following Privileged Gateway Intents ON:
   • ✅ Message Content Intent — required for the bot to read messages.
   • ✅ Server Members Intent — needed if you want the bot to respond to member events.
   • ✅ Presence Intent — optional, useful for status-aware responses.
7. Click Save Changes.

⚠️ Important: The Message Content Intent is mandatory. Without it, your bot will come online but won't be able to read or respond to messages.

Step 2 – Copy Your Bot Token

1. Still on the Bot page, click Reset Token (or Copy if shown).
2. Confirm the reset if prompted — Discord will show you the token once. Copy it immediately.
3. Store it somewhere safe (a password manager, or directly in your config as shown below). Never share this token publicly — anyone with it controls your bot.

Step 3 – Configure openclaw.json

Open your OpenClaw configuration file and add the Discord plugin block. Here's a minimal working config:

{
  "plugins": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN_HERE",
      "channels": ["general", "ai-assistant"],
      "prefix": "@bot",
      "respondToMentions": true,
      "respondToDMs": true
    }
  }
}

Full configuration reference:

{
  "plugins": {
    "discord": {
      "enabled": true,
      "token": "MTExxx...your_token_here",
      "guildId": "YOUR_SERVER_ID",
      "channels": ["general", "ai-assistant", "dev-help"],
      "prefix": "@OpenClaw",
      "respondToMentions": true,
      "respondToDMs": true,
      "allowedRoles": ["Admin", "Moderator", "Members"],
      "blockedUsers": [],
      "maxMessageLength": 2000,
      "typingIndicator": true,
      "replyInThread": false,
      "model": "glm5",
      "systemPrompt": "You are a helpful assistant in this Discord server. Keep responses concise.",
      "rateLimit": {
        "messagesPerMinute": 20,
        "cooldownSeconds": 3
      }
    }
  }
}

Key config fields explained:

💡 Pro tip: Use an environment variable instead of hardcoding the token:

"token": "${DISCORD_BOT_TOKEN}"

Then set DISCORD_BOT_TOKEN=your_token in your shell environment or a .env file. This keeps secrets out of your config file.

Step 4 – Invite the Bot to Your Server

1. Back in the Discord Developer Portal, click OAuth2 → URL Generator in the left sidebar.
2. Under Scopes, check:
   • ✅ bot
   • ✅ applications.commands (for slash commands, if you want them)
3. Under Bot Permissions, check:
   • ✅ Read Messages/View Channels
   • ✅ Send Messages
   • ✅ Send Messages in Threads
   • ✅ Embed Links
   • ✅ Read Message History
   • ✅ Add Reactions
4. Copy the generated URL at the bottom.
5. Paste it in your browser, select your server, and click Authorize.

The bot will appear in your server's member list as offline until OpenClaw is (re)started.

Step 5 – Pair with OpenClaw

1. Save your updated openclaw.json.
2. Restart the OpenClaw gateway:

   openclaw gateway restart
   

3. Check the gateway status:

   openclaw gateway status
   

   You should see discord: connected in the plugin status output.
4. Head to your Discord server and type in one of your configured channels:

   @YourBotName hello
   

5. If everything is wired up, you'll get a response within a second or two. 🎉

Permissions & Security Best Practices

Running an AI bot in a shared server comes with responsibility. Follow these practices to keep things secure:

Least-Privilege Permissions

Only grant the bot permissions it actually needs. Avoid giving Administrator permission — it's almost never required and creates unnecessary risk.

Minimum viable permissions for most setups:

• Read Messages
• Send Messages
• Embed Links
• Read Message History
• Add Reactions

Scope the Bot to Specific Channels

Use the channels config array to limit which channels the bot monitors. This prevents the bot from accidentally responding in announcements, support tickets, or sensitive channels.

"channels": ["ai-chat", "dev-questions"]

Role-Based Access Control

Restrict who can query the bot using allowedRoles:

"allowedRoles": ["Members", "Verified", "Staff"]

This ensures unverified or guest users can't query your AI agent.

Rate Limiting

Enable rate limiting to prevent abuse — especially important in public servers:

"rateLimit": {
  "messagesPerMinute": 10,
  "cooldownSeconds": 5
}

🔒 Related reading: OpenClaw Security Hardening Guide — covers token rotation, firewall rules, and audit logging.

Advanced Configuration

Multi-Server Deployment

You can connect one OpenClaw instance to multiple Discord servers by running multiple gateway instances or using the guildId field to route configurations:

{
  "plugins": {
    "discord": {
      "enabled": true,
      "token": "${DISCORD_BOT_TOKEN}",
      "instances": [
        {
          "guildId": "111222333444555666",
          "channels": ["ai-general"],
          "model": "llama",
          "systemPrompt": "You are a community assistant."
        },
        {
          "guildId": "999888777666555444",
          "channels": ["dev-ai", "code-help"],
          "model": "sonnet",
          "systemPrompt": "You are a senior software engineer assistant."
        }
      ]
    }
  }
}

Thread Mode

Enable replyInThread: true to have the bot create a dedicated thread for every conversation. This keeps your main channels clean:

"replyInThread": true,
"threadAutoArchiveDuration": 60

Custom System Prompts Per Channel

You can tailor the bot's personality and knowledge focus by channel:

"channelOverrides": {
  "code-review": {
    "model": "sonnet",
    "systemPrompt": "You are a senior code reviewer. Be direct, precise, and flag security issues."
  },
  "brainstorming": {
    "model": "glm5",
    "systemPrompt": "You are a creative brainstorming partner. Expand on ideas, ask questions."
  }
}

Real-World Use Cases

1. Dev Team Knowledge Base

Many engineering teams set up OpenClaw in their #dev-help channel so junior devs can ask questions about internal tooling, architecture decisions, or coding patterns — getting instant answers without interrupting senior engineers. The bot can be pointed at internal documentation files as context.

2. Community Server Assistant

Public Discord communities (gaming, crypto, open-source projects) use OpenClaw to handle FAQs, explain concepts, and keep conversation flowing without mods having to repeat themselves. Combined with allowedRoles, you can gate the bot to verified members only.

3. Personal Research Assistant

For solo creators or researchers, the Discord bot means your AI agent is accessible from your phone via the Discord mobile app — no need to be at your desktop. Ask it to summarize articles, draft content, or look up information while you're on the go.

4. Customer Support Triage

Small SaaS businesses use OpenClaw in a private Discord support server to handle Tier-1 support questions. The bot handles common issues instantly; unresolved queries get escalated to a human via a #human-escalation channel.

5. Automated Monitoring Alerts

With custom cron jobs and the Discord plugin, OpenClaw can post system status updates, deployment notifications, or market alerts directly to a dedicated Discord channel — no external webhook service required.

OpenClaw vs Other Discord AI Bots

Bottom line: OpenClaw is the only self-hosted option with full LLM flexibility, persistent memory, and a real skill/tool system. You trade 3 extra minutes of setup for full data privacy and zero ongoing subscription costs.

Troubleshooting Common Issues

Bot Appears Offline in Discord

Symptom: The bot shows as offline even after restarting OpenClaw.

Fix:

1. Check gateway status: openclaw gateway status
2. Verify your token is correct in openclaw.json — re-copy it from the Developer Portal if unsure.
3. Ensure the gateway is actually running: openclaw gateway start
4. Check for errors: openclaw gateway logs --tail 50

Bot Doesn't Respond to Messages

Symptom: Bot is online (green dot) but doesn't reply when mentioned.

Checklist:

• ✅ Is the channel name in your channels array? (Case-sensitive!)
• ✅ Is Message Content Intent enabled in the Developer Portal?
• ✅ Does the bot have Read Messages permission in that channel?
• ✅ Are you mentioning the bot correctly (@BotName message)?
• ✅ Is the user's role in allowedRoles?

"Invalid Token" Error in Logs

Symptom: Gateway logs show DiscordAPIError: 401 Unauthorized or Invalid token.

Fix:

1. Go to the Developer Portal → Bot → Reset Token.
2. Copy the new token.
3. Update openclaw.json and restart the gateway.

Note: Tokens are invalidated automatically if you reset them or if your bot's username/avatar is changed by certain actions.

Bot Responds to Everything (Not Just Mentions)

Symptom: The bot responds to every message in monitored channels, not just @mentions.

Fix: Set respondToMentions: true and ensure you don't have a catch-all prefix like "":

"respondToMentions": true,
"prefix": null

Rate Limit Errors (429)

Symptom: Bot stops responding temporarily; logs show 429 Too Many Requests.

Fix: You're hitting Discord's API rate limits. Reduce message frequency or increase your cooldown:

"rateLimit": {
  "messagesPerMinute": 5,
  "cooldownSeconds": 10
}

Bot Works Locally But Not on VPS

Symptom: Discord bot works when running OpenClaw on your laptop but fails on a remote server.

Checklist:

• ✅ Is the gateway running on the VPS? (openclaw gateway status via SSH)
• ✅ Are outbound HTTPS connections allowed from the VPS? (port 443)
• ✅ Is the correct openclaw.json deployed to the VPS?
• ✅ Environment variables (DISCORD_BOT_TOKEN) set in the VPS environment?

🔗 See also: OpenClaw VPS Deployment Guide for full remote setup instructions.

FAQ

How long does OpenClaw Discord bot setup take?

For most users, under 5 minutes from start to first response. The main time sinks are creating the Discord application (2 min) and editing the config file (1–2 min). If you're troubleshooting permissions, add another 5 minutes.

Does OpenClaw need to be running for the Discord bot to work?

Yes. OpenClaw runs on your machine (or VPS), and the Discord bot is a plugin that connects through the OpenClaw gateway. If OpenClaw is off, the bot goes offline. For 24/7 availability, run OpenClaw on a VPS or always-on server.

Can I add the bot to multiple Discord servers?

Yes. You can invite the same bot application to multiple servers. Use the instances config array (see Advanced Configuration) to set different channels, models, and prompts per server.

Is my conversation data private?

Yes — because OpenClaw is self-hosted, your messages never leave your machine (unless your chosen LLM model routes data to an external API, like OpenAI). For full privacy, use a locally-running model via Ollama. See the OpenClaw Privacy Guide for details.

Can I use the bot with a free Discord account?

Yes. Creating Discord applications and bots requires a standard Discord account — no Nitro subscription or payment is needed to create or host bots.

What AI models can the OpenClaw Discord bot use?

Any model configured in your OpenClaw setup. This includes OpenAI (GPT-4.1), Anthropic (Claude), Fireworks (GLM-5, Llama, DeepSeek), and local models via Ollama. You can even set different models per channel. See OpenClaw Model Routing for the full list.

How do I update the bot's personality or behavior?

Edit the systemPrompt field in your openclaw.json Discord plugin config, then restart the gateway. You can also override it per-channel using channelOverrides. Changes take effect immediately on restart.

Can the bot access files or run code?

Yes, with the right skills enabled. OpenClaw's skill system lets the bot search the web, read files, run shell commands, check calendars, and more — all from within Discord. Enable or disable skills in your main openclaw.json to control what the bot can do. Use this carefully in public servers.

The bot stopped working after a Discord update. What do I do?

Check the OpenClaw changelog and Discord's developer announcements for breaking changes. Usually a gateway restart (openclaw gateway restart) resolves transient issues. For persistent problems, check the OpenClaw GitHub issues or the LobsterDome community Discord.

How do I remove or disable the Discord bot?

To disable without removing config:

"discord": { "enabled": false }

To fully remove: delete the discord block from openclaw.json and restart the gateway. To remove the bot from a server, kick it like any other member from Server Settings → Members.

Wrapping Up

The OpenClaw Discord bot setup is one of the most powerful ways to extend your AI agent beyond your desktop. In five minutes, you go from a local assistant to a team-accessible, always-available bot that respects your data privacy and runs on your terms.

The key takeaways:

• Create your Discord application, enable Message Content Intent, and copy your token.
• Add the discord plugin block to openclaw.json.
• Restart the gateway and invite the bot to your server.
• Use allowedRoles, channels, and rateLimit to keep things secure and focused.
• For 24/7 uptime, deploy OpenClaw on a VPS.

Next steps:

• 📖 OpenClaw Skills Directory — browse tools you can enable for the Discord bot
• 🔒 OpenClaw Security Hardening Guide — lock down your bot in production
• 🚀 OpenClaw VPS Deployment Guide — always-on bot setup
• 🤖 OpenClaw Model Routing Guide — choose the right AI model per task

Have questions or ran into an issue not covered here? Drop a comment below or join the LobsterDome Discord community where OpenClaw users share configs, tips, and workarounds.

{/* SCHEMA MARKUP SUGGESTION: Implement Article JSON-LD for rich snippets. Example:

*/}

Article reviewed for accuracy on May 1, 2026. OpenClaw is under active development — configuration options may change in future releases. Always check the official OpenClaw docs for the latest reference.