How to connect OpenClaw to Discord (and fix it when it goes quiet)

To connect OpenClaw to Discord, create a Discord application with a bot user, turn on the Message Content intent, invite the bot with the bot and applications.commands scopes, install the @openclaw/discord plugin, give the gateway the token through the DISCORD_BOT_TOKEN environment variable, and approve your first DM with openclaw pairing approve discord <CODE>. Your OpenClaw Discord bot then answers your DMs.

It stays silent in servers until you add the server to channels.discord.guilds. That is the most common reason an OpenClaw Discord bot shows as online but ignores everyone, and it is what happened to me.

I connected my own OpenClaw gateway to Discord on September 4, 2026, on version 2026.9.1, and hit several of the problems in the troubleshooting section. This guide was checked on September 27, 2026 against OpenClaw 2026.9.6, the @openclaw/discord 2026.9.6 plugin and the official docs. Every config block below passed openclaw config validate on my 2026.9.1 CLI and the config schema shipped in the 2026.9.6 Discord plugin.

What you need first

• OpenClaw installed and onboarded. openclaw status should show a running gateway and a configured model. Current releases need Node 24.16+ or 26.1+, and the official installer sets that up.
• A machine that stays on. The gateway holds the Discord connection, so when the machine sleeps, the bot goes offline. The 24/7 hosting guide covers keeping a process running.
• A Discord server where you have Manage Server. A private server with just you and the bot is the safest place to start.

I installed OpenClaw as a global npm package and run the gateway as a background service. It binds to loopback, ws://127.0.0.1:18789, by default. Leave that alone: the Discord connection is outbound, so Discord never needs to reach the gateway.

Step 1: Create the Discord application and bot

The bot is a normal Discord application, the same kind you would create for any bot.

1. Open the Discord Developer Portal, click New Application and name it.
2. Open Bot and set the username your agent should have.
3. Turn Public Bot off. Discord's docs say that when it's unchecked, "only you can add the bot to guilds," which is what you want for a personal agent.
4. Click Reset Token and copy the token. On a new app this creates the first token; nothing is being reset.

Keep the token out of chats, including chats with the agent itself. The bot token guide explains what it grants and what to do if it leaks.

Step 2: Turn on the intents OpenClaw uses

On the same Bot page, under Privileged Gateway Intents:

Since June 10, 2026, an app that fewer than 10,000 unique users can see switches these on in the portal without a review, though Discord asks you to enable only the intents the app actually needs. A personal agent is nowhere near that line.

If you'd rather not grant Message Content, OpenClaw can run mention-only. DMs and messages that @mention the bot still carry their text, so set this and keep requireMention: true on every server you allow:

{
  channels: {
    discord: {
      intents: { messageContent: false },
    },
  },
}

Step 3: Invite the bot with the permissions it needs

Open OAuth2, then URL Generator, and tick the bot and applications.commands scopes. OpenClaw's docs list the permissions below as the baseline for text channels. The integers are those same sets worked out from Discord's permission table:

Leave Administrator off. You can build the invite link, or decode one you already have, with the permissions calculator. Open the link, pick your server and authorize. The guide to adding bots covers the cases where your server doesn't show up.

Two small things in the Discord app before you move on:

• Turn on Developer Mode under User Settings > Advanced, then right-click the server icon for Copy Server ID and your avatar for Copy User ID. You need both in Step 6.
• For pairing, the bot has to be able to DM you: right-click the server icon, open Privacy Settings and turn on Direct Messages.

Step 4: Install the plugin and give OpenClaw the token

The Discord channel is a plugin. In current releases it is an official external package, @openclaw/discord, and not part of the core install:

openclaw plugins install @openclaw/discord

Then give the gateway the token as an environment variable reference, so the token itself never sits in the config file:

export DISCORD_BOT_TOKEN="paste-your-token-here"

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

openclaw config patch --file ./discord.patch.json5 --dry-run
openclaw config patch --file ./discord.patch.json5
openclaw gateway restart

dmPolicy: "pairing" and groupPolicy: "allowlist" are the defaults. I write them out so the file says what the bot will do. The dry run also resolves the token reference, so it stops with Environment variable "DISCORD_BOT_TOKEN" is missing or empty if the token is in neither your shell nor ~/.openclaw/.env.

A background service doesn't see variables you export in a terminal. Either put DISCORD_BOT_TOKEN=... in OpenClaw's global .env file (~/.openclaw/.env by default), or reinstall the service with openclaw gateway install from a shell where the variable is set.

