跳到主要内容

Discord 集成

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

在设置之前，这里是最让人关心的部分：Hermes 进入您的服务器后会如何表现。

Hermes 的行为表现​

上下文行为
私信 (DMs)Hermes 会响应每一条消息，无需 @mention。每个私信会话都有独立的会话状态。
服务器频道默认情况下，Hermes 仅在您 @mention 它时才响应。如果您在未提及它的频道中发帖，Hermes 会忽略该消息。
自由响应频道您可以通过设置 DISCORD_FREE_RESPONSE_CHANNELS 使特定频道无需提及即可响应，或通过设置 DISCORD_REQUIRE_MENTION=false 全局禁用提及要求。
线程 (Threads)Hermes 会在同一线程中回复。除非该线程或其父频道被配置为自由响应模式，否则仍需遵守提及规则。线程会与父频道隔离，保持独立的会话历史。
多人共享的频道默认情况下，Hermes 会为频道内的每个用户单独隔离会话历史，以确保安全性和清晰性。两人在同一个频道中对话不会共享同一份对话记录，除非您显式禁用此行为。
提及其他用户的消息当 DISCORD_IGNORE_NO_MENTION 为 true（默认值）时，如果消息 @ 了其他用户但未提及机器人，Hermes 将保持沉默。这可防止机器人介入针对其他人的对话。若希望机器人对所有消息做出响应（无论是否提及），可将其设为 false。此设置仅适用于服务器频道，不适用于私信。
提示

如果您希望创建一个普通机器人帮助频道，让用户无需每次标记机器人即可与 Hermes 交流，可将该频道添加到 DISCORD_FREE_RESPONSE_CHANNELS 列表中。

Discord 网关模型​

Hermes 在 Discord 上并非无状态的 Webhook 回复机制。它通过完整的消息网关运行，这意味着每个传入消息都会经过以下流程：

  1. 授权验证 (DISCORD_ALLOWED_USERS)
  2. 提及 / 自由响应检查
  3. 会话查找
  4. 会话历史加载
  5. 正常的 Hermes 代理执行（包括工具、记忆和斜杠命令）
  6. 响应发送回 Discord

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

Discord 中的会话模型​

默认情况下：

  • 每个私信拥有独立的会话
  • 每个服务器线程拥有独立的会话命名空间
  • 每个在共享频道中的用户在该频道内拥有独立的会话

因此，如果 Alice 和 Bob 都在 #research 频道中与 Hermes 对话，Hermes 默认会将它们视为两个独立的对话，尽管它们使用的是同一个可见的 Discord 频道。

此行为由 config.yaml 控制：

group_sessions_per_user: true

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

group_sessions_per_user: false

共享会话在协作型房间中可能很有用，但也意味着：

  • 用户共享上下文增长和 token 成本
  • 某个人的长时间工具任务可能导致其他人的上下文膨胀
  • 某个人的运行任务可能中断另一个人在同一房间中的后续提问

中断与并发​

Hermes 通过会话键跟踪正在运行的代理。

当使用默认设置 group_sessions_per_user: true 时：

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

当设置为 group_sessions_per_user: false 时：

  • 整个房间共享该频道/线程的一个运行代理槽位
  • 不同用户的后续消息可能相互中断或排队等待

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

第一步：创建 Discord 应用​

  1. 访问 Discord 开发者门户，使用您的 Discord 账户登录。
  2. 点击右上角的 New Application（新建应用）。
  3. 输入应用名称（例如：“Hermes Agent”），并接受开发者服务条款。
  4. 点击 Create（创建）。

您将进入 通用信息 页面。请记下 Application ID —— 后续构建邀请链接时需要用到。

第二步：创建机器人​

  1. 在左侧边栏中点击 Bot。
  2. Discord 会自动为您的应用创建一个机器人用户。您将看到机器人的用户名，可进行自定义。
  3. 在 授权流程 部分：
    • 将 Public Bot 设置为 ON —— 使用 Discord 提供的邀请链接所必需（推荐）。这将允许“安装”标签页生成默认授权 URL。
    • 保持 Require OAuth2 Code Grant 为 OFF。
提示

您可在此页面为机器人设置自定义头像和横幅。这是用户在 Discord 中看到的内容。

私有机器人替代方案

如果你希望将机器人保持私有（公共机器人 = 关闭），则在第 5 步中必须使用手动 URL 方法，而不是安装标签页。Discord 提供的链接需要启用公共机器人功能。

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

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

在 机器人 页面中，向下滚动至 特权网关意图。你会看到三个开关：

