The Complete Guide to Hermes Agent Discord Setup and Session Isolation

Mon, 13 Apr 2026 10:12:01 +0800

Hermes Agent, as a fully-featured AI assistant platform, supports connecting to servers as a Discord Bot. Based on hands-on deployment experience, this article systematically walks through the whole flow from bot creation to session-isolation configuration, and answers the typical problems you may hit during deployment.

1. Discord Bot creation and basic configuration

1. Create a Discord Application

Go to the Discord Developer Portal, click New Application, fill in the app name, and you’ll enter the management interface. On the General Information page, note down the Application ID; you’ll need it later to generate the invite link.

2. Configure the Bot and key permissions

Open the Bot tab on the left. Here you need to complete three key settings:

Bot identity settings

Public Bot: keep it ON so you can use Discord’s standard invite link
You can upload the bot’s avatar and banner on this page

Getting the Token

Click Reset Token to generate the Bot Token
This Token is shown only once, so save it carefully; you’ll write it into Hermes’ .env file later

Privileged Gateway Intents (key step)

At the bottom of the page, find the Privileged Gateway Intents section. You must enable both of the following:

Intent	Purpose	Required?
Server Members Intent	Access member list, resolve usernames	Yes
Message Content Intent	Read message text content	Yes

Note: Message Content Intent is a prerequisite for the bot to respond properly. If it isn’t enabled, the bot can come online and receive events but can’t read the message text—it appears “online but unresponsive.”

3. Generate the invite link and authorize

Method 1: Installation tab (recommended)

On the left, go to Installation → enable Guild Install
For Install Link, select Discord Provided Link
Under Scopes, check bot and applications.commands
Under Permissions, select: View Channels, Send Messages, Read Message History, Embed Links, Attach Files

Method 2: Build the URL manually

Replace YOUR_APP_ID with the Application ID, then visit the link and pick a server to authorize.

2. Hermes environment configuration

Add the following to the ~/.hermes/.env file:

To get your User ID: Discord Settings → Advanced → enable Developer Mode, then right-click your own username and select Copy User ID.

Start the Gateway:

Optional environment variables:

Variable	Default	Description
DISCORD_REQUIRE_MENTION	true	Whether the bot only responds when @-mentioned in a channel
DISCORD_AUTO_THREAD	true	Automatically create a Thread on @mention (recommended to keep on)
DISCORD_FREE_RESPONSE_CHANNELS	-	Channel IDs where the bot responds without an @mention
DISCORD_IGNORED_CHANNELS	-	Blacklist of channels the bot completely ignores

3. How session isolation works

Hermes distinguishes sessions with a session_key. The default behavior in the Discord scenario is as follows:

1. DM — naturally isolated

Every DM conversation has its own independent session_key, no @mention needed, and all messages automatically fall into the same session.

2. Server channels — isolated per user by default

A global setting in config.yaml controls this behavior:

When the value is true:

Alice @-mentions the bot in #research; the bot maintains a separate session for her
Bob @-mentions the bot in the same channel; the bot maintains a completely different session for him
The two share no context, token usage, or runtime state

If set to false, the whole channel shares a single session.

3. Threads — the core isolation mechanism

Discord Threads are the key mechanism Hermes uses to isolate sessions:

Threads are isolated from the parent channel

A Thread’s session_key includes the thread_id, so conversations inside a Thread are completely isolated from the parent channel

Shared by default within a Thread

thread_sessions_per_user defaults to false, so all users in the same Thread share one session (good for collaborative scenarios)
If you want per-user isolation within a Thread too, set thread_sessions_per_user: true

Auto-created Threads (strongly recommended)

DISCORD_AUTO_THREAD defaults to true. Its mechanism:

Result:

Each @mention = one new Thread = one brand-new isolated session
Subsequent replies inside the Thread don’t need another @mention
Different tasks naturally live in different sessions, completely avoiding context contamination

4. Troubleshooting: no response to @mention in a channel

If DM works fine but channel @mention gets no response, check in this order:

1. Check Message Content Intent (the most common cause)

Go to Discord Developer Portal → your Application → Bot → Privileged Gateway Intents, confirm Message Content Intent is enabled, then click Save Changes.

2. Check the bot’s channel permissions

In Discord, right-click the channel → Edit Channel → Permissions, and confirm the bot role has:

View Channels
Read Message History
Send Messages

3. Check the environment configuration

4. The ultimate fix: re-authorize

If you’ve confirmed all the above settings are correct but it still won’t respond, try:

Kick the bot from the server
Re-authorize with a new invite link (make sure the permission integer includes the required permissions)
Restart the hermes gateway