There is also a one-command route: openclaw channels add --channel discord --use-env installs the plugin if it's missing and writes the channel config from DISCORD_BOT_TOKEN. Avoid the --token flag, which puts the token on the command line. The export line above lands in your shell history too, so on a shared machine put the token straight into ~/.openclaw/.env instead.

Check the connection:

openclaw channels status --probe

Step 5: Approve your first DM

On my gateway the Discord DM channel runs in pairing mode. A new DM gets a short code, and nothing reaches the agent until I approve it:

openclaw pairing list discord
openclaw pairing approve discord <CODE>

Codes expire after an hour. OpenClaw only sends the pairing message when it creates a new request, about once per hour per sender, and keeps at most 3 pending requests per account. So a second DM a minute later gets no new code; look in openclaw pairing list discord instead.

If you'd rather skip pairing, set dmPolicy: "allowlist" and allowFrom: ["YOUR_USER_ID"]. Never use dmPolicy: "open" on an agent that can run tools.

Step 6: Let it answer in your server

My bot answered DMs from the start and ignored my server. That is groupPolicy: "allowlist" working as designed: once a channels.discord block exists, every server message is dropped until the server is listed under guilds. Current releases also print a warning in openclaw channels status when the policy is allowlist and no guilds are configured.

This allows one server, one channel and one person:

{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        "123456789012345678": {           // your Server ID
          requireMention: true,
          users: ["987654321098765432"],  // your User ID
          channels: {
            // the one channel where it answers without an @mention
            "234567890123456789": { enabled: true, requireMention: false },
          },
        },
      },
    },
  },
}

The rules that trip people up, from OpenClaw's access-control docs:

• A server entry with no channels map lets the bot work in every channel it can see.
• Adding even one channel entry turns the map into an allowlist, and every unlisted channel is denied. Add a "*" entry if the rest of the server should keep the server defaults.
• users and roles take IDs. A sender is allowed if they match either list. Name matching is off unless you turn on dangerouslyAllowNameMatching.
• Server messages need an @mention unless requireMention: false is set on the server or the channel.

Run openclaw config validate before you restart. In my test it rejected a mistyped requireMentionn with "must not have additional properties" and named the exact key.

Keep the agent on a short leash

An OpenClaw agent can do whatever its tools allow on the machine it runs on, and anyone who can message it can ask. OpenClaw's security docs assume "one trust boundary per gateway," meaning one operator or a team whose members trust each other, and say OpenClaw "is not a hostile multi-tenant security boundary." Scope it accordingly:

• DMs: keep pairing or an allowlist, and approve only people you'd give a shell to.
• Servers: allowlist one server, one or two channels, and your user ID or a staff role.
• Discord actions: moderation, roles and presence actions are off by default under channels.discord.actions. Leave them off unless you want the agent able to time out, kick or ban.
• Tools: for any agent other people can reach, start from OpenClaw's hardened baseline, which denies runtime, file system and automation tool groups.
• Discord side: no Administrator permission, Public Bot off.
• Gateway: stay on loopback, and run openclaw security audit after every config change.

Troubleshooting an OpenClaw Discord bot

Start with the command ladder from OpenClaw's own troubleshooting page, which usually names the problem:

openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw logs --follow
openclaw doctor

The bot shows as offline

Work down this list:

1. The gateway isn't running. Check openclaw gateway status. If the machine slept or rebooted without the service, start it.
2. The plugin isn't loaded. openclaw channels status keeps a configured channel visible when its plugin fails to load, marked blocked with the plugin error. Install it with openclaw plugins install @openclaw/discord. After an update, OpenClaw's docs suggest openclaw doctor --fix, then openclaw gateway restart.
3. There is no channels.discord block. The gateway does not start Discord from DISCORD_BOT_TOKEN alone.
4. The service can't see the token. See the .env note in Step 4.
5. Discord rejected the token. That's close code 4004, "Authentication failed." Reset the token, update the variable and restart.
6. You're on an old build. My first npm install -g openclaw@latest gave me an older release than the current one, and openclaw update fixed it. Compare openclaw --version with npm view openclaw version. One cause to check: npm freshness filters such as min-release-age. OpenClaw's install docs say the hosted installer clears them for the OpenClaw install, while a manual npm install follows your own npm policy.

