Hermes Agent on Discord

Defaults from the official Discord docs — most “the bot is ignoring me” reports are one of these rows:

• A working Hermes install with a model connected — confirm a plain chat works first (setup guide).
• A Discord account and a server where you have Manage Server (needed to invite a bot).
• Discord Developer Mode on (User Settings → Advanced) so you can copy numeric IDs.
• A machine that stays on while you want the bot to answer — your laptop works for testing; see the gateway section.

1. In the Discord Developer Portal, click New Application and name it. Note the Application ID.
2. Open Bot. Leave Require OAuth2 Code Grant off. Public Bot on lets you use Discord's generated invite link; off means you must build the invite URL by hand (Step 2).
3. Under Privileged Gateway Intents, turn on the intents below and click Save Changes.
4. Under Token, click Reset Token and copy it — Discord shows it once. Anyone with it controls the bot.

Use the Installation tab (Guild Install, scopes bot + applications.commands) or build the URL yourself. The applications.commands scope is what lets Hermes register its slash commands.

https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912

Hermes auto-creates threads and adds 👀/✅/❌ reactions by default, so the recommended set matches the default behavior. The bot shows as offline in the member list until the gateway starts.

Run the guided setup and choose Discord, or write the values yourself. The web dashboard's Channels page has the same per-platform form. Unlike Telegram, the official docs describe no QR shortcut for Discord — you create the bot in the Developer Portal.

$hermes gateway setup      # choose Discord, paste the token and your user ID
$
# …or add to ~/.hermes/.env
$DISCORD_BOT_TOKEN=your-bot-token
$DISCORD_ALLOWED_USERS=284102345871466496
$
$hermes gateway            # start in the foreground to test

Send the bot a DM, then @mention it in a channel it can see. The 👀 reaction means the message was accepted and is being processed. Once that works, install the gateway as a service (hermes gateway install) so it survives logout and reboots. Settings in .env override the matching keys under discord: in ~/.hermes/config.yaml.

With Developer Mode on, right-click a user, role, channel, or server and choose Copy ID. Every Hermes setting takes the numeric ID, never a name:

Hermes fails closed. Without DISCORD_ALLOWED_USERS, DISCORD_ALLOWED_ROLES, DISCORD_ALLOWED_CHANNELS, or an explicit allow-all flag, the bot connects and looks online but denies every message, and ~/.hermes/logs/gateway.log says No Discord access policy configured. The alternative to an allowlist is DM pairing: an unknown user who DMs the bot gets a one-time code, which you approve with hermes pairing approve discord <code> (codes expire after an hour). DISCORD_ALLOW_ALL_USERS=true opens the bot to everyone who can reach it — authorized users get the agent's full toolset, including the terminal.

For a message in a server channel, the rules apply in this order:

1. Ignored channels win. A channel (or a thread under it) in DISCORD_IGNORED_CHANNELS is never answered.
2. Allowed channels restrict. If DISCORD_ALLOWED_CHANNELS is set, other channels are ignored (DMs still work if the user is allowed).
3. Mention required by default. DISCORD_REQUIRE_MENTION=true; set it to false to answer everything, or list individual free-response channels instead.
4. Mentions of other people. A message that @mentions someone else but not the bot is skipped (DISCORD_IGNORE_NO_MENTION=true).

Because unmentioned messages aren't processed, Hermes backfills context when you do mention it: it reads the channel back to its own last reply (up to 50 messages) and adds that to your message. It skips this in DMs and free-response channels, where nothing was missed. Turn it off with DISCORD_HISTORY_BACKFILL=false.

Outgoing pings are restricted by default: Hermes cannot ping @everyone, @here, or roles even if the model writes them. Individual users and reply pings still work.

• Free-response channels reply inline by default. Set discord.free_response_auto_thread: true to thread them too.
• Several bots in one thread: set discord.thread_require_mention: true, otherwise every bot already in the thread answers every message.
• Different model or persona per channel: platforms.discord.channel_overrides (model, provider, system prompt) and discord.channel_prompts; threads and forum posts fall back to their parent's entry.
• A forum created after the gateway started is picked up on the next directory refresh or gateway restart.

DMs are the simplest mode: no mention, no auto-thread, and one session per DM that continues until you send /new or /reset — gateway conversations don't reset on inactivity. The user still has to be allowlisted, hold an allowed role in a server shared with the bot, or be paired. Slash commands, voice messages, and file uploads work the same as in channels.

The Discord bot is the Hermes gateway process. It connects out to Discord over Discord's Gateway WebSocket, so no inbound port or public URL is needed — but when hermes gateway stops (laptop asleep, terminal closed, crash), the bot shows offline and nothing answers. On a remote machine, the hermes serve or dashboard backend that Desktop connects to is a separate process from the gateway — start and keep the gateway running on its own.

• Messages sent while offline are not answered by default. Opt in with discord.missed_message_backfill.enabled: true; it replays unanswered messages from listed channels (default: your free-response channels) from the last 6 hours, capped at 10 per reconnect.
• Replies interrupted by a crash are redelivered on the next start from a delivery ledger; a possibly duplicated one is labeled “Recovered reply”.
• Repeated Discord failures auto-pause the adapter (circuit breaker) and it stays paused until you run /platform resume discord.
• For always-on use, run the gateway as a service on a machine that stays on — hosting options, VPS guide.

$hermes gateway status
$hermes gateway restart
$tail -n 50 ~/.hermes/logs/gateway.log

One Hermes profile runs one gateway with one Discord bot token. To run several distinct bots, create a profile per bot, give each its own Discord application and token in that profile's .env, and start each profile's gateway. If two profiles use the same token, Hermes blocks the second gateway with an error naming the other profile. Cloning a profile never copies its Discord token or allowlists.

A Bot Mode bot in Hermes Desktop is a profile, so it can have its own Discord bot this way — but Bot Mode itself is a Desktop roster, not a Discord feature, and configuring one does not configure the other. If Hermes bots should answer each other in Discord, DISCORD_ALLOW_BOTS must be mentions or all, and a handoff needs a literal @mention; a loop guard drops bot messages in a channel after 20 in 5 minutes. Two gateways sharing one Discord application (for example staging and production) should set slash_commands: false on one of them so slash-command registration doesn't flap.

• Slash commands: built-ins such as /model, /reset, and /sethome, plus one command per installed skill, up to Discord's 100-command limit; extra skills are skipped with a log warning.
• Files in: any file type, up to 32 MiB per file by default (DISCORD_MAX_ATTACHMENT_BYTES). Small text files are read straight into the prompt.
• Voice: incoming voice messages are transcribed; /voice tts adds spoken replies; /voice join brings Hermes into a voice channel.

Open bugs affecting Discord right now

• Files and audio from Hermes fail to send (“couldn't deliver the file attachment”; text still works) — #121938, opened September 24, 2026. The code path it describes is unchanged in the v0.21.5 release; a fix PR was open, not merged, on September 26, 2026.
• Voice replies arrive but won't play — MP3 audio uploaded as a voice message (#123680).
• Role-only access: messages work, slash commands are rejected and the user is offered a pairing code (#118958). Adding the user ID to DISCORD_ALLOWED_USERS avoids it.
• Embed-only messages from other bots are invisible to replies and backfill (#45188).

Both run through the same gateway, and one gateway can serve both at once with shared memory and skills. The differences that change how you set Hermes up:

Setting up Telegram instead? See Hermes Agent Telegram setup.