Fix OpenClaw Discord Bot in Wrong Channels or Servers

Key takeaways

• OpenClaw has two allowlists for Discord: guilds (servers) and channels. If either list is non-empty, the bot only operates where listed. An empty array means "allow all."
• If your bot responds in servers where it shouldn't, the guilds array is either empty or contains IDs you didn't intend. Same logic applies to channels.
• Every time a bot is kicked and re-invited to a server, the guild ID stays the same but the pairing resets. You need to approve the new pairing request.
• OpenClaw does not support category-level allowlists. Use Discord's built-in channel permissions as a complementary layer.

Your OpenClaw Discord bot is responding in channels or servers where it should stay quiet. The fix is in two config arrays: guilds controls which servers the bot monitors, and channels controls which channels within those servers. Set them to the IDs you want and restart.

How OpenClaw Discord guild and channel allowlists work

OpenClaw checks two arrays in your Discord config before processing any message. Both live under channels.discord.accounts.default in ~/.openclaw/config/config.json.

The guilds array controls which servers (guilds) the bot responds in. If the array contains guild IDs, the bot ignores any server not listed. If the array is empty, the bot responds in every server it's been invited to.

The channels array works the same way for channels within allowed guilds. If it contains channel IDs, the bot only responds in those specific channels. If empty, it responds in every channel where it has read access.

Both filters are evaluated before pairing and requireMention checks. A message from a guild not in the allowlist never reaches the pairing system. It's dropped immediately with this log line:

drop guild (not in allowlist)

For channels:

drop channel (not in allowlist)

If you see either of these in your logs, the allowlist is blocking the message.

How to restrict your OpenClaw Discord bot to specific channels

Edit your config file at ~/.openclaw/config/config.json. Add the channel IDs to the channels array:

{
  "channels": {
    "discord": {
      "accounts": {
        "default": {
          "guilds": ["1234567890123456789"],
          "channels": ["9876543210987654321", "1111222233334444555"]
        }
      }
    }
  }
}

The bot now only responds in those two channels. Messages in all other channels are dropped silently.

Restart the gateway:

openclaw gateway restart

To add more channels later, append their IDs to the array and restart. Removing a channel ID stops the bot from responding there immediately after restart.

If you'd rather use Discord's native permissions instead of the config allowlist, go to the channels where the bot should stay quiet, edit channel permissions, find the bot's role, and deny "Send Messages." This is visible to server admins and doesn't require an OpenClaw config change. Both approaches work. The config allowlist is easier to manage across many channels. Discord permissions are more transparent to other server admins.

How to restrict your OpenClaw Discord bot to specific servers

Add guild IDs to the guilds array in config:

{
  "channels": {
    "discord": {
      "accounts": {
        "default": {
          "guilds": ["1234567890123456789", "5555666677778888999"]
        }
      }
    }
  }
}

The bot ignores all servers not in this list. Messages from other servers produce the drop guild (not in allowlist) log line.

An empty array allows all servers:

"guilds": []

This is fine for personal bots in a small number of servers. For public bots, always use an explicit allowlist. Anyone who invites your bot can use it, and your AI provider charges apply to every message processed.

If you're seeing "unknown guild" errors in your logs, it usually means the bot was kicked from a server but the guild ID is still in your config. Either remove the stale ID from the guilds array or ignore the warning. It doesn't affect the bot's operation in other servers.

What happens when your OpenClaw Discord bot is kicked and reinvited

When a bot is kicked from a Discord server and re-invited, two things stay the same and one thing resets.

Same: The guild ID doesn't change. Discord servers keep their ID permanently. Your config still points to the right server.

Same: The bot's role and permissions are re-created from the OAuth2 invite URL. If you used the same invite URL, the bot gets the same permissions it had before.

Resets: The OpenClaw pairing. Every kick-and-reinvite generates a new pairing request. Even if the guild was previously approved, you need to approve it again.

Check for the new request:

openclaw pairing pending

Approve it:

openclaw pairing approve discord 1234567890123456789

If the bot was working before the kick and isn't working after the reinvite, the pairing is almost always the reason. The guild ID is right, the permissions are right, but the pairing approval is gone.

How to find Discord channel and server IDs

You need Developer Mode enabled in Discord. Go to User Settings > Advanced > Developer Mode and toggle it on. This adds a "Copy ID" option to right-click menus throughout Discord.

Server (guild) ID: Right-click the server icon in your server list. Select "Copy Server ID." Paste it into your config's guilds array.

Channel ID: Right-click the channel name in the channel list. Select "Copy Channel ID." Paste it into your config's channels array.

User ID: Right-click a username in the member list or a message. Select "Copy User ID." This is useful for allowFrom configuration but not for channel/server allowlists.

All Discord IDs are large numbers like 1234567890123456789. They need to be quoted as strings in JSON:

"guilds": ["1234567890123456789"]

Without quotes, JSON parses them as numbers and may lose precision. Always quote Discord IDs in your OpenClaw config.

FAQ

I get "unknown guild" errors in the OpenClaw Discord logs. What does that mean?

Your config references a guild ID for a server the bot is no longer in. This happens when the bot was kicked or the server was deleted, but the ID is still in your guilds array. The error is a warning, not a crash. The bot continues working in all other servers. To clean it up, remove the stale guild ID from your config and restart the gateway.

How do I run multiple Discord bots in one OpenClaw instance?

Add multiple accounts under channels.discord.accounts in your config. Each account needs its own bot token, and you can set separate guilds and channels arrays per account:

{
  "channels": {
    "discord": {
      "accounts": {
        "bot1": {
          "token": "first_bot_token",
          "guilds": ["1111111111111111111"]
        },
        "bot2": {
          "token": "second_bot_token",
          "guilds": ["2222222222222222222"]
        }
      }
    }
  }
}

Each bot connects independently. They can be in different servers or the same server with different channel restrictions.

Is it safe to set the guilds array to empty in OpenClaw Discord config?

For personal bots in a few servers, yes. An empty guilds array means "respond in every server the bot has been invited to." The risk is that anyone who invites your bot can use it, and every message processed costs you API credits with your AI provider. If your bot is public or has a discoverable invite URL, always use an explicit allowlist. For private bots where you control every invite, an empty array is fine.

Can I use Discord category permissions instead of the OpenClaw channel allowlist?

Partially. Discord categories set default permissions for channels within them. If you deny "View Channel" for the bot's role at the category level, the bot can't see any channels in that category by default. But individual channels can override category permissions. A channel with an explicit "View Channel: Allow" for the bot's role will let the bot in even if the category denies it. OpenClaw doesn't have a category-level allowlist in config. Your options are the flat channels array in OpenClaw config, or managing permissions at the Discord category and channel level. For most setups, the OpenClaw channel allowlist is simpler to manage.

Changelog

• 2026-03-07: Created (split from fix-openclaw-discord-errors)