Real-world deployment experience shows that re-authorizing often fixes the problem—likely because Discord’s side permission cache hasn’t refreshed.

5. Recommended configuration

For maximum isolation, here’s the recommended configuration:

~/.hermes/.env:

~/.hermes/config.yaml:

The interaction experience under this configuration:

In #general, @Bot “help me write a Python script” → the bot automatically creates Thread A, and the task runs in an isolated environment
@Bot again “analyze this document” → the bot creates Thread B, another brand-new session
A colleague also @-mentions the bot in #general → gets their own Thread C, no interference

6. Session management commands

The following commands are available in any conversation:

Command	Effect
/reset	Reset the current session and start a fresh empty session
/title task-name	Name the current session for easier reference later
/sethome	Set the current channel as Home Channel, used to receive scheduled task output

Summary

Isolation level	Default behavior	Control method
DM vs channel	Fully isolated	Natural
Different users, same channel	Isolated per user	group_sessions_per_user: true
Different Threads	Fully isolated	Natural (thread_id is part of the session key)
Same Thread, different users	Shared session	Enable isolation with thread_sessions_per_user: true
Same user, same channel, different tasks	Shared session	Rely on DISCORD_AUTO_THREAD=true to auto-open a Thread

Keeping DISCORD_AUTO_THREAD=true (the default) is the simplest and most effective way to prevent contamination: every @mention lands in a fresh Thread session, fundamentally preventing multiple tasks in the same channel from interfering with one another.

From OpenClaw to Hermes: Automatic Role Migration with a Single Command

Wed, 08 Apr 2026 05:55:11 +0800

After running hermes claw migrate, your config files and skills have been migrated to Hermes, but the Agent’s cognition may still be stuck in the OpenClaw era. It may still call itself “Aris,” try to access the ~/.openclaw/ directory, and use tools that no longer exist.

Solution: Send a single command that lets the Agent automatically check and fix its own identity and working logic.

Roles Explained

Before continuing, we need to clarify two identities:

Identity	Framework	Description
Aris	OpenClaw	The AI assistant name in the original OpenClaw ecosystem, used in your historical configuration
Helix	Hermes	The new identity after migrating to Hermes, which the Agent needs to self-identify as

When the Agent says “I am Aris,” it is still running on its OpenClaw identity. You need it to update to “I am Helix.”

Background

Limitations of the Official Migration Command

hermes claw migrate handles the data level:

Copies configuration files to ~/.hermes/
Migrates skills to ~/.hermes/skills/openclaw-imports/
Transfers memory files

But it does not modify the contents of files. If SOUL.md says “I am Aris,” the Agent will still believe that after migration.

Typical Symptoms

After migration, if the Agent exhibits any of the following behaviors, it needs role adaptation:

Symptom	Description
Calls itself “Aris”	Identity not updated
Accesses `~/.openclaw/`	Wrong path cognition
Invokes memory_search	Using an OpenClaw-specific tool
Mentions “OpenClaw provides context”	Wrong framework cognition

The Single-Command Automation Approach

You don’t need to edit files manually. Send the following command to the Agent, and it will automatically perform all checks and fixes:

The Agent will automatically run the checks above, modify files directly, and report a summary of changes to you.

Technical Details (for reference)

If you want to know exactly what the Agent will check, here are the technical details:

Where Identity Is Declared

File	Path	Purpose
SOUL.md	~/.hermes/SOUL.md	Global identity and personality definition
MEMORY.md	~/.hermes/memories/MEMORY.md	The Agent’s personal notes (limited to 2,200 characters)
USER.md	~/.hermes/memories/USER.md	User profile (limited to 1,375 characters)

Key Differences

Dimension	OpenClaw (Aris)	Hermes (Helix)
Identity	“I am Aris”	“I am Helix”
Framework	OpenClaw	Hermes Agent (Nous Research)
Home directory	~/.openclaw/	~/.hermes/
Memory storage	.jsonl files	SQLite + FTS5
Skill lookup	memory_search	skills_list + skill_view
Memory limits	No explicit limits	2,200 / 1,375 characters

Example of Actual Changes

SOUL.md changes:

MEMORY.md changes:

Verification Results

After the Agent completes its self-check, it will output a report similar to the following:

Manual Verification (optional)

If you want to confirm the migration results manually:

References

Official migration guide: Migrate from OpenClaw
Memory system: Persistent Memory
Context files: Context Files

Compiled from actual migration experience with Hermes Agent v0.7.0.

Hermes on TorchTree