Hermes Agent Discord Bot Setup: Intents, Roles, and Fixes (2026)

How Hermes behaves on Discord

Hermes DMs respond without a mention. In server channels, the default is to respond only when someone mentions the bot. Each DM gets its own session, each thread gets its own namespace, and each user in a shared channel gets a separate session by default.

This is a stateful agent gateway, not a stateless webhook. Every message passes through authorization, mention checks, session lookup, transcript loading, normal tool execution, and response delivery.

Step 1: Create the Discord bot

In the Discord Developer Portal, create an application and add a Bot. Copy the bot token and keep it outside source control. Rotate it immediately if it appears in a screenshot, shell history shared with others, or a committed file.

Step 2: Enable the required intents

Under Bot → Privileged Gateway Intents, enable Message Content Intent. Hermes needs it to read message text.

Enable Server Members Intent if you authorize by role or use usernames rather than numeric IDs. Presence Intent is not required.

When these intents are missing, Discord can reject the connection with PrivilegedIntentsRequired, or the bot can appear present without processing messages.

Step 3: Configure Hermes and access control

Run:

hermes gateway setup

Select Discord and provide the token plus an access policy. The manual environment values look like:

DISCORD_BOT_TOKEN=your-discord-bot-token
DISCORD_ALLOWED_USERS=111222333444555666

For a team that manages membership through Discord roles:

DISCORD_ALLOWED_ROLES=987654321098765432

Use numeric role IDs, not names. User and role allowlists are combined with OR logic, so either can authorize a person.

Hermes intentionally fails closed. A connected bot with no user, role, or channel access policy can remain online while denying inbound messages. Do not “fix” this with DISCORD_ALLOW_ALL_USERS=true unless the agent has no sensitive tools and the open access is deliberate.

Step 4: Invite the bot and start the gateway

Invite the application to the intended server. Its role needs View Channel, Read Message History, Send Messages, and any attachment permissions your workflow requires.

Start or restart Hermes:

hermes gateway
hermes gateway restart

Mention the bot in an allowed server channel for the first test. Use a DM for a simpler authorization test.

Step 5: Preserve per-user sessions

The safe shared-channel default is:

group_sessions_per_user: true

Alice and Bob can speak in the same visible channel without inheriting each other’s transcripts. Set it to false only when the room is intentionally one shared conversation and everyone understands that messages, interruptions, and context are collective.

Step 6: Restrict channels and mentions

Use DISCORD_ALLOWED_CHANNELS when the bot belongs in only a few rooms. Hermes also blocks @everyone, @here, and role mentions by default while allowing individual-user and reply mentions. Keep those defaults. An agent can reproduce mention text from a source or prompt without understanding the notification blast it would create.

Free-response channels can remove the mention requirement, but they also make unrelated conversation eligible for model calls. Use them for a dedicated bot room, not a busy general channel.

Troubleshooting an online but silent bot

Check these in order:

1. Enable Message Content Intent in the Developer Portal.
2. Set an allowed user, allowed role, or deliberate channel policy.
3. Confirm View Channel and Read Message History permissions.
4. Update DISCORD_BOT_TOKEN if it was reset.
5. Inspect ~/.hermes/logs/gateway.log for the exact denied policy or missing intent.
6. Run hermes gateway restart after configuration changes.

A 403 Forbidden usually means the bot role lacks a Discord permission. PrivilegedIntentsRequired is a Developer Portal setting. “User not allowed” is a Hermes authorization policy. Treating all three as network failures wastes time.

Admin and user command tiers

For shared deployments, Hermes can separate allowed admins from ordinary users and limit which slash commands non-admins may call. This matters because an authorized user can otherwise reach powerful agent capabilities, including tools and system access.

Use /whoami inside Discord to inspect the active scope, your tier, and the commands available to you. Keep restart, approval, and broad tool-control commands with admins.

Official references

• Hermes Discord setup
• Hermes messaging gateway
• Hermes security guide

Related guides

• Hermes Telegram bot setup
• Hermes Bot Mode
• Hermes Agent mastery tips
• Agent Docker sandbox security