On 2026.9.1, the openclaw doctor --fix step needed the gateway stopped first: stop it with openclaw gateway stop, run the fix, then openclaw gateway start. Current docs say an explicit repair now stops and restarts a managed service by itself. If you run the gateway by hand or under another supervisor, stop it yourself first.

Online, but silent in your server

• The server isn't allowlisted. This was my case. Add it under channels.discord.guilds as in Step 6.
• The channel isn't in the server's channels map. Add it, or add "*".
• You didn't @mention it. Server messages are mention-gated by default, and requireMention only works under a server or channel entry.
• You aren't in users or roles for that server or channel.
• Message Content is off. Server messages then arrive without text. Turn it on and restart the gateway.
• The bot can't see the channel. Check View Channels and Read Message History there. openclaw channels capabilities --channel discord --target channel:<id> audits permissions for one channel. Permission checks only work with numeric channel IDs.
• It types but never posts. The room may be set to messages.groupChat.visibleReplies: "message_tool", where the agent only posts when it calls its message tool.

"You are not authorized to use this command"

OpenClaw registers slash commands for everyone in the server, but checks each use against the same policies as messages. The common cases in the plugin's code:

• in a DM, dmPolicy is allowlist and you aren't in allowFrom (in pairing mode you get a pairing code instead);
• in a server, the server or channel has a users or roles list and you aren't on it;
• commands.allowFrom is set and you aren't in it. When it is set, it replaces the server's users and roles lists for commands.

OpenClaw's docs note that commands "may still be visible in the Discord UI for unauthorized users," so other members seeing the commands and getting this reply is expected. You can hide them per role and channel under Server Settings > Integrations.

"fetch failed"

The log line Failed to get gateway information from Discord: fetch failed means Node couldn't complete an HTTPS request to discord.com: no network at startup, DNS, a firewall or VPN, or a proxy.

Test from the same machine. This endpoint needs no token:

curl -s https://discord.com/api/v10/gateway

It should print {"url":"wss://gateway.discord.gg"}. If it doesn't, fix the network first. Behind a proxy, set channels.discord.proxy (for example "http://proxy.example:8080"). OpenClaw's docs say the Discord WebSocket doesn't pick up proxy environment variables, so the setting has to be explicit.

Several bugs in this area were fixed during 2026, including the metadata request ignoring the account proxy (#80227) and the plugin never retrying after a network outage at startup (#51370). Update before you debug further. If the gateway started while the network was down, restart it once the network is back.

Close code 4014 (disallowed intents)

The log says gateway closed with code 4014 (missing privileged gateway intents). The gateway asked for an intent that is switched off in the Developer Portal. Turn on Message Content, plus Server Members if you use role allowlists or names, save, and restart the gateway: a running connection doesn't pick up the change.

Or set intents.messageContent: false and run mention-only as in Step 2. The general 4014 section explains the error for any bot.

Rate limits and restart loops

• Logins. Discord allows 1,000 identifies per 24 hours. At the limit it ends all sessions, resets the token and emails the owner. A gateway restarting every minute gets there in under a day.
• Invalid requests. 10,000 responses with status 401, 403 or 429 in 10 minutes gets your IP temporarily blocked from the API. API requests made with a rejected token come back 401 and count toward it.
• OpenClaw's crash-loop breaker. Three unclean boots within 5 minutes keep channels from auto-starting, with channel autostart suppressed by crash-loop breaker in the logs. Fix the cause, then start Discord by hand with openclaw gateway call channels.start --params '{"channel":"discord"}', or leave the gateway running until the window passes.
• Startup lookups. If the host is blocked or rate limited on the startup application lookup, set channels.discord.applicationId to the Application ID from General Information and OpenClaw skips that call.
• Bot loops. If you let it read other bots with allowBots, prefer "mentions". OpenClaw's bot loop protection also mutes a pair of bots that keep answering each other.

The Discord rate limits section has the general picture.

When a personal agent is the wrong tool

OpenClaw is built to be your assistant, reachable from your chats. If you're setting up the Hermes Agent instead, the Discord side is the same; its access rules live in environment variables.

What neither is built for is answering a community's questions. Once hundreds of members can talk to an agent with tools, every one of them can try to steer it.

For that job I build Discord AI support bots that answer only from your docs, link their sources, hand off to staff when unsure, and run hosted on your own bot application with your own model key. Most land in the Community tier from $1,490, with hosting on Care at $49 a month. If that is what you were really after, send me a short brief.