Guide

OpenClaw Discord Integration: 4-Step Developer Quickstart, $16/mo Host

2026-10-09

OpenClaw Discord Integration: 4-Step Developer Quickstart, $16/mo Host

Yes, OpenClaw integrates with Discord as a bot over the official Gateway, supporting both direct messages and guild channels. Create a Discord application, copy the bot token into DISCORD_BOT_TOKEN or channels.discord.token, and start the OpenClaw gateway. Then DM the bot to get a pairing code and approve it with openclaw pairing approve discord .

***

> TL;DR:

>

> - Enable Message Content Intent in Discord’s Developer Portal; a mismatch between enabled and requested privileged intents can close the Gateway with error 4013 or 4014.

> - Store the token in an environment variable when possible; config file tokens take precedence, and any token or intent change requires a gateway restart.

> - DM pairing authorizes only the individual account, not a server; configure guild access separately with numeric user IDs, an allowlist, and mention requirements.

> - Voice is off by default; enable it, set allowed channels and auto join behavior, and grant Connect, Speak, Send Messages, and Read Message History.

> - If the bot appears online but stays silent, check intents and thread permissions, then run openclaw doctor and openclaw channels status --probe.

***

Table of Contents

Quickstart checklist for a working test bot

We like to get a bot online in a private server before touching production channels; you might also find useful insights on optimizing your communications workflows with Slack Call Notifications for Canadian Ops in this integrated automation guide. It gives us a safe space to watch the Discord setup documentation play out against real Gateway behavior, intents, and permission scopes, without risking a live workspace.

Here is the minimum path from zero to a responding bot:

  1. In the Discord Developer Portal, create an application, add a Bot user, and enable the intents your workflow needs.
  2. Generate an OAuth2 invite URL with the bot and applications.commands scopes, plus baseline permissions.
  3. Set the bot token through DISCORD_BOT_TOKEN or channels.discord.token, then start the OpenClaw gateway.
  4. Send the bot a direct message, copy the pairing code it returns, and approve it from your terminal.

Once pairing succeeds, the agent can read and reply inside the channels you have authorized. Everything past this point is about tightening permissions, routing, and reliability rather than getting the connection itself to work.

Creating the Discord application and bot correctly

Most integration failures trace back to a handful of portal settings rather than anything in OpenClaw's own config. We treat this step as worth doing slowly, since fixing a missing intent after the fact usually means another restart cycle.

  • Go to Applications, click New Application, add a Bot, then reset and copy the token. Store it immediately. Discord will not show it again.
  • Enable Message Content Intent under Privileged Gateway Intents. Ordinary guild messages are unreadable without it. Enable Server Members Intent only if you are building allowlists from member data, and treat Presence Intent as optional.
  • In the OAuth2 URL Generator, select the bot and applications.commands scopes, then check View Channels, Send Messages, Read Message History, Embed Links, Attach Files, and Send Messages in Threads if your workflow touches thread conversations.
  • Turn on Developer Mode in Discord's own settings (Advanced) so you can right-click to copy Server ID, User ID, and Channel ID values for config files.

Per the Discord setup docs, the bot connects through Discord's official Gateway and supports both DMs and guild channels once these pieces are in place.

Setting the bot token in OpenClaw and completing pairing

Configuration precedence matters here: channels.discord.token in your config file takes priority over the DISCORD_BOT_TOKEN environment variable, which acts as a fallback. A JSON5 snippet referencing a secret looks like this:

  • channels.discord.token: { secretRef: "env:DISCORD_BOT_TOKEN" }
  • channels.discord.applicationId: "your-application-id"

Run openclaw gateway to start the connection directly, or openclaw gateway install if you want it managed as a background service. Restart the gateway any time you change token placement or intents, since those values are read at startup, not hot-reloaded.

Pairing itself is a short handshake: DM the bot from your Discord account, it replies with a short code, and you approve that code from the machine running OpenClaw with openclaw pairing approve discord . Approving a DM pairs your user identity; it does not by itself authorize any guild.

Pro Tip: *Keep the token in an environment variable rather than hardcoded in a config file you might commit, and lock file permissions on any config that does hold it directly.*

Controlling access with DM policy, allowlists, and mentions

Discord access and OpenClaw's own authorization are two separate layers, and conflating them is the most common misconfiguration we see. Per the access control documentation, DM policy and guild handling are governed independently.

  • Set dmPolicy to pairing, allowlist, open, or disabled depending on how open you want direct messages to be.
  • Use groupPolicy: "allowlist" with guilds.YOUR_SERVER_ID.requireMention: true to restrict a guild workspace and force explicit mentions before the agent replies.
  • Build allowlists with stable numeric Discord IDs, not display names. Name matching is disabled by default and exists only as a break-glass fallback, flagged as dangerouslyAllowNameMatching for a reason.
  • Threads inherit the permission and allowlist settings of their parent channel, so a restricted channel stays restricted in its threads.

Pro Tip: *Approving a DM pairing request only authorizes that individual user; it grants nothing server-wide, so configure guild allowlists deliberately.*

How messages route, thread, and stream back to Discord

Session scoping decides how much context the agent keeps per conversation. Direct messages typically map to your main session, while guild channels get isolated per-channel session keys so a conversation in one channel does not bleed into another.

