Hermes Agent Discord 配置与会话隔离完全指南

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

Hermes Agent 作为功能完备的 AI 助手平台，支持通过 Discord Bot 形式接入服务器。本文基于实际部署经验，系统梳理从 Bot 创建到会话隔离配置的完整流程，并解答部署过程中可能遇到的典型问题。

一、Discord Bot 创建与基础配置

1. 创建 Discord Application

访问 Discord Developer Portal，点击 New Application，填写应用名称后进入管理界面。在 General Information 页面记录 Application ID，后续生成邀请链接时需要用到。

2. 配置 Bot 与关键权限

进入左侧 Bot 标签页，此处需要完成三项关键设置：

Bot 身份设置

Public Bot：建议保持 ON，以便使用 Discord 提供的标准邀请链接
可在此页面上传 Bot 头像和横幅

Token 获取

点击 Reset Token 生成 Bot Token
该 Token 仅显示一次，务必妥善保存，后续写入 Hermes 的 .env 文件

Privileged Gateway Intents（关键步骤）

页面下方找到 Privileged Gateway Intents 区域，必须开启以下两项：

Intent	作用	是否必须
Server Members Intent	访问成员列表、解析用户名	是
Message Content Intent	读取消息文本内容	是

注意：Message Content Intent 是 Bot 能够正常响应的前提。若未开启，Bot 虽能在线并接收事件，但无法获取消息文字内容，表现为"在线但不回复"。

3. 生成邀请链接并授权

方式一：Installation 标签页（推荐）

左侧进入 Installation → 开启 Guild Install
Install Link 选择 Discord Provided Link
Scopes 勾选 bot 和 applications.commands
Permissions 选择：View Channels、Send Messages、Read Message History、Embed Links、Attach Files

方式二：手动构造 URL

将 YOUR_APP_ID 替换为 Application ID，访问该链接选择服务器完成授权。

二、Hermes 环境配置

在 ~/.hermes/.env 文件中添加：

获取 User ID 的方式：Discord 设置 → Advanced → 开启 Developer Mode，右键点击自己的用户名选择 Copy User ID。

启动 Gateway：

可选环境变量：

变量	默认值	说明
DISCORD_REQUIRE_MENTION	true	频道中是否需要 @Bot 才响应
DISCORD_AUTO_THREAD	true	@mention 时自动创建 Thread（推荐保持开启）
DISCORD_FREE_RESPONSE_CHANNELS	-	无需 @mention 即可响应的频道 ID
DISCORD_IGNORED_CHANNELS	-	Bot 完全不理会的频道黑名单

三、会话隔离机制详解

Hermes 通过 session_key 区分不同会话，Discord 场景下的默认行为如下：

1. DM（私聊）— 天然隔离

每个 DM 对话拥有独立的 session_key，无需 @mention，所有消息自动归入同一会话。

2. 服务器频道 — 默认按用户隔离

config.yaml 中的全局设置控制此行为：

当该值为 true 时：

Alice 在 #research 频道 @Bot，Bot 为她维护独立会话
Bob 在同一频道 @Bot，Bot 为他维护完全不同的独立会话
两人互不共享上下文、Token 消耗、运行状态

若设为 false，整个频道共享一个会话。

3. Thread（子区/线程）— 核心隔离手段

Discord Thread 是 Hermes 实现会话隔离的关键机制：

Thread 与父频道隔离

Thread 的 session_key 包含 thread_id，因此 Thread 内对话与父频道完全隔离

Thread 内默认共享

thread_sessions_per_user 默认为 false，同一 Thread 内的所有用户共享一个会话（适合协作场景）
若需 Thread 内也按用户隔离，设置 thread_sessions_per_user: true

自动创建 Thread（强烈推荐）

DISCORD_AUTO_THREAD 默认为 true，其工作机制：

效果：

每次 @mention = 一个新的 Thread = 一个全新的隔离会话
Thread 内后续回复无需再次 @mention
不同任务天然处于不同会话，完全避免上下文污染

四、问题排查：频道 @mention 无响应

若 DM 可正常工作但频道 @mention 无响应，按以下顺序排查：

1. 检查 Message Content Intent（最常见原因）

进入 Discord Developer Portal → 你的 Application → Bot → Privileged Gateway Intents，确认 Message Content Intent 已开启，点击 Save Changes。

2. 检查 Bot 频道权限

在 Discord 中，右键频道 → Edit Channel → Permissions，确认 Bot 角色拥有：

View Channels
Read Message History
Send Messages

3. 检查环境配置

4. 终极解决方案：重新授权

若确认以上设置均正确但仍无法响应，尝试：

将 Bot 踢出服务器
使用新的邀请链接重新授权（确保权限整数包含所需权限）
重新启动 hermes gateway

实际部署经验表明，重新授权往往能解决问题，可能是 Discord 端权限缓存未刷新导致。

五、最佳实践配置

推荐配置实现最大化隔离：

~/.hermes/.env：

~/.hermes/config.yaml：

此配置下的交互体验：

在 #general @Bot “帮我写 Python 脚本” → Bot 自动创建 Thread A，任务在隔离环境运行
再次 @Bot “分析这份文档” → Bot 创建 Thread B，又是一个全新会话
同事也在 #general @Bot → 获得独立的 Thread C，互不干扰

六、会话管理命令

在任意对话中可使用以下命令：

命令	作用
/reset	重置当前会话，开启全新空会话
/title 任务名称	为当前会话命名，便于后续查找
/sethome	将当前频道设为 Home Channel，用于接收定时任务输出

总结

隔离层级	默认行为	控制方式
DM vs 频道	完全隔离	天然
不同用户同频道	按用户隔离	group_sessions_per_user: true
不同 Thread	完全隔离	天然（thread_id 参与 session key）
同 Thread 不同用户	共享会话	thread_sessions_per_user: true 可开启隔离
同用户同频道不同任务	共享会话	依靠 DISCORD_AUTO_THREAD=true 自动开 Thread

保持 DISCORD_AUTO_THREAD=true（默认开启）是最简单有效的防污染手段，让每次 @mention 都落入全新 Thread 会话中，从根本上避免同一频道内多任务互相干扰。

Discord on 火炬树