Skip to main content

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。此设置仅适用于服务器频道，不适用于私信。
tip

如果你想创建一个普通帮助频道，让成员无需每次都 @ 机器人就能与 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 交流，即使他们使用的是同一个可见的 Discord 频道，Hermes 默认也会将其视为两个独立的对话。

这一行为由 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)。

你将进入 通用信息 (General Information) 页面。请记下 应用 ID —— 后续生成邀请链接时需要用到。

第二步：创建机器人​

  1. 在左侧边栏点击 机器人 (Bot)。
  2. Discord 会自动为你创建一个机器人用户。你会看到机器人的用户名，可以自行修改。
  3. 在 授权流程 (Authorization Flow) 区域：
    • 将 公开机器人 (Public Bot) 设为 开启 (ON) —— 使用 Discord 提供的邀请链接所必需（推荐）。这允许“安装 (Installation)”标签页生成默认授权 URL。
    • 保持 需要 OAuth2 代码授权 (Require OAuth2 Code Grant) 为 关闭 (OFF)。
tip

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

私有机器人替代方案

如果你希望保持机器人私密（即关闭 Public Bot），则必须在第 5 步使用 手动 URL 方法，而非“安装”标签页。Discord 提供的链接要求 Public Bot 必须启用。

第三步：启用高权限网关意图（Gateway Intents）​

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

在 机器人 (Bot) 页面，向下滚动至 高权限网关意图 (Privileged Gateway Intents)。你会看到三个开关：

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

请将“服务器成员意图”和“消息内容意图”都开启（设为 ON）。

  • 若缺少 消息内容意图，机器人虽能收到消息事件，但消息文本为空——机器人根本看不到你说什么。
  • 若缺少 服务器成员意图，机器人无法解析允许用户列表中的用户名，可能无法识别是谁在与它通信。
这是 Discord 机器人无法工作的首要原因

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

关于服务器数量说明：

  • 如果你的机器人在 少于 100 个服务器 中，可以自由切换意图。
  • 如果你的机器人在 100 个及以上服务器 中，Discord 要求提交验证申请才能使用高权限意图。对于个人使用，这通常不是问题。

点击页面底部的 保存更改 (Save Changes)。

第四步：获取机器人令牌（Token）​

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

  1. 在 令牌 (Token) 区域，点击 重置令牌 (Reset Token)。
  2. 如果你的 Discord 账号启用了双重验证，请输入你的 2FA 验证码。
  3. Discord 将显示你的新令牌。请立即复制。
令牌仅显示一次

令牌仅显示一次。一旦丢失，必须重置并生成新令牌。切勿公开分享令牌，也切勿将其提交到 Git。任何人持有此令牌均可完全控制你的机器人。 ::

将令牌妥善保存（例如使用密码管理器）。你将在第 8 步用到它。

第五步：生成邀请链接​

你需要一个 OAuth2 链接来邀请机器人加入你的服务器。有两种方法可选：

选项 A：使用“安装”标签页（推荐）:::note[需要公开机器人]​

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

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

选项 B：手动链接​

您可以直接使用以下格式构造邀请链接：

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. 在浏览器中打开邀请链接（来自安装标签页或您自行构建的手动链接）。
  2. 在 添加到服务器 下拉菜单中，选择您的服务器。
  3. 点击 继续，然后点击 授权。
  4. 如果提示，请完成验证码验证。
info

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

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

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

Hermes Agent 使用您的 Discord 用户 ID 来控制谁可以与机器人互动。如何查找：

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

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

tip

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

第8步：配置 Hermes Agent​

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

运行引导式设置命令：

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 中上线。向其发送一条消息——无论是私信还是它能看见的频道中的消息——以进行测试。

tip

