跳到主要内容

Discord 设置

Hermes Agent 可作为机器人集成到 Discord 中，让你通过私信或服务器频道与你的 AI 助手聊天。机器人接收你的消息，通过 Hermes Agent 的处理流程（包括工具使用、记忆和推理）进行处理，并实时回复。它支持文本、语音消息、文件附件和斜杠命令。

在开始设置之前，这里先介绍一下大多数人最关心的部分：Hermes 加入你的服务器后会如何表现。

Hermes 的行为方式​

场景行为
私信Hermes 会回复每一条消息。不需要 @提及。每个私信会话都是独立的。
服务器频道默认情况下，Hermes 只在你 @提及 它时才会回复。如果你在频道中发消息但没有提及它，Hermes 会忽略该消息。
自由回复频道你可以通过 DISCORD_FREE_RESPONSE_CHANNELS 将特定频道设置为无需提及，或者通过 DISCORD_REQUIRE_MENTION=false 全局禁用提及要求。
主题Hermes 会在同一主题内回复。除非该主题或其父频道被配置为自由回复频道，否则提及规则仍然适用。主题的会话历史记录与父频道隔离。
多用户共享的频道默认情况下，为了安全和清晰，Hermes 会在频道内为每个用户隔离会话历史记录。两个人在同一频道中交谈不会共享一个对话记录，除非你明确禁用此功能。
提示

如果你想创建一个普通的机器人帮助频道，让人们无需每次都标记它就能与 Hermes 交谈，请将该频道添加到 DISCORD_FREE_RESPONSE_CHANNELS 中。

Discord 网关模型​

Discord 上的 Hermes 不是一个无状态回复的 Webhook。它通过完整的消息网关运行，这意味着每条传入消息都会经过：

  1. 授权 (DISCORD_ALLOWED_USERS)
  2. 提及 / 自由回复检查
  3. 会话查找
  4. 会话记录加载
  5. 正常的 Hermes Agent 执行，包括工具、记忆和斜杠命令
  6. 将响应发送回 Discord

这一点很重要，因为在繁忙服务器中的行为取决于 Discord 的路由和 Hermes 的会话策略。

Discord 中的会话模型​

默认情况下：

  • 每个私信都有自己的会话
  • 每个服务器主题都有自己的会话命名空间
  • 共享频道中的每个用户在该频道内都有自己的会话

因此，如果 Alice 和 Bob 都在 #research 频道中与 Hermes 交谈，即使他们使用的是同一个可见的 Discord 频道，Hermes 默认也会将这些视为独立的对话。

这由 config.yaml 控制：

group_sessions_per_user: true

仅当你明确希望整个房间共享一个对话时，才将其设置为 false：

group_sessions_per_user: false

共享会话对于协作房间可能有用，但也意味着：

  • 用户共享上下文增长和令牌成本
  • 一个人冗长且大量使用工具的任务可能会使其他人的上下文膨胀
  • 一个人正在运行的任务可能会中断另一个人在同一房间内的后续操作

中断与并发​

Hermes 通过会话键来跟踪正在运行的 Agent。

使用默认的 group_sessions_per_user: true：

  • Alice 中断她自己正在运行的请求只会影响她在该频道中的会话
  • Bob 可以在同一频道中继续交谈，而不会继承 Alice 的历史记录或中断 Alice 的运行

使用 group_sessions_per_user: false：

  • 整个房间共享该频道/主题的一个运行中 Agent 槽位
  • 来自不同用户的后续消息可能会相互中断或排队

本指南将引导你完成完整的设置过程——从在 Discord 开发者门户创建机器人到发送第一条消息。

步骤 1：创建 Discord 应用​

  1. 前往 Discord 开发者门户 并使用你的 Discord 账户登录。
  2. 点击右上角的 New Application。
  3. 为你的应用输入一个名称（例如 "Hermes Agent"）并接受开发者服务条款。
  4. 点击 Create。

你将进入 General Information 页面。记下 Application ID —— 稍后构建邀请链接时会用到它。

步骤 2：创建机器人​

  1. 在左侧边栏中，点击 Bot。
  2. Discord 会自动为你的应用创建一个机器人用户。你将看到机器人的用户名，你可以自定义它。
  3. 在 Authorization Flow 下：
    • 将 Public Bot 设置为 ON —— 这是使用 Discord 提供的邀请链接（推荐）所必需的。这允许 Installation 选项卡生成默认的授权 URL。
    • 将 Require OAuth2 Code Grant 保持为 OFF。
提示

你可以在此页面为你的机器人设置自定义头像和横幅。这就是用户在 Discord 中看到的样子。

私有机器人替代方案