Reply behavior is configurable through replyToMode, which controls whether responses reference the original message, start a thread, or reply inline, useful to tune depending on how chatty a channel already is.

  • OpenClaw suppresses rich link embeds by default; set channels.discord.accounts..suppressEmbeds to false if your workflow depends on them.
  • Streaming previews are governed by textChunkLimit and maxLinesPerMessage, which cap how much partial output appears before the final message lands.
  • Per the messaging behavior docs, reply routing back to Discord is deterministic, and these defaults are meant to be tuned in staging before a wider rollout.

Enabling voice channels and auto-join behavior

Voice support is strictly opt-in. Set channels.discord.voice.enabled to true, then configure allowedChannels and autoJoin to control which voice channels the agent can enter and whether it joins automatically.

In the target voice channel, grant Connect, Speak, Send Messages, and Read Message History, per the voice channels documentation. From there, native slash commands /vc join, /vc leave, and /vc status manage the session directly. Watch for speech-to-text or transcript failures under heavy background noise or overlapping speakers, since those are the most common breakdowns in realtime voice.

Voice channel access and session permissions

Troubleshooting a bot that connects but won't respond

A bot that shows online in Discord but ignores messages almost always traces to one of a small set of causes. Run through these in order before digging deeper:

  1. Confirm privileged intents are enabled in the Developer Portal and that your requested Gateway intents match your config, since a mismatch is what triggers the Gateway's 4013 or 4014 close codes according to the troubleshooting docs.
  2. Check channel-level permissions, including Send Messages in Threads if the conversation lives inside one.
  3. Verify the token is set where you think it is: config takes precedence over environment variables, and a changed value needs a gateway restart to take effect.
  4. Run openclaw doctor for a general health scan, and openclaw channels status --probe to surface connection-specific warnings.

Discord enforces privileged intents strictly: requesting Message Content or Server Members without enabling them in the portal closes the Gateway connection outright, which is why intent mismatches are the single most common cause of a silent bot. Our own troubleshooting walkthrough covers the same checks in more depth if you want a second pass.

Configuration reference for channels.discord

The keys you will touch most often live under channels.discord. Beyond enabled and token, expect to configure applicationId, per-account settings under accounts.*, groupPolicy, dmPolicy, guild-specific overrides under guilds, intent toggles, replyToMode, streaming limits, and the voice block covered above.

  • A private guild workspace with no mention requirement needs groupPolicy: "open" and guilds.YOUR_SERVER_ID.requireMention: false.
  • An allowlist entry pairs a server ID with specific authorized user IDs under that same guild block.
  • Disabling the privileged Message Content intent (when you only need DMs or mention-based replies) means setting intents.messageContent to false.
Config keyPurpose
`channels.discord.token`Bot token, ideally a SecretRef to an environment variable
`channels.discord.applicationId`Discord application ID for OAuth2 and command registration
`channels.discord.groupPolicy`Guild-wide policy: open, allowlist, or disabled
`channels.discord.dmPolicy`DM policy: pairing, allowlist, open, or disabled
`channels.discord.guilds`Per-guild overrides including requireMention and allowlists
`channels.discord.voice.enabled`Toggles realtime voice support

The integration itself ships as the @openclaw/discord plugin, installable via npm or ClawHub, and our own hosting walkthrough covers the install routes if you are wiring this up on managed infrastructure.

What we'd test before a wider rollout

We always start new bots in a throwaway private server, with the narrowest set of privileged intents the workflow actually needs and numeric IDs everywhere instead of display names, which drift. Self-hosting gives you full control over every config key above, but it also means you own restarts, rate limit handling, and token rotation. Managed hosting trades some of that control for less ongoing maintenance. Either way, treat the bot token as a secret from day one.

> *— Iosif Peterfi*

A no-maintenance path if you'd rather skip the ops work

If running your own gateway, handling restarts, and rotating tokens isn't how you want to spend your week, we built ClawBase to deploy OpenClaw on a dedicated server with one click. You still connect Discord, Telegram, or Slack and write your own config exactly as described above; we just handle uptime, persistent memory, and daily backups behind it.

Clawbase
  • One-click deployment on a dedicated server, no sysadmin work required.
  • High uptime with daily backups and automated updates.
  • Access to the Discord configuration options covered in this guide.

Plans start at $16 per month on the LITE tier, with PRO and MAX tiers available for heavier usage. Check current pricing and get started on Clawbase.

FAQ

What permissions does a Discord bot need for OpenClaw?

At minimum, grant View Channels, Send Messages, Read Message History, Embed Links, and Attach Files, plus Send Messages in Threads if thread conversations are part of your workflow. These are the baseline permissions recommended in the OpenClaw Discord setup docs.

Why does my bot connect but never respond to messages?

The most common cause is a privileged intent mismatch: Message Content Intent must be enabled in the Developer Portal, or Discord closes the Gateway connection with a 4013 or 4014 error, according to the troubleshooting guide. Run openclaw doctor and openclaw channels status --probe to confirm which check is failing.

Does pairing with a bot give it access to my whole server?

No. Approving a DM pairing code authorizes your individual user identity only, not the guild itself, per the access control documentation. Guild-wide access is configured separately through groupPolicy and allowlists.

Can I run OpenClaw's Discord integration without managing my own server?

Yes. Self-hosting gives you direct control over every config file and restart cycle, while a managed option like ClawBase deploys OpenClaw on a dedicated server with one click and handles uptime and backups for you.

How do I enable voice features in the Discord integration?

Set channels.discord.voice.enabled to true and configure allowedChannels and autoJoin, then grant Connect, Speak, Send Messages, and Read Message History in the target voice channel, as described in the voice channels docs. From there, the native /vc join, /vc leave, and /vc status commands manage sessions directly.

Recommended