意图用途是否必需
状态意图查看用户在线/离线状态可选
服务器成员意图访问成员列表，解析用户名必需
消息内容意图读取消息的文本内容必需

请将 服务器成员意图 和 消息内容意图 两个选项都切换为 开启。

  • 如果没有启用 消息内容意图，机器人虽然会收到消息事件，但消息文本为空——机器人实际上无法看到你输入的内容。
  • 如果没有启用 服务器成员意图，机器人将无法解析允许用户列表中的用户名，可能无法识别是谁在与它通信。
这是 Discord 机器人无法工作的首要原因

如果机器人显示在线但从未响应消息，消息内容意图 几乎肯定被禁用了。请返回 开发者门户，选择你的应用 → 机器人 → 特权网关意图，确保 消息内容意图 已开启。点击 保存更改。

关于服务器数量：

  • 如果你的机器人在 少于 100 个服务器 中，可以自由地开启或关闭意图。
  • 如果你的机器人在 100 个或更多服务器 中，Discord 要求你提交验证申请才能使用特权意图。对于个人使用，这通常不是问题。

点击页面底部的 保存更改。

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

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

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

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

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

第 5 步：生成邀请 URL​

你需要一个 OAuth2 URL 来将机器人邀请到你的服务器。有两种方法：

需要公共机器人

此方法要求在第 2 步中将 公共机器人 设置为 开启。如果你将公共机器人设为关闭，请改用下方的手动 URL 方法。

  1. 在左侧边栏中，点击 安装。
  2. 在 安装上下文 下，启用 服务器安装。
  3. 对于 安装链接，选择 Discord 提供的链接。
  4. 在 服务器安装的默认安装设置 下：
    • 作用域：选择 bot 和 applications.commands
    • 权限：选择下方列出的权限。

选项 B：手动 URL​

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

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

将 YOUR_APP_ID 替换为第 1 步中的应用 ID。

所需权限​

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

  • 查看频道 —— 查看其有权限访问的频道
  • 发送消息 —— 回复你的消息
  • 嵌入链接 —— 格式化富文本响应
  • 附加文件 —— 发送图片、音频和文件输出
  • 读取消息历史 —— 保持对话上下文
  • 在线程中发送消息 —— 回复线程中的对话
  • 添加表情反应 —— 通过表情反应表示确认

权限整数​

等级权限整数包含内容
最小117760查看频道、发送消息、读取消息历史、附加文件
推荐274878286912上述全部权限，外加嵌入链接、在线程中发送消息、添加表情反应

第 6 步：将机器人邀请到你的服务器​

  1. 在浏览器中打开邀请 URL（来自安装标签页或你构造的手动 URL）。
  2. 在 添加到服务器 下拉菜单中，选择你的服务器。
  3. 点击 继续，然后点击 授权。
  4. 如果提示，完成验证码。
信息

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

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

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

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

  1. 打开 Discord（桌面版或网页版应用）。
  2. 进入 设置 → 高级 → 将 开发者模式 开关切换为 开启。
  3. 关闭设置页面。
  4. 右键点击自己的用户名（在消息中、成员列表中或个人资料中）→ 选择 复制用户 ID。

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

提示

开发者模式还允许你以相同方式复制 频道 ID 和 服务器 ID —— 右键点击频道或服务器名称，然后选择“复制 ID”。如果你希望手动设置主页频道，将需要频道 ID。

第 8 步：配置 Hermes 代理​

运行引导式设置命令：

hermes gateway setup

提示时选择 Discord，然后粘贴你的机器人令牌和用户 ID。

选项 B：手动配置​

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

# Required
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=284102345871466496

# Multiple allowed users (comma-separated)
# DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543

然后启动网关：

hermes gateway

机器人应在几秒钟内于 Discord 中上线。向它发送一条消息——无论是私信还是它可见的频道中——以进行测试。

提示

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

配置参考​

Discord 的行为由两个文件控制：~/.hermes/.env 用于凭证和环境级别开关，以及 ~/.hermes/config.yaml 用于结构化设置。当两者均被设置时，环境变量的优先级高于 config.yaml 中的值。

环境变量（.env）​

