To set up Hermes Agent as a Discord bot, create an application in the Discord Developer Portal, turn on Message Content Intent, invite the bot, give Hermes the token and an allowlist, then start the gateway. The four steps below take 15 to 30 minutes.
Checked against the Hermes docs for v0.23.1 (released 9 November 2026).
Two failures cover most broken setups. If the bot never comes online, Message Content Intent is usually off: Hermes always asks Discord for message content, and Discord refuses the connection when the toggle is disabled. If the bot is online but ignores everyone, the allowlist is usually empty, because Hermes denies every Discord user until you name who may use it. Both are fixed below.
Create the Discord application and bot
Open the Discord Developer Portal. Click "New Application." Name it something clear ("Hermes Agent" works fine). This creates the application shell.
Go to the Bot tab in the sidebar. Discord auto-creates a bot user for your application. This is where the most important settings live.
Enable privileged gateway intents
Scroll down to "Privileged Gateway Intents." Hermes needs two of the three toggles; the third is optional:
Message Content Intent. Required, and the critical one. Hermes always requests it, so with the toggle off Discord rejects the bot's connection and the bot stays offline. The gateway log then says "Discord rejected the connection because privileged Gateway Intents are not enabled". Enable it. Save.
Server Members Intent. The Hermes setup guide lists it as required. Hermes requests it when your allowlist uses usernames instead of numeric IDs, or when you set DISCORD_ALLOWED_ROLES to authorize users by role.
Presence Intent. Optional.
If your bot is in fewer than 100 servers, you can toggle these freely. Above 100 servers, Discord requires a verification application. For personal or team use, this isn't a concern.
Copy the bot token
Still on the Bot page, click "Reset Token" under the Token section. If you have 2FA enabled, enter your code. Copy the token immediately. Discord only shows it once. Store it in a password manager, not in a commit, not in a screenshot, not in a Slack message.
Invite the bot to your server
Go to the Installation tab (or build the OAuth2 URL manually). Set the scopes to bot and applications.commands. For permissions, select:
View Channels, Send Messages, Read Message History, Send Messages in Threads, Embed Links, Attach Files, Add Reactions.
Start with these minimal permissions. You can expand later. Use the generated install link to invite the bot to your server. It will appear in the member list as offline until you start the Hermes gateway.
Start with one private test channel. Not your entire server. Verify the bot responds there before opening it up to community channels or team-wide use.
Configure Hermes for Discord
The quick way: hermes gateway setup (v0.21.6+)
Since v0.21.6, the setup wizard does most of this for you:
hermes gateway setup
Pick Discord and paste the token. The wizard validates the token, flags any missing intents, prints the invite link for your bot, and allowlists you as the owner. If you're on an older version, run hermes update first, or configure it by hand as below. Either way, it helps to know what the wizard writes.
The manual way: .env
Hermes stores Discord credentials in ~/.hermes/.env and behavior settings in ~/.hermes/config.yaml. Environment variables in .env always take precedence over config.yaml values.
# ~/.hermes/.env
DISCORD_BOT_TOKEN=your-bot-token-here
DISCORD_ALLOWED_USERS=284102345871466496,583102345871466497
DISCORD_HOME_CHANNEL=1234567890123456789
DISCORD_ALLOWED_USERS (user IDs or usernames) is effectively required. With no allowlist set (DISCORD_ALLOWED_USERS, DISCORD_ALLOWED_ROLES or DISCORD_ALLOWED_CHANNELS), the gateway denies everyone. This is a security-first default, not a bug. You can open the bot to everyone with DISCORD_ALLOW_ALL_USERS=true, but don't do that on a server with strangers in it.
To find your Discord User ID: open Discord, go to Settings, then Advanced, toggle Developer Mode to ON. Right-click your username anywhere and select "Copy User ID."
To find Channel IDs: with Developer Mode on, right-click any channel name and select "Copy Channel ID." If you would rather not hand-manage IDs and tokens at all, you can deploy an AI agent with Discord connected through OAuth instead.
If you're managing a team, DISCORD_ALLOWED_ROLES is more practical than listing every user ID:
DISCORD_ALLOWED_ROLES=1098765432109876543
Any member with that role is authorized. This uses OR semantics with DISCORD_ALLOWED_USERS, so you can combine both.
Start the gateway and test
Before starting the Discord gateway, verify Hermes works in the CLI using the same profile:
hermes chat --oneshot -q "reply with discord provider ok"
If this fails with API key, credits, or rate limit errors, fix those first. Discord isn't the broken part yet.
Then start the gateway:
hermes gateway run
The bot should come online in Discord within seconds. Send it a DM or @mention it in your test channel. If it responds, the setup is working. Install it as a persistent service:
hermes gateway install
Check status with hermes gateway status. View logs with journalctl --user -u hermes-gateway -f on Linux.
If you've already set up Hermes with Slack and want to compare the Discord approach, the core difference is that Discord uses a standard bot token instead of Slack's Socket Mode. The gateway abstracts both, so your agent's behavior and memory are identical across platforms.
Per-channel behavior (this is where it gets useful)
Discord has more permission surfaces than most messaging platforms: server roles, channel overrides, threads, forums, slash commands. Hermes exposes controls for all of them.
Free-response channels let the bot reply without an @mention. Perfect for a dedicated "#ask-hermes" channel:
# ~/.hermes/.env
DISCORD_FREE_RESPONSE_CHANNELS=1234567890,9876543210
Ignored channels prevent the bot from responding at all, even when mentioned:
DISCORD_IGNORED_CHANNELS=1111111111,2222222222
Outside free-response channels, DISCORD_REQUIRE_MENTION (default true) means the bot only answers when @mentioned. DISCORD_ALLOWED_CHANNELS does the opposite of the ignore list: the bot only works in the channels you name.
Session isolation (enabled by default) means that when Alice and Bob both talk to Hermes in #research, they get separate conversation histories. Alice's context doesn't leak into Bob's session, and vice versa. This is a top-level setting in config.yaml that applies to every gateway platform, not just Discord:
group_sessions_per_user: true # default: per-user sessions
Set to false if you want the entire channel to share one conversation (useful for collaborative research channels where context should accumulate).
Slash commands register automatically. Any skill installed via hermes skills install appears as a native Discord slash command on the next gateway restart. The 100-command limit per bot applies. If you run multiple gateways against the same application (staging + production), set gateway.platforms.discord.extra.slash_commands: false in config.yaml on the non-primary instance to avoid registration conflicts.
If all this per-channel YAML configuration feels like a lot of overhead for what should be a simple Discord bot, it is. That's the tradeoff with self-hosted frameworks. BetterClaw's Discord integration handles channel routing, permissions, and session management through a visual builder. One click to connect, per-channel behavior configured with dropdowns instead of YAML. Free plan available, $49/month for Pro. Telegram, Discord and Slack bots are built in.
The silent failures (and their fixes)
Bot online but never responds
Check the allowlist first. With no DISCORD_ALLOWED_USERS, DISCORD_ALLOWED_ROLES or DISCORD_ALLOWED_CHANNELS set, the bot connects normally but Hermes denies every incoming message. Add your user ID to DISCORD_ALLOWED_USERS in ~/.hermes/.env and run hermes gateway restart. In server channels, also remember that DISCORD_REQUIRE_MENTION is on by default, so the bot only answers an @mention outside free-response channels.
Bot responds in DMs but not in channels
Channel-level permissions override server-level permissions. Right-click the channel, go to "Edit Channel," then "Permissions." Check that the bot's role has View Channel, Send Messages, and Read Message History set to the green checkmark, not grey neutral. Grey means "inherit from server," which usually works, but explicit green is safer.
If nothing else works, the nuclear option: delete the channel, recreate it with the same name. The new channel inherits fresh default permissions cleanly.
Bot creates threads for every reply (and you don't want that)
Hermes defaults to auto-threading in server channels (DISCORD_AUTO_THREAD, default true). Set it to false in .env to turn threading off everywhere, or override per channel:
discord:
no_thread_channels:
- "CHANNEL_ID_HERE"
Gateway runs but bot shows offline
The gateway process is alive but the Discord WebSocket connection failed. Check that Message Content Intent is on (this is the most common cause) and that your bot token is valid (tokens can be invalidated if you reset them in the Developer Portal without updating .env). Re-running hermes gateway setup on v0.21.6 or later is the fastest check, because it validates the token and flags missing intents. Run hermes gateway status and look for connection errors in the output.
Two bots caught in an infinite reply loop
DISCORD_ALLOW_BOTS defaults to none for this exact reason. Discord auto-mentions the replied-to author on every reply, so two bots that answer every mention can trigger each other indefinitely. If you do want bots to see each other (next section), keep DISCORD_BOTS_REQUIRE_INLINE_MENTION at its default of true, which, as the name says, requires an @mention written into the message itself.
For problems outside Discord (gateway crashes, update regressions, model errors), see our roundup of Hermes Agent bugs and fixes.
Running several Hermes bots in one Discord server
Since v0.21.0, Hermes has had Bot Mode, and it's easy to assume that's how you get a team of bots into Discord. It isn't. Bot Mode is a desktop app feature: a Bots tab next to Sessions, where each bot is a Hermes profile (stored at ~/.hermes/profiles/<name>/) created with "New Agent". The group chats in Bot Mode are Hermes rooms, not Discord channels (since v0.23.1 they can also run on a gateway without Desktop), and bots talk to each other there with the message_agent tool. hermes peer connects bots across machines. The Hermes docs treat these Bot Mode bots and messaging bots (Discord or Telegram accounts) as different things.
To get several named Hermes bots into one Discord server, you combine the two ideas: one profile per bot, and one Discord bot per profile.
- Create one Discord application per bot in the Developer Portal, each with its own name, avatar and token, and the same intents as above. Discord shows each as a separate member.
- Create one Hermes profile per bot. In the desktop app, that's New Agent in the Bots tab. Each profile has its own memory, skills and credentials. You can open any of them from the terminal with
hermes -p <bot> chat. - Give each profile its own token. Run the Discord setup with the profile flag, for example
hermes -p research gateway setup, and paste that bot's token. - Let the bots see each other. Set
DISCORD_ALLOW_BOTS=mentionsin each profile (allalso exists but invites loops). KeepDISCORD_BOTS_REQUIRE_INLINE_MENTIONat its defaulttrue. If you use threads,DISCORD_THREAD_REQUIRE_MENTIONmakes bots wait for a mention inside threads too. - Run one gateway per profile, for example
hermes -p research gateway runandhermes -p coder gateway run.
Now a person can write "@research summarise this thread and pass it to @coder" in a channel, and each bot answers as itself. Give each bot a narrow job and its own allowed channels, or you'll have two bots answering the same question.
Running the bot in production
Setting up Hermes as a Discord bot takes about 15 to 30 minutes if you follow this guide. The bot will work. The slash commands will register. Per-channel behavior is flexible.
But running it in production means maintaining a server, keeping the gateway process alive, rotating tokens, and keeping up with security updates, as with any self-hosted agent framework. For community Discord servers, personal workspaces, and dev teams comfortable with ops, Hermes is a solid choice. For teams that want the Discord bot without the infrastructure, there are managed alternatives.
If you've read through this guide and thought I just want the bot without all the ops, that's why BetterClaw exists. Free plan with 1 agent and 100 credits a month. $49/month for Pro, with Telegram, Slack, Discord and Gmail built in, plus webhooks and 500+ connectors. Unlimited skills. 28+ model providers via BYOK. Your first agent deploys in 60 seconds, and the Discord connection is one click.
Discord vs Telegram for Hermes
Both run through the same Hermes gateway, so your agent's memory and skills are identical on either. Telegram is faster to set up (one BotFather token, no developer portal or intents) and suits a personal assistant you reach from your phone; see the Hermes Telegram setup guide. Discord takes longer but suits a team: multiple people in one channel, roles for access, threads for separate tasks, and slash commands for your skills. If your team lives in Slack instead, see the Hermes Agent Slack setup guide. Either way, the gateway needs to run continuously, which is a hosting problem, not a chat app problem.
If your company runs on Microsoft 365 instead, the same gateway covers that too: see the Hermes Agent Microsoft Teams setup guide. If you're going to self-host, do it deliberately. Private test channel first. Minimal permissions. Explicit user or role allowlists. Prove the path works before you invite the bot into your community.
And if the bot goes quiet, check two things in order: offline means Message Content Intent, online but silent means the allowlist.
Frequently Asked Questions
How do I set up Hermes Agent on Discord?
Create an application in the Discord Developer Portal, copy the bot token from the Bot tab, and turn on Message Content Intent and Server Members Intent. Invite the bot with View Channels, Send Messages and Read Message History. Then run hermes gateway setup and pick Discord, or set DISCORD_BOT_TOKEN and DISCORD_ALLOWED_USERS in ~/.hermes/.env, and start it with hermes gateway run.
Which Discord intents does Hermes need?
Message Content Intent is required. Hermes always requests it, and Discord refuses the bot's connection when it is off, so the bot never comes online. The Hermes setup guide also lists Server Members Intent as required, and Hermes requests it when your allowlist uses usernames or roles. Presence Intent is optional. Under 100 servers you can switch these on freely in the Bot tab.
Why does my Hermes Discord bot not respond?
If the bot shows offline, Message Content Intent is usually off or the token is wrong, so check the Developer Portal and DISCORD_BOT_TOKEN. If it is online but silent, the allowlist is usually empty: Hermes denies every user until you set DISCORD_ALLOWED_USERS, DISCORD_ALLOWED_ROLES or DISCORD_ALLOWED_CHANNELS. Also check channel permissions and that you @mention the bot outside free-response channels.
Can I run several Hermes bots in one server?
Yes. Create one Discord application and token per bot, and one Hermes profile per bot, then run one gateway per profile, for example hermes -p research gateway run. To let the bots see each other, set DISCORD_ALLOW_BOTS=mentions and keep DISCORD_BOTS_REQUIRE_INLINE_MENTION at its default of true, which stops two bots from replying to each other forever.
How much does it cost to run Hermes Agent as a Discord bot?
Hermes is free and open source under the MIT license. You pay for a server to run the gateway, usually a small VPS, plus your model usage, which depends on the provider and how busy the bot is. BetterClaw is a separate no-code AI agent platform, not a Hermes host, with Discord, Slack and Telegram built in. There is a free plan, and Pro is $49/month.
Is the Hermes Discord bot secure for community servers?
By default, yes. Hermes denies every Discord user until you set DISCORD_ALLOWED_USERS or DISCORD_ALLOWED_ROLES, ignores other bots (DISCORD_ALLOW_BOTS=none), and cannot ping @everyone or roles. For a community server, keep mention-only replies, limit the bot to chosen channels with DISCORD_ALLOWED_CHANNELS, grant minimal permissions, and never use DISCORD_ALLOW_ALL_USERS=true where strangers can reach the bot.
How does the Hermes Discord bot compare to BetterClaw's Discord integration?
Hermes gives you full control: per-channel config, session settings, slash commands for skills and voice channel support. In return you run a server, keep the gateway alive and rotate tokens yourself. BetterClaw is a separate no-code AI agent platform whose Discord integration connects through a visual builder with no server or gateway to maintain. Hermes is free but self-hosted, and BetterClaw has a free plan.