如果你希望保持机器人私有（Public Bot = OFF），你必须在步骤 5 中使用 Manual URL 方法，而不是 Installation 选项卡。Discord 提供的链接要求启用 Public Bot。

步骤 3：启用特权网关意图​

这是整个设置中最关键的一步。如果没有启用正确的意图，你的机器人可以连接到 Discord，但将无法读取消息内容。

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

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

通过将 Server Members Intent 和 Message Content Intent 的开关拨到 ON 来启用两者。

  • 没有 Message Content Intent，你的机器人会收到消息事件，但消息文本是空的——机器人根本看不到你输入的内容。
  • 没有 Server Members Intent，机器人无法为允许的用户列表解析用户名，并且可能无法识别是谁在给它发消息。
这是 Discord 机器人无法工作的首要原因

如果你的机器人已在线但从不回复消息，Message Content Intent 几乎肯定被禁用了。返回 开发者门户，选择你的应用 → Bot → Privileged Gateway Intents，确保 Message Content Intent 开关已拨到 ON。点击 Save Changes。

关于服务器数量：

  • 如果你的机器人在少于 100 个服务器中，你可以自由地开关意图。
  • 如果你的机器人在100 个或更多服务器中，Discord 要求你提交验证申请才能使用特权意图。对于个人使用，这无需担心。

点击页面底部的 Save Changes。

步骤 4：获取机器人令牌​

机器人令牌是 Hermes Agent 用来以你的机器人身份登录的凭证。仍在 Bot 页面上：

  1. 在 Token 部分下，点击 Reset Token。
  2. 如果你的 Discord 账户启用了双重身份验证，请输入你的 2FA 代码。
  3. Discord 将显示你的新令牌。立即复制它。
令牌仅显示一次

令牌只显示一次。如果你丢失了它，需要重置并生成一个新的。切勿公开分享你的令牌或将其提交到 Git —— 任何拥有此令牌的人都可以完全控制你的机器人。

将令牌安全地存储在某处（例如密码管理器）。你将在步骤 8 中需要它。

步骤 5：生成邀请 URL​

你需要一个 OAuth2 URL 来邀请机器人加入你的服务器。有两种方法可以做到这一点：

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

需要公共机器人

此方法要求**在步骤 2 中将 Public Bot 设置为 ON。如果你将 Public Bot 设置为 OFF，请改用下面的 Manual URL 方法。

  1. 在左侧边栏中，点击 Installation。
  2. 在 Installation Contexts 下，启用 Guild Install。
  3. 对于 Install Link，选择 Discord Provided Link。
  4. 在 Guild Install 的 Default Install Settings 下：
    • Scopes：选择 bot 和 applications.commands
    • Permissions：选择下面列出的权限。

选项 B：手动 URL​

你可以直接使用以下格式构建邀请 URL：

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

将 YOUR_APP_ID 替换为步骤 1 中的 Application ID。

所需权限​

这些是你的机器人所需的最低权限：

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

推荐的附加权限​

  • Send Messages in Threads —— 在主题对话中回复
  • Add Reactions —— 对消息做出反应以示确认

权限整数值​

级别权限整数值包含内容
最低117760查看频道、发送消息、读取消息历史记录、附加文件
推荐274878286912以上所有权限，外加嵌入链接、在主题中发送消息、添加反应

步骤 6：邀请到你的服务器​

  1. 在浏览器中打开邀请 URL（来自 Installation 选项卡或你构建的手动 URL）。
  2. 在 Add to Server 下拉菜单中，选择你的服务器。
  3. 点击 Continue，然后点击 Authorize。
  4. 如果出现提示，请完成验证码。
信息

你需要在 Discord 服务器上拥有 Manage Server 权限才能邀请机器人。如果在下拉菜单中看不到你的服务器，请让服务器管理员使用邀请链接。

授权后，机器人将出现在你服务器的成员列表中（在启动 Hermes 网关之前，它将显示为离线状态）。

步骤 7：查找你的 Discord 用户 ID​

Hermes Agent 使用你的 Discord 用户 ID 来控制谁可以与机器人交互。查找方法如下：

  1. 打开 Discord（桌面版或网页版）。
  2. 进入 Settings → Advanced → 将 Developer Mode 开关拨到 ON。
  3. 关闭设置。
  4. 右键单击你自己的用户名（在消息、成员列表或你的个人资料中）→ Copy User ID。

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

提示

开发者模式也允许你以同样的方式复制 频道 ID 和 服务器 ID —— 右键单击频道或服务器名称并选择 Copy ID。如果你想手动设置主频道，将需要频道 ID。

步骤 8：配置 Hermes Agent​

