Discord 配置

Hermes Agent 以 Discord Bot 的形式集成，让你可以通过私信或服务器频道与 AI 助手对话。Bot 接收你的消息，通过 Hermes Agent 管线处理（包括工具使用、记忆和推理），并实时响应。支持文本、语音消息、文件附件和斜杠命令。

Hermes 在 Discord 中的行为

场景	行为
私信	Hermes 回复每条消息，无需 @提及。每个私信有独立会话。
服务器频道	默认只在被 @提及时回复。未提及的消息会被忽略。
自由回复频道	通过 `DISCORD_FREE_RESPONSE_CHANNELS` 指定特定频道免提及，或全局设置 `DISCORD_REQUIRE_MENTION=false`
线程	Hermes 在同一线程中回复。提及规则仍适用，除非该线程或其父频道配置为自由回复。
多用户共享频道	默认按用户隔离会话历史。两个人在同一频道聊天不会共享一份记录。

会话模型

默认情况下：

每个私信有自己的会话
每个服务器线程有自己的会话命名空间
共享频道中每个用户有自己的会话

这由 config.yaml 控制：

group_sessions_per_user: true     # 默认 — 按用户隔离
# group_sessions_per_user: false  # 共享一个对话（协作房间用，但要注意 Token 成本和中断问题）

第一步：创建 Discord 应用

前往 Discord 开发者门户并登录
点击右上角的 New Application
输入应用名称（如 “Hermes Agent”），接受开发者服务条款
点击 Create

记下 Application ID — 后续构建邀请链接需要用到。

第二步：创建 Bot

在左侧边栏点击 Bot
Discord 会自动为你的应用创建 Bot 用户
在 Authorization Flow 下：
- 将 Public Bot 设为 ON — 这是使用 Discord 提供的邀请链接所必需的
- 保持 Require OAuth2 Code Grant 为 OFF

第三步：启用特权网关意图

这是整个设置中最关键的一步。 如果没有正确的意图，Bot 能连接到 Discord 但无法读取消息内容。

在 Bot 页面，向下滚动到 Privileged Gateway Intents，你会看到三个开关：

意图	用途	是否必需？
Presence Intent	查看用户在线/离线状态	可选
Server Members Intent	访问成员列表、解析用户名	必需
Message Content Intent	读取消息文本内容	必需

启用 Server Members Intent 和 Message Content Intent。

点击底部的 Save Changes。

第四步：获取 Bot Token

Bot Token 是 Hermes Agent 用来以你的 Bot 身份登录的凭据：

在 Bot 页面的 Token 区域，点击 Reset Token
如果启用了两步验证，输入 2FA 验证码
Discord 显示新 Token — 立即复制

第五步：生成邀请链接

方式 A：使用 Installation 选项卡（推荐）

在左侧边栏点击 Installation
在 Installation Contexts 下启用 Guild Install
Install Link 选择 Discord Provided Link
在 Default Install Settings for Guild Install 下：
- Scopes：选择 bot 和 applications.commands
- Permissions：选择下方列出的权限

方式 B：手动 URL

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

将 YOUR_APP_ID 替换为第一步的 Application ID。

所需权限

最低权限：

View Channels — 查看可访问的频道
Send Messages — 回复消息
Embed Links — 格式化富文本响应
Attach Files — 发送图片、音频和文件输出
Read Message History — 维护对话上下文

推荐额外权限：

Send Messages in Threads — 在线程对话中回复
Add Reactions — 用表情回应确认消息

级别	权限整数	包含内容
最低	117760	View Channels, Send Messages, Read Message History, Attach Files
推荐	274878286912	以上全部 + Embed Links, Send Messages in Threads, Add Reactions

第六步：邀请到你的服务器

在浏览器中打开邀请链接
在 Add to Server 下拉菜单中选择你的服务器
点击 Continue，然后 Authorize
如有提示，完成验证码

第七步：查找你的 Discord 用户 ID

打开 Discord（桌面或网页版）
进入 Settings → Advanced → 开启 Developer Mode
右键点击你自己的用户名 → Copy User ID

你的用户 ID 是一串长数字，如 284102345871466496。

第八步：配置 Hermes Agent

方式 A：交互式设置（推荐）

hermes gateway setup

选择 Discord，然后粘贴 Bot Token 和用户 ID。

方式 B：手动配置

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

# 必填
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=284102345871466496

# 多个允许的用户（逗号分隔）
# DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543

然后启动网关：

hermes gateway

Bot 应该在几秒内在 Discord 上线。给它发送私信或在它可见的频道中提及它来测试。

配置参考

Discord 行为通过两个文件控制：~/.hermes/.env 用于凭据和环境级别开关，~/.hermes/config.yaml 用于结构化设置。环境变量优先级高于 config.yaml。

常用环境变量

变量	必填	默认值	说明
`DISCORD_BOT_TOKEN`	是	—	Bot Token
`DISCORD_ALLOWED_USERS`	是	—	允许交互的用户 ID，逗号分隔
`DISCORD_ALLOWED_ROLES`	否	—	允许的角色 ID，逗号分隔
`DISCORD_HOME_CHANNEL`	否	—	主动消息频道 ID
`DISCORD_REQUIRE_MENTION`	否	true	是否需要 @提及才回复
`DISCORD_FREE_RESPONSE_CHANNELS`	否	—	免提及频道 ID，逗号分隔
`DISCORD_AUTO_THREAD`	否	true	自动为 @提及创建线程
`DISCORD_REACTIONS`	否	true	处理中添加表情回应
`DISCORD_IGNORED_CHANNELS`	否	—	永不回复的频道 ID
`DISCORD_ALLOW_BOTS`	否	none	处理其他 Bot 消息的模式：none/mentions/all
`DISCORD_PROXY`	否	—	代理 URL

config.yaml 设置

discord:
  require_mention: true              # 服务器频道需要 @提及
  free_response_channels: ""          # 免提及频道
  auto_thread: true                   # 自动创建线程
  reactions: true                     # 处理中的表情回应
  ignored_channels: []                # 忽略的频道
  no_thread_channels: []              # 不创建线程的频道
  history_backfill: true              # 提及时回填近期频道消息
  history_backfill_limit: 50          # 回填消息数量上限
  allow_mentions:
    everyone: false                    # 禁止 @everyone
    roles: false                       # 禁止 @role
    users: true                        # 允许 @user
    replied_user: true                 # 回复时通知原作者

group_sessions_per_user: true         # 共享频道按用户隔离会话