Discord setup

Everything needed to get a Discord bot running: create the application, grant intents, invite it to a server, pair it, and prepare a guild workspace.

Quick setup

Create a Discord application with a bot, add the bot to your server, and pair it with OpenClaw. Use a private server if you can; create one first (Create My Own > For me and my friends) if needed.

Create a Discord application and bot

In the Discord Developer Portal, click New Application and name it (for example "OpenClaw").

Open Bot in the sidebar and set the Username to your agent's name.

Enable privileged intents

Still on the Bot page, under Privileged Gateway Intents enable:

• Message Content Intent (required for normal guild messages)
• Server Members Intent (recommended; required for role allowlists, name-to-ID matching, and channel-audience access groups)
• Presence Intent (optional; only for presence updates)

Copy your bot token

On the Bot page, click Reset Token and copy the token.

Generate an invite URL and add the bot to your server

Open OAuth2 in the sidebar. In the OAuth2 URL Generator, enable the scopes:

• bot
• applications.commands

In the Bot Permissions section that appears, enable at least:

General Permissions

• View Channels

Text Permissions

• Send Messages
• Read Message History
• Embed Links
• Attach Files
• Add Reactions (optional)

That is the baseline for normal text channels. If the bot will post in threads — including forum or media channel workflows that create or continue a thread — also enable Send Messages in Threads.

Copy the generated URL, open it in a browser, select your server, and click Continue. The bot should now appear in your server.

Enable Developer Mode and collect your IDs

In the Discord app, enable Developer Mode so you can copy IDs:

1. User Settings (gear icon) → Developer → toggle on Developer Mode (on mobile: App Settings → Advanced)
2. Right-click your server icon → Copy Server ID
3. Right-click your own avatar → Copy User ID

Keep the Server ID and User ID with your bot token; you need all three next.

Allow DMs from server members

For pairing to work, Discord must let the bot DM you. Right-click your server icon → Privacy Settings → toggle on Direct Messages.

Keep this on if you use Discord DMs with OpenClaw. If you only use guild channels, you can disable it after pairing.

Set your bot token securely (do not send it in chat)

The bot token is a secret. Set it on the machine running OpenClaw before messaging your agent:

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 already runs as a background service, restart it via the OpenClaw Mac app or by stopping and restarting the `openclaw gateway run` process.
For managed service installs, run `openclaw gateway install` from a shell where `DISCORD_BOT_TOKEN` is set, or store the variable in `~/.openclaw/.env` so the service can resolve the env SecretRef after restart.
If your host is blocked or rate-limited by Discord's startup application lookup, set the application/client ID from the Developer Portal so startup can skip that REST call: `channels.discord.applicationId` for the default account, or `channels.discord.accounts.<accountId>.applicationId` per bot.

Configure OpenClaw and pair

Ask your agent

Chat with your OpenClaw agent on an existing channel (for example Telegram) and tell it. If Discord is your first channel, use the CLI / config tab instead.

"I already set my Discord bot token in config. Please finish Discord setup with User ID <user_id> and Server ID <server_id>."

CLI / config

    File-based config:

{
  channels: {
    discord: {
      enabled: true,
      token: {
        source: "env",
        provider: "default",
        id: "DISCORD_BOT_TOKEN",
      },
    },
  },
}

    Env fallback for the default account:

DISCORD_BOT_TOKEN=...

    For scripted or remote setup, write the same JSON5 block with `openclaw config patch --file ./discord.patch.json5 --dry-run`, then rerun without `--dry-run`. Plaintext `token` strings work too, and SecretRef values are supported for `channels.discord.token` across env/file/exec/store providers. See [Secrets Management](/agents/openclaw/gateway/secrets/).

    For multiple Discord bots, keep each bot token and application ID under its account. A top-level `channels.discord.applicationId` is inherited by accounts, so only set it there when every account uses the same application ID.

{
  channels: {
    discord: {
      enabled: true,
      accounts: {
        personal: {
          token: { source: "env", provider: "default", id: "DISCORD_PERSONAL_TOKEN" },
          applicationId: "111111111111111111",
        },
        work: {
          token: { source: "env", provider: "default", id: "DISCORD_WORK_TOKEN" },
          applicationId: "222222222222222222",
        },
      },
    },
  },
}

Approve first DM pairing

Once the gateway is running, DM your bot in Discord. It replies with a pairing code.

Ask your agent

Send the pairing code to your agent on your existing channel:

"Approve this Discord pairing code: ``"

CLI

openclaw pairing list discord
openclaw pairing approve discord <CODE>

Pairing codes expire after 1 hour. After approval, chat with your agent in a Discord DM.

If Discord cannot grant Message Content Intent, OpenClaw can still operate in DMs and in guild channels where users explicitly mention the bot. Set channels.discord.intents.messageContent: false so the Gateway does not request the unavailable privileged intent, and keep requireMention: true on every configured guild channel. Discord omits user-authored content from other guild messages in this mode.

Recommended: Set up a guild workspace

Once DMs work, you can turn your server into a full workspace where each channel gets its own agent session with its own context. Recommended for private servers where it is just you and your bot.

Add your server to the guild allowlist

This lets your agent respond in any channel on your server, not just DMs.

Ask your agent

"Add my Discord Server ID <server_id> to the guild allowlist"

Config

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

Allow responses without @mention

By default, the agent only responds in guild channels when @mentioned. On a private server you probably want it to respond to every message.

In guild channels, normal replies post automatically by default. For shared always-on rooms, opt into `messages.groupChat.visibleReplies: "message_tool"` so the agent can lurk and only post when it decides a channel reply is useful. This works best with latest-generation, tool-reliable models such as GPT-6 Astra. Ambient room events stay quiet unless the tool sends. See [Ambient room events](/agents/openclaw/channels/ambient-room-events/) for the full lurk-mode config.

If Discord shows typing and the logs show token usage but no posted message, check whether the turn was configured as an ambient room event or opted into message-tool visible replies.

Session-busy notices also respect this reply policy. For ambient events and message-tool replies, Discord records the failure and suppressed notice in Gateway logs without posting to the room.

Ask your agent

"Allow my agent to respond on this server without having to be @mentioned"

Config

    Set `requireMention: false` in your guild config:

{
  channels: {
    discord: {
      guilds: {
        YOUR_SERVER_ID: {
          requireMention: false,
        },
      },
    },
  },
}

    To require message-tool sends for visible group/channel replies, set `messages.groupChat.visibleReplies: "message_tool"`.

Plan for memory in guild channels

Long-term memory (MEMORY.md) only auto-loads in DM sessions; guild channels do not load it.

Ask your agent

"When I ask questions in Discord channels, use memory_search or memory_get if you need long-term context from MEMORY.md."

Manual

For shared context in every channel, put stable instructions in AGENTS.md or USER.md (injected for every session). Keep long-term notes in MEMORY.md and access them on demand with memory tools.

Now create channels and start chatting. The agent sees the channel name, and each channel is an isolated session — set up #coding, #home, #research, or whatever fits your workflow.