选项 A：交互式设置（推荐）​

运行引导式设置命令：

hermes gateway setup

出现提示时选择 Discord，然后在被要求时粘贴你的机器人令牌和用户 ID。

选项 B：手动配置​

将以下内容添加到你的 ~/.hermes/.env 文件中：

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

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

# 可选：无需 @提及 即可回复（默认：true = 需要提及）
# DISCORD_REQUIRE_MENTION=false

# 可选：机器人无需 @提及 即可回复的频道（逗号分隔的频道 ID）
# DISCORD_FREE_RESPONSE_CHANNELS=1234567890,9876543210

~/.hermes/config.yaml 中的可选行为设置：

discord:
  require_mention: true

group_sessions_per_user: true
  • discord.require_mention: true 使 Hermes 在正常的服务器流量中保持安静，除非被提及
  • group_sessions_per_user: true 在共享频道和主题中保持每个参与者的上下文隔离

启动网关​

配置完成后，启动 Discord 网关：

hermes gateway

机器人应在几秒钟内在 Discord 中上线。给它发送一条消息——可以是私信，也可以是在它能看到的频道中——进行测试。

提示

你可以在后台或作为 systemd 服务运行 hermes gateway 以实现持久运行。详情请参阅部署文档。

主频道​

你可以指定一个“主频道”，机器人可以在其中发送主动消息（例如定时任务输出、提醒和通知）。有两种设置方法：

使用斜杠命令​

在机器人所在的任意 Discord 频道中键入 /sethome。该频道将成为主频道。

手动配置​

将这些内容添加到你的 ~/.hermes/.env 文件中：

DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"

将 ID 替换为实际的频道 ID（右键点击频道 → 在开发者模式下复制频道 ID）。

语音消息​

Hermes Agent 支持 Discord 语音消息：

  • 接收到的语音消息 会自动使用配置的 STT 提供商进行转录：本地的 faster-whisper（无需密钥）、Groq Whisper（需要 GROQ_API_KEY）或 OpenAI Whisper（需要 VOICE_TOOLS_OPENAI_KEY）。
  • 文本转语音：使用 /voice tts 命令，让机器人在发送文本回复的同时发送语音音频回复。
  • Discord 语音频道：Hermes 也可以加入语音频道，听取用户发言，并在频道中进行语音回复。

完整的设置和操作指南，请参阅：

故障排除​

机器人已上线但不响应消息​

原因：消息内容意图未启用。

解决方法：前往 开发者门户 → 你的应用 → Bot → Privileged Gateway Intents → 启用 Message Content Intent → 保存更改。重启网关。

启动时出现 "Disallowed Intents" 错误​

原因：你的代码请求了在开发者门户中未启用的意图。

解决方法：在 Bot 设置中启用所有三个 Privileged Gateway Intents（Presence、Server Members、Message Content），然后重启。

机器人在特定频道中看不到消息​

原因：机器人的角色没有查看该频道的权限。

解决方法：在 Discord 中，进入该频道的设置 → 权限 → 添加机器人的角色，并启用 查看频道 和 读取消息历史 权限。

403 Forbidden 错误​

原因：机器人缺少必要的权限。

解决方法：使用第 5 步中的 URL，以正确的权限重新邀请机器人，或者在服务器设置 → 角色中手动调整机器人的角色权限。

机器人离线​

原因：Hermes 网关未运行，或者令牌不正确。

解决方法：检查 hermes gateway 是否正在运行。验证 .env 文件中的 DISCORD_BOT_TOKEN。如果你最近重置了令牌，请更新它。

"User not allowed" / 机器人忽略你​

原因：你的用户 ID 不在 DISCORD_ALLOWED_USERS 列表中。

解决方法：将你的用户 ID 添加到 ~/.hermes/.env 文件中的 DISCORD_ALLOWED_USERS 变量中，然后重启网关。

同一频道中的人意外地共享上下文​

原因：group_sessions_per_user 被禁用，或者平台无法为该上下文中的消息提供用户 ID。

解决方法：在 ~/.hermes/config.yaml 中设置以下内容并重启网关：

group_sessions_per_user: true

如果你有意想要一个共享房间的对话，请保持关闭状态——只是需要预期会共享对话历史和共享中断行为。

安全​

注意

务必设置 DISCORD_ALLOWED_USERS 来限制可以与机器人交互的人员。如果不设置，作为安全措施，网关默认会拒绝所有用户。只添加你信任的人员的用户 ID——授权用户拥有对代理功能的完全访问权限，包括工具使用和系统访问。

有关保护 Hermes Agent 部署的更多信息，请参阅安全指南。