Discord setup for OpenClaw

Run your agent inside Discord DMs, private servers, channels, threads, forums, and approval workflows with the right bot permissions from day one.

Why Discord is worth setting up

Discord takes more setup than Telegram because you create a bot application, choose gateway intents, and invite it to a server. The payoff is a durable agent workspace: DMs for private chat, isolated server channels for different projects, threads for work queues, and components for approvals and forms.

DMs and servers

Use private DMs for personal tasks, then add the bot to a private server when you want project channels with separate session context.

Thread workflows

Forum and media channels can become lightweight task queues where every post has its own thread and conversation history.

Interactive approvals

Discord components support buttons, selects, modals, and ephemeral responses, which fits review and approval flows better than plain chat.

Access policy

OpenClaw can pair DMs, allowlist guilds, require mentions, and restrict component clicks to specific Discord users.

Connect Discord step by step

This assumes OpenClaw is already installed. If Discord is your first channel, use the CLI steps below. If you already have another channel live, you can ask that agent to finish the config after the token is stored securely.

Create a Discord application and bot

Open the Discord Developer Portal, create a new application, then open the Bot page. Set the bot username to whatever you call your OpenClaw agent.

For the cleanest setup, invite the bot to a private server you control. A one-person server is ideal for testing before adding the bot anywhere shared.

Enable gateway intents

On the bot page, scroll to Privileged Gateway Intents and enable the intents OpenClaw needs:

Message Content Intent is required so the agent can read messages.
Server Members Intent is recommended and needed for role allowlists and name-to-ID matching.
Presence Intent is optional and only needed if you want presence updates.

Copy the bot token and invite the bot

Still on the bot page, use Reset Token to reveal the first token and store it like a password. Then open OAuth2, use the URL generator, and select bot plus applications.commands.

Grant the baseline bot permissions OpenClaw needs for normal text channels:

View Channels
Send Messages
Read Message History
Embed Links
Attach Files
Add Reactions, if you want reaction workflows
Send Messages in Threads, if you plan to use thread or forum workflows

Copy the generated invite URL, open it, choose your server, and confirm. The bot should appear in the server member list.

Collect your server and user IDs

In Discord, enable Developer Mode, then copy the IDs OpenClaw will use for pairing and allowlists. On desktop: User Settings → Advanced → Developer Mode. Then right-click your server icon and copy the server ID, and right-click your own avatar to copy your user ID.

On mobile, Developer Mode is under App Settings → Advanced.

Store the token securely in OpenClaw

Set the token as an environment-backed secret reference instead of pasting it into chat:

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
cat > discord.patch.json5 <<'JSON5'
{
  channels: {
    discord: {
      enabled: true,
      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
    },
  },
}
JSON5
openclaw config patch --file ./discord.patch.json5 --dry-run
openclaw config patch --file ./discord.patch.json5
openclaw gateway

If OpenClaw runs as a managed service, put DISCORD_BOT_TOKEN in the service environment or ~/.openclaw/.env, then restart the gateway so the service can resolve the secret.

Approve your first DM pairing

Allow DMs from server members in that server's privacy settings, then DM your bot. OpenClaw should return a pairing code. Approve it from the CLI:

openclaw pairing list discord
openclaw pairing approve discord <CODE>

Pairing codes expire after one hour. Once approved, your Discord DM is live.

Turn a server into an agent workspace

For serious use, Discord works best as a private server where each channel maps to a separate OpenClaw session. Keep the policy strict while you test, then loosen only the pieces you actually need.

Allow your guild and require mentions

Add your server ID to the Discord guild allowlist. Start with requireMention: true so the agent only answers when addressed in channel:

{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        YOUR_SERVER_ID: {
          requireMention: true,
          users: ["YOUR_USER_ID"],
        },
      },
    },
  },
}

For a private one-person server, you can later set requireMention: false. In shared rooms, keep mention gating or use ambient room events so the agent only posts when a tool send is intentional.

🧠

Plan memory boundaries

Discord guild channels are isolated from each other. That is useful: #coding, #ops, and #research can each keep their own context. It also means long-term memory should be deliberate.

Put stable shared rules in AGENTS.md or USER.md.
Use memory tools on demand when a guild channel needs long-term context.
Keep sensitive personal context out of channels where other humans can see replies.

🔒

Do not paste tokens into Discord

Bot tokens are account-level secrets. Store them in environment variables, files, or a secret provider, and send only non-secret IDs or pairing codes through chat.

Threads, forums, and components

🧵

Use threads for durable work items

Recommended

Discord forum and media channels only accept thread posts. OpenClaw can create a thread by sending to the forum parent, using the first non-empty line as the title, or by creating the thread explicitly:

openclaw message send --channel discord --target channel:<forumId> \
  --message "Topic title
Body of the post"

openclaw message thread create --channel discord --target channel:<forumId> \
  --thread-name "Topic title" --message "Body of the post"

Forum parents do not accept Discord components. Send buttons, selects, or forms to the thread itself with channel:<threadId>.

☑

Approval workflows

OpenClaw supports Discord components for agent messages: text, sections, separators, action rows, media galleries, files, buttons, select menus, and modal forms. Use allowedUsers on buttons when only a specific operator should approve a task.

Callbacks expire after 30 minutes by default. Extend channels.discord.agentComponents.ttlMs only when review workflows genuinely need longer-lived buttons.

Quick troubleshooting

🔧

Bot is online but silent?

Confirm Message Content Intent is enabled in the Developer Portal.
Check the bot has View Channels, Send Messages, and Read Message History in that Discord channel.
In guild channels, mention the bot if requireMention: true.
Make sure the server ID is listed under channels.discord.guilds when group policy is allowlist.
If DM pairing does not start, allow direct messages from server members for the server where the bot lives.

🧪

Useful checks

openclaw channels list
openclaw channels status
openclaw channels capabilities --channel discord
openclaw doctor --fix

If startup is blocked or rate-limited during Discord's application lookup, set channels.discord.applicationId from the Developer Portal so OpenClaw can skip that startup REST call.