变量是否必需默认值描述
DISCORD_BOT_TOKEN是—来自 Discord 开发者门户 的机器人令牌。
DISCORD_ALLOWED_USERS是—允许与机器人交互的 Discord 用户 ID 列表，以逗号分隔。若未设置，网关将拒绝所有用户。
DISCORD_HOME_CHANNEL否—机器人发送主动消息（如定时任务输出、提醒、通知）的频道 ID。
DISCORD_HOME_CHANNEL_NAME否"Home"在日志和状态输出中显示的主页频道名称。
DISCORD_REQUIRE_MENTION否true当为 true 时，机器人仅在服务器频道中被 @提及 时才响应。设为 false 可使机器人在每个频道中响应所有消息。
DISCORD_FREE_RESPONSE_CHANNELS否—机器人无需 @提及 即可响应的频道 ID 列表，以逗号分隔。即使 DISCORD_REQUIRE_MENTION 为 true 也适用。
DISCORD_IGNORE_NO_MENTION否true当为 true 时，若消息 @提及 了其他用户但未提及机器人，机器人将保持沉默。防止机器人介入针对其他人的对话。仅适用于服务器频道，不适用于私信。
DISCORD_AUTO_THREAD否true当为 true 时，为文本频道中的每个 @提及 自动创建新线程，使每次对话独立（类似 Slack 行为）。已位于线程或私信中的消息不受影响。
DISCORD_ALLOW_BOTS否"none"控制机器人如何处理来自其他 Discord 机器人的消息。"none" —— 忽略所有其他机器人。"mentions" —— 仅接受被 @提及 的机器人消息。"all" —— 接受所有机器人消息。
DISCORD_REACTIONS否true当为 true 时，机器人在处理消息期间添加表情符号反应（👀 表示开始，✅ 表示成功，❌ 表示错误）。设为 false 可完全禁用反应。
DISCORD_IGNORED_CHANNELS否—机器人 从不 响应的频道 ID 列表，以逗号分隔。优先级高于所有其他频道设置。
DISCORD_NO_THREAD_CHANNELS否—机器人直接在频道中回复而非创建线程的频道 ID 列表，以逗号分隔。仅在 DISCORD_AUTO_THREAD 为 true 时有效。
DISCORD_REPLY_TO_MODE否"first"控制回复引用行为："off" —— 从不引用原消息，"first" —— 仅在第一个消息块中引用（默认），"all" —— 在每个消息块中都引用。

配置文件（config.yaml）​

~/.hermes/config.yaml 中的 discord 部分与上述环境变量一一对应。config.yaml 中的设置作为默认值应用——如果已设置对应的环境变量，则环境变量的值将覆盖配置文件中的值。

# Discord-specific settings
discord:
  require_mention: true           # Require @mention in server channels
  free_response_channels: ""      # Comma-separated channel IDs (or YAML list)
  auto_thread: true               # Auto-create threads on @mention
  reactions: true                 # Add emoji reactions during processing
  ignored_channels: []            # Channel IDs where bot never responds
  no_thread_channels: []          # Channel IDs where bot responds without threading

# Session isolation (applies to all gateway platforms, not just Discord)
group_sessions_per_user: true     # Isolate sessions per user in shared channels

discord.require_mention​

类型： 布尔值 — 默认值： true

启用后，机器人仅在服务器频道中被直接 @提及 时才响应。私信始终会得到响应，不受此设置影响。

discord.free_response_channels​

类型： 字符串或列表 — 默认值： ""

机器人无需 @提及 即可响应的频道 ID 列表。支持逗号分隔字符串或 YAML 列表格式：

# String format
discord:
  free_response_channels: "1234567890,9876543210"

# List format
discord:
  free_response_channels:
    - 1234567890
    - 9876543210

如果线程的父频道位于此列表中，则该线程也将变为无需提及。

discord.auto_thread​

类型： 布尔值 — 默认值： true

启用后，常规文本频道中的每个 @mention 都会自动为对话创建一个新线程。这能保持主频道的整洁，并为每次对话提供独立的会话历史记录。线程创建后，该线程中的后续消息不再需要 @mention — 机器人会知道它已参与其中。

在现有线程或私信（DM）中发送的消息不受此设置影响。

discord.reactions​

类型： boolean — 默认值： true

控制机器人是否在消息上添加表情符号反应作为视觉反馈：

  • 👀 在机器人开始处理你的消息时添加
  • ✅ 在响应成功交付时添加
  • ❌ 在处理过程中发生错误时添加

如果你觉得这些反应令人分心，或机器人的角色没有 添加反应 权限，请禁用此功能。

discord.ignored_channels​

类型： string 或 list — 默认值： []

机器人从不响应的频道 ID 列表，即使被直接 @mentioned 也是如此。此设置具有最高优先级 — 如果某个频道在此列表中，机器人将静默忽略该频道中的所有消息，无论 require_mention、free_response_channels 或其他任何设置如何。