您可以将 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 时，机器人仅在被 @mentioned 时才响应服务器频道中的消息。设为 false 可使机器人在每个频道中响应所有消息。
DISCORD_FREE_RESPONSE_CHANNELS否—用逗号分隔的频道 ID 列表，机器人在此类频道中无需 @mention 即可响应，即使 DISCORD_REQUIRE_MENTION 为 true 也适用。
DISCORD_IGNORE_NO_MENTION否true当 true 时，若消息未提及机器人但涉及其他用户，机器人将保持沉默。防止机器人介入针对他人的对话。仅适用于服务器频道，不适用于私信。
DISCORD_AUTO_THREAD否true当 true 时，每当在普通文本频道中收到 @mention，机器人会自动创建一个新线程，使每次对话独立（类似 Slack 的行为）。已存在于线程或私信中的消息不受此设置影响。
DISCORD_ALLOW_BOTS否"none"控制机器人如何处理来自其他 Discord 机器人的消息。"none" — 忽略所有其他机器人。"mentions" — 仅接受明确提及 Hermes 的机器人消息。"all" — 接受所有机器人消息。
DISCORD_REACTIONS否true当 true 时，机器人在处理消息期间会添加表情反应（👀 表示开始，✅ 成功，❌ 错误）。设为 false 可完全禁用反应。
DISCORD_IGNORED_CHANNELS否—用逗号分隔的频道 ID 列表，机器人在此类频道中 永远不回应，即使 @mentioned 也适用。优先级高于所有其他频道设置。
DISCORD_NO_THREAD_CHANNELS否—用逗号分隔的频道 ID 列表，机器人在此类频道中直接回复，而非创建线程。仅在 DISCORD_AUTO_THREAD 为 true 时相关。
DISCORD_REPLY_TO_MODE否"first"控制回复引用行为："off" — 永不回复原消息；"first" — 仅在第一个消息块时回复引用（默认）；"all" — 在每个消息块中都进行回复引用。

配置文件 (config.yaml)​

discord 部分在 ~/.hermes/config.yaml 中镜像上述环境变量。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

启用后，机器人仅在被直接 @mentioned 时才会在服务器频道中响应。私信始终会得到回复，与此设置无关。

discord.free_response_channels​

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

机器人在此类频道中无需 @mention 即可响应所有消息。支持逗号分隔字符串或 YAML 列表格式：

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

# List format
discord:
  free_response_channels:
    - 1234567890
    - 9876543210

如果某个线程的父频道在此列表中，则该线程也会变为无需提及。

discord.auto_thread​

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

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

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

discord.reactions​

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

控制机器人是否在处理消息时添加表情反应作为视觉反馈：

  • 👀 在机器人开始处理您的消息时添加
  • ✅ 在成功交付响应时添加
  • ❌ 在处理过程中发生错误时添加如果发现反应功能令人分心，或机器人的角色没有 添加反应 权限，请禁用此功能。

discord.ignored_channels​

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

指定机器人从不响应的频道 ID 列表，即使消息直接 @ 了机器人也如此。该设置具有最高优先级——只要某个频道在此列表中，机器人将静默忽略该频道内的所有消息，无论其他任何设置（如 require_mention、free_response_channels 等）如何配置。

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

# List format
discord:
  ignored_channels:
    - 1234567890
    - 9876543210

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

discord.no_thread_channels​

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

指定机器人在这些频道中直接回复到原频道，而不是自动创建新线程。此设置仅在 auto_thread 为 true（默认值）时生效。在这些频道中，机器人会像普通消息一样直接回复，而非生成新线程。

discord:
  no_thread_channels:
    - 1234567890  # Bot responds inline here

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

group_sessions_per_user​

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

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

当 true 时：Alice 和 Bob 在 #research 中与 Hermes 的对话各自独立，互不干扰。
当 false 时：整个频道共享一份对话记录和一个运行中的代理槽位。

group_sessions_per_user: true

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

display.tool_progress​

类型： 字符串 — 默认值： "all" — 可选值： off, new, all, verbose

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

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

display.tool_progress_command​

类型： 布尔值 — 默认值： 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）。

解决方法：前往 开发者门户 → 您的应用 → Bot → 高级网关意图 → 启用 消息内容意图 → 保存更改。重启网关。

启动时报 “Disallowed Intents” 错误​

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

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

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

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

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

出现 403 Forbidden 错误​

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

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

机器人离线​

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

解决方法：检查 hermes gateway 是否正在运行。确认 DISCORD_BOT_TOKEN 在您的 .env 文件中正确无误。若最近重置过令牌，请更新。

“用户不允许” / 机器人无视你​

原因：你的用户 ID 未在 DISCORD_ALLOWED_USERS 中。

解决方法：将你的用户 ID 添加至 DISCORD_ALLOWED_USERS 的 ~/.hermes/.env 中，并重启网关。

同一频道中的用户意外共享上下文​

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

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

group_sessions_per_user: true

若您有意实现共享房间对话，可保持关闭——但需接受共享对话历史和共享中断行为。

安全性​

warning

始终设置 DISCORD_ALLOWED_USERS 以限制谁可以与机器人互动。未设置时，网关默认拒绝所有用户，作为安全措施。仅添加您信任的用户 ID——授权用户将获得对代理功能的完全访问权限，包括工具使用和系统访问。

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