# String format
discord:
  ignored_channels: "1234567890,9876543210"

# List format
discord:
  ignored_channels:
    - 1234567890
    - 9876543210

如果某个线程的父频道在此列表中，则该线程中的消息也会被忽略。

discord.no_thread_channels​

类型： string 或 list — 默认值： []

机器人在这些频道中直接在频道内回复，而不是自动创建线程。此设置仅在 auto_thread 为 true（默认值）时生效。在此类频道中，机器人以普通消息形式直接回复，而不是创建新线程。

discord:
  no_thread_channels:
    - 1234567890  # Bot responds inline here

适用于专门用于机器人交互的频道，避免线程带来不必要的干扰。

group_sessions_per_user​

类型： boolean — 默认值： true

这是一个全局网关设置（非 Discord 特有），控制同一频道中的用户是否拥有隔离的会话历史。

当为 true 时：Alice 和 Bob 在 #research 中交谈时，各自与 Hermes 有独立的对话。当为 false 时：整个频道共享一个对话记录和一个运行中的代理槽。

group_sessions_per_user: true

请参阅上方的 会话模型 部分，了解每种模式的完整影响。

display.tool_progress​

类型： string — 默认值： "all" — 可选值： off, new, all, verbose

控制机器人在处理过程中是否在聊天中发送进度消息（例如，“正在读取文件...”，“正在运行终端命令...”）。这是一个全局网关设置，适用于所有平台。

display:
  tool_progress: "all"    # off | new | all | verbose
  • off — 不发送进度消息
  • new — 每轮仅显示第一个工具调用
  • all — 显示所有工具调用（网关消息中截断为 40 个字符）
  • verbose — 显示完整的工具调用详情（可能生成较长的消息）

display.tool_progress_command​

类型： boolean — 默认值： false

启用后，将在网关中启用 /verbose 斜杠命令，让你无需编辑 config.yaml 即可循环切换工具进度模式（off → new → all → verbose → off）。

display:
  tool_progress_command: true

交互式模型选择器​

在 Discord 频道中发送 /model（不带参数）以打开基于下拉菜单的模型选择器：

  1. 提供者选择 — 一个下拉菜单，显示可用的提供者（最多 25 个）。
  2. 模型选择 — 第二个下拉菜单，列出所选提供者的模型（最多 25 个）。

选择器在 120 秒后超时。只有授权用户（在 DISCORD_ALLOWED_USERS 中的用户）可以使用。如果你知道模型名称，可直接输入 /model <name>。

技能的原生斜杠命令​

Hermes 会自动将已安装的技能注册为 原生 Discord 应用程序命令。这意味着技能会像内置命令一样出现在 Discord 的自动补全 / 菜单中。

  • 每个技能都会成为一个 Discord 斜杠命令（例如 /code-review、/ascii-art）
  • 技能接受一个可选的 args 字符串参数
  • Discord 对每个机器人的应用命令数量有限制，最多 100 个 — 如果你的技能数量超过可用槽位，多余的技能将被跳过，并在日志中发出警告
  • 技能在机器人启动时与内置命令（如 /model、/reset、/background）一同注册

无需额外配置 — 任何通过 hermes skills install 安装的技能，在下一次网关重启时都会自动注册为 Discord 斜杠命令。

主频道​

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

使用斜杠命令​

在机器人所在的任意 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 还可以加入语音频道，聆听用户发言，并在频道中进行语音回应。

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

故障排除​

机器人在线但不响应消息​

原因：消息内容意图（Message Content Intent）被禁用。

修复方法：前往 开发者门户 → 你的应用 → 机器人 → 高级网关意图（Privileged Gateway Intents）→ 启用 消息内容意图 → 保存更改。然后重启网关。

启动时出现“不被允许的意图”错误​

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

修复方法：在机器人设置中启用全部三个高级网关意图（状态、服务器成员、消息内容），然后重启。

机器人无法查看特定频道中的消息​

原因：机器人的角色在该频道中缺少查看权限。

修复方法：在 Discord 中进入该频道的设置 → 权限 → 为机器人的角色添加 查看频道 和 阅读消息历史 权限。

出现 403 Forbidden 错误​

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

修复方法：使用第 5 步提供的链接重新邀请机器人，或手动在服务器设置 → 角色中调整机器人的权限。

机器人离线​

原因：Hermes 网关未运行，或令牌（token）错误。

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

“用户不允许” / 机器人忽略你​

原因：你的用户 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 代理部署的更多信息，请参阅 安全指南。