好奇心花园🪴

搜索

SearchSearch

最近的笔记

Discord

2026年5月24日49分钟阅读

Discord 设置

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

在设置之前，这里是大多数人最想知道的：Hermes 进入您的服务器后的行为。

Hermes 的行为

上下文行为
私信Hermes 回复每条消息。无需 @提及。每条私信有自己的会话。
服务器频道默认情况下，Hermes 仅在您 @提及 时回复。如果您在频道中发布消息而不提及它，Hermes 会忽略该消息。
自由回复频道您可以使用 DISCORD_FREE_RESPONSE_CHANNELS 使特定频道无需提及，或使用 DISCORD_REQUIRE_MENTION=false 全局禁用提及。这些频道中的消息会内联回复——跳过自动线程化，以保持频道轻量聊天。
线程Hermes 在同一线程中回复。提及规则仍然适用，除非该线程或其父频道被配置为自由回复。线程与父频道在会话历史方面保持隔离。
多用户共享频道默认情况下，Hermes 在频道内按用户隔离会话历史，以确保安全和清晰。两个人在同一频道中交谈不会共享一个记录，除非您显式禁用此功能。
提及其他用户的消息当 DISCORD_IGNORE_NO_MENTION 为 true（默认）时，如果一条消息 @提及了其他用户但没有提及机器人，Hermes 保持静默。这防止机器人跳入针对其他人的对话。仅适用于服务器频道，不适用于私信。

:::tip 如果您想要一个普通机器人帮助频道，人们可以在其中与 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 交谈，Hermes 默认将它们视为独立的对话，即使它们使用相同的可见 Discord 频道。

这由 config.yaml 控制：

group_sessions_per_user: true

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

group_sessions_per_user: false

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

  • 用户共享上下文增长和 token 成本
  • 一个人的长时间工具密集型任务可能会膨胀其他人的上下文
  • 一个人的进行中运行可能会中断同一房间中另一个人的后续操作

中断和并发

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

使用默认的 group_sessions_per_user: true：

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

使用 group_sessions_per_user: false：

  • 整个房间共享该频道/线程的一个正在运行 agent 槽位
  • 来自不同人的后续消息可以互相中断或排队

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

第 1 步：创建 Discord 应用

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

您将进入通用信息页面。记下应用 ID——稍后您需要它来构建邀请 URL。

第 2 步：创建机器人

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

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

:::info[私密机器人替代方案] 如果您希望保持机器人私密（Public Bot = OFF），您必须使用第 5 步中的手动 URL 方法，而不是安装标签。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，机器人无法为用户白名单解析用户名，并且可能无法识别谁在给它发消息。

:::warning[这是 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 将显示您的新令牌。立即复制它。

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

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

第 5 步：生成邀请 URL

您需要 OAuth2 URL 来邀请机器人加入您的服务器。有两种方法：

选项 A：使用安装标签（推荐）

:::note[需要 Public Bot] 此方法需要第 2 步中将 Public Bot 设置为 ON。如果您将 Public Bot 设置为 OFF，请改用下面的手动 URL 方法。 :::

  1. 在左侧边栏中，点击 Installation。
  2. 在 Installation Contexts 下，启用 Guild Install。
  3. 对于 Install Link，选择 Discord Provided Link。
  4. 在 Default Install Settings for Guild Install：
    • 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 步中的应用 ID。

必需权限

您的机器人需要的最低权限：

  • 查看频道 — 查看有权访问的频道
  • 发送消息 — 回复您的消息
  • 嵌入链接 — 格式化富回复
  • 附加文件 — 发送图片、音频和文件输出
  • 阅读消息历史 — 维护对话上下文

推荐的额外权限

  • 在线程中发送消息 — 在线程对话中回复
  • 添加反应 — 对消息添加反应以表示确认

权限整数

级别权限整数包含内容
最小117760查看频道、发送消息、阅读消息历史、附加文件
推荐274878286912以上所有加上嵌入链接、在线程中发送消息、添加反应

第 6 步：邀请到您的服务器

  1. 在浏览器中打开邀请 URL（从安装标签或您构建的手动 URL）。
  2. 在 Add to Server 下拉菜单中，选择您的服务器。
  3. 点击 Continue，然后 Authorize。
  4. 如果提示，完成 CAPTCHA。

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

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

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

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

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

您的用户 ID 是一个像 284102345871466496 这样的长数字。

:::tip 开发者模式还允许您以相同方式复制频道 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

然后启动网关：

hermes gateway

机器人应在几秒内在 Discord 中上线。给它发送一条消息——无论是私信还是它在其中且有权限的频道——进行测试。

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

配置参考

Discord 行为通过两个文件控制：~/.hermes/.env 用于凭据和环境级开关，以及 ~/.hermes/config.yaml 用于结构化设置。当两者都设置时，环境变量始终优先于 config.yaml 的值。

环境变量（.env）

变量必需默认值描述
DISCORD_BOT_TOKEN是—来自 Discord 开发者门户 的机器人令牌。
DISCORD_ALLOWED_USERS是—逗号分隔的 Discord 用户 ID，允许与机器人交互。没有这个或 DISCORD_ALLOWED_ROLES，网关会拒绝所有用户。
DISCORD_ALLOWED_ROLES否—逗号分隔的 Discord 角色 ID。拥有其中任一角色的成员被授权——与 DISCORD_ALLOWED_USERS 是”或”语义。连接时自动启用 Server Members Intent。当管理团队轮换时很有用：新管理员在获得角色后即可获得访问权限，无需推送配置。
DISCORD_HOME_CHANNEL否—机器人发送主动消息（定时任务输出、提醒、通知）的频道 ID。
DISCORD_HOME_CHANNEL_NAME否"Home"主频道在日志和状态输出中的显示名称。
DISCORD_COMMAND_SYNC_POLICY否"safe"控制原生斜杠命令启动同步。"safe" 比较现有全局命令并仅更新更改的内容，当 Discord 元数据更改无法通过补丁应用时重新创建命令。"bulk" 保留旧的 tree.sync() 行为。"off" 完全跳过启动同步。
DISCORD_REQUIRE_MENTION否true当为 true 时，机器人仅在服务器频道中被 @提及 时回复。设为 false 以响应所有频道中的每条消息。
DISCORD_THREAD_REQUIRE_MENTION否false当为 true 时，线程内提及快捷方式被禁用——线程与频道一样需要门控，即使机器人已经参与也需要 @提及。当多个机器人共享一个线程且您希望每个机器人仅在显式 @提及 时触发时使用。
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" — 仅接受 @提及 Hermes 的机器人消息。"all" — 接受所有机器人消息。
DISCORD_REACTIONS否true当为 true 时，机器人在处理过程中添加表情反应（开始时 👀，成功时 ✅，错误时 ❌）。设为 false 以完全禁用反应。
DISCORD_IGNORED_CHANNELS否—逗号分隔的频道 ID，机器人永远不会在这些频道中回复，即使被 @提及。优先于所有其他频道设置。
DISCORD_ALLOWED_CHANNELS否—逗号分隔的频道 ID。设置后，机器人仅在这些频道中回复（加上私信，如果允许）。覆盖 config.yaml 的 discord.allowed_channels。与 DISCORD_IGNORED_CHANNELS 结合使用以表达允许/拒绝规则。
DISCORD_NO_THREAD_CHANNELS否—逗号分隔的频道 ID，机器人直接在该频道中回复，而不是创建线程。仅当 DISCORD_AUTO_THREAD 为 true 时相关。
DISCORD_HISTORY_BACKFILL否true当为 true 时，在机器人被提及时会预先附加最近的频道回滚（自机器人的最后一次回复以来）到用户消息前。恢复机器人因 require_mention 而本会错过的上下文。在私信和自由回复频道中跳过。设为 false 以禁用。
DISCORD_HISTORY_BACKFILL_LIMIT否50在组装回填块时向后扫描的最大消息数。实际上，扫描通常会更早停止——在机器人自己在该频道中的最后一条消息处。
DISCORD_REPLY_TO_MODE否"first"控制回复引用行为："off" — 从不回复原始消息，"first" — 仅在第一个消息块上回复引用（默认），"all" — 在每个块上回复引用。
DISCORD_ALLOW_MENTION_EVERYONE否false当为 false（默认）时，即使机器人的响应包含这些令牌，也不能 @ 通知 @everyone 或 @here。设为 true 以重新启用。见下文的提及控制。
DISCORD_ALLOW_MENTION_ROLES否false当为 false（默认）时，机器人不能 @ 通知角色。设为 true 以允许。
DISCORD_ALLOW_MENTION_USERS否true当为 true（默认）时，机器人可以通过 ID @ 通知个人用户。
DISCORD_ALLOW_MENTION_REPLIED_USER否true当为 true（默认）时，回复消息会 @ 通知原始作者。
DISCORD_PROXY否—Discord 连接的代理 URL（HTTP、WebSocket、REST）。覆盖 HTTPS_PROXY/ALL_PROXY。支持 http://、https:// 和 socks5:// 协议。
DISCORD_ALLOW_ANY_ATTACHMENT否false当为 true 时，机器人接受任何文件类型的附件（不仅限于内置的 PDF/文本/zip/办公文档白名单）。未知类型会缓存到磁盘，并以 application/octet-stream MIME 呈现给 agent，以便它可以用 terminal / read_file / ffprobe 等检查。
DISCORD_MAX_ATTACHMENT_BYTES否33554432网关将下载和缓存的每个附件的最大字节数。默认 32 MiB。设为 0 表示无上限（附件在写入时保存在内存中，因此无限制会带来实际的内存成本）。
HERMES_DISCORD_TEXT_BATCH_DELAY_SECONDS否0.6适配器在刷新排队文本块之前等待的宽限期（秒）。有助于平滑流式输出。
HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS否2.0当单条消息超过 Discord 长度限制时，拆分块之间的延迟（秒）。

配置文件（config.yaml）

~/.hermes/config.yaml 中的 discord 部分镜像上述环境变量。Config.yaml 设置作为默认值应用——如果等效的环境变量已设置，则环境变量优先。

# Discord 特定设置
discord:
  require_mention: true           # 在服务器频道中要求 @提及
  thread_require_mention: false   # 如果为 true，在线程中也要求 @提及（多机器人线程）
  free_response_channels: ""      # 逗号分隔的频道 ID（或 YAML 列表）
  auto_thread: true               # 在 @提及时自动创建线程
  reactions: true                 # 在处理过程中添加表情反应
  ignored_channels: []            # 机器人永不回复的频道 ID
  no_thread_channels: []          # 机器人无线程回复的频道 ID
  history_backfill: true          # 在提及时预先附加最近的频道回滚（默认：true）
  history_backfill_limit: 50      # 向后扫描的最大消息数（默认：50）
  channel_prompts: {}             # 每频道的临时系统提示
  allow_mentions:                 # 机器人允许 @ 通知的内容（安全默认值）
    everyone: false               # @everyone / @here 通知（默认：false）
    roles: false                  # @role 通知（默认：false）
    users: true                   # @user 通知（默认：true）
    replied_user: true            # 回复引用 @ 通知作者（默认：true）
 
# 会话隔离（适用于所有网关平台，不仅限于 Discord）
group_sessions_per_user: true     # 在共享频道中按用户隔离会话

discord.require_mention

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

启用后，机器人仅在服务器频道中被直接 @提及 时回复。无论此设置如何，私信总是获得回复。

discord.thread_require_mention

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

默认情况下，一旦机器人参与了一个线程（在 @提及 时自动创建，或已回复过一次），它会继续回复该线程中的每条后续消息，无需再次 @提及。这是 1 对 1 对话的正确默认值。

在多机器人线程中，用户每轮针对一个机器人时，此默认值会变成陷阱——线程中的每个其他机器人也会对每条消息触发，消耗额度并污染频道。设置 thread_require_mention: true 以禁用线程内快捷方式，并以与频道相同的方式门控线程。显式 @提及 仍然像以前一样工作。

discord:
  require_mention: true
  thread_require_mention: true    # 多机器人设置

discord.free_response_channels

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

机器人无需 @提及 即可响应所有消息的频道 ID。接受逗号分隔的字符串或 YAML 列表：

# 字符串格式
discord:
  free_response_channels: "1234567890,9876543210"
 
# 列表格式
discord:
  free_response_channels:
    - 1234567890
    - 9876543210

如果线程的父频道在此列表中，该线程也成为免提及的。

自由回复频道也跳过自动线程化——机器人内联回复，而不是每条消息都创建新线程。这使频道保持轻量聊天界面的可用性。如果您想要线程行为，不要将该频道列为自由回复（改用正常的 @提及 流程）。

discord.auto_thread

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

启用后，每个普通文本频道中的 @提及 会自动为对话创建一个新线程。这保持主频道整洁，并为每个对话提供自己的隔离会话历史。一旦线程被创建，该线程中的后续消息不需要 @提及——机器人知道它已经参与。设置 thread_require_mention 为 true 以在多机器人设置中禁用此线程内快捷方式。

现有线程或私信中的消息不受此设置影响。列在 discord.free_response_channels 或 discord.no_thread_channels 中的频道也会绕过自动线程化，获得内联回复。

discord.reactions

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

控制机器人是否添加表情反应作为视觉反馈：

  • 👀 在机器人开始处理您的消息时添加
  • ✅ 在响应成功投递时添加
  • ❌ 如果在处理过程中发生错误

如果您发现反应分散注意力，或者机器人的角色没有 Add Reactions 权限，请禁用此功能。

discord.ignored_channels

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

机器人永远不会回复的频道 ID，即使直接 @提及。这具有最高优先级——如果一个频道在此列表中，机器人静默忽略那里的所有消息，无论 require_mention、free_response_channels 或任何其他设置如何。

# 字符串格式
discord:
  ignored_channels: "1234567890,9876543210"
 
# 列表格式
discord:
  ignored_channels:
    - 1234567890
    - 9876543210

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

discord.no_thread_channels

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

机器人直接在该频道中回复而不是自动创建线程的频道 ID。这只在 auto_thread 为 true（默认）时生效。在这些频道中，机器人像普通消息一样内联回复，而不是产生新线程。

discord:
  no_thread_channels:
    - 1234567890  # 机器人在这里内联回复

对于专门用于机器人交互的频道很有用，线程化会增加不必要的噪音。

discord.channel_prompts

类型： 映射 — 默认值： {}

每频道临时系统提示，在匹配的 Discord 频道或线程中的每轮对话时注入，不会持久化到会话历史中。

discord:
  channel_prompts:
    "1234567890": |
      此频道用于研究任务。偏好深入比较、
      引用和简洁的综合。
    "9876543210": |
      此论坛用于治疗式支持。保持温暖、接地
      且不评判。

行为：

  • 精确的线程/频道 ID 匹配优先。
  • 如果消息到达线程或论坛帖子内部，且该线程没有显式条目，Hermes 回退到父频道/论坛 ID。
  • 提示在运行时临时应用，因此更改它们会立即影响未来的轮次，无需重写过去的会话历史。

discord.history_backfill

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

启用后，机器人在每次 @提及 时恢复错过的频道消息。使用 require_mention: true 时，机器人只处理直接标记它的消息——频道中的其他所有内容对会话记录都是不可见的。历史回填在触发时向后扫描最近的频道历史，收集机器人上次回复和当前提及之间的消息，并将其包含为上下文。

按界面的行为：

  • 服务器频道（使用 require_mention: true）：回填扫描自机器人上次回复以来的频道。当其他参与者在机器人未被寻址时发布了消息时很有用。
  • 线程：回填仅扫描线程——Discord 的 channel.history() 在线程上只返回该线程的消息，而不是父频道。这是正确的作用域，因为线程通常是自包含的对话。
  • 私信：跳过。每条私信消息都会触发机器人，因此会话记录已经完整——没有提及间隙需要填充。
  • 自由回复频道和机器人自己自动创建的线程：跳过，原因相同——没有提及门控意味着没有间隙。

每个用户会话（group_sessions_per_user: true，默认）也受益：用户的会话缺少其他频道参与者发布的上下文，以及用户自己在标记机器人之前的消息。回填填充两者。

discord:
  history_backfill: true   # 默认

要关闭它：

discord:
  history_backfill: false

注意： 在机器人处理期间（在触发和响应之间）到达的消息不会被捕获。这是一个可接受的简化——用户可以重新发送或再次标记。

discord.history_backfill_limit

类型： 整数 — 默认值： 50

恢复频道上下文时向后扫描的最大消息数。实际上，扫描通常会更早停止——在机器人自己在该频道中的最后一条消息处，这是轮次之间的自然边界。此限制是冷启动和长时间无机器人消息时的安全上限。

discord:
  history_backfill: true
  history_backfill_limit: 50

group_sessions_per_user

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

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

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

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 斜杠命令在网关中可用，让您可以循环切换工具进度模式（off → new → all → verbose → off），而无需编辑 config.yaml。

display:
  tool_progress_command: true

斜杠命令访问控制

默认情况下，每个被允许的用户可以运行所有斜杠命令。要将您的白名单拆分为管理员（完全斜杠命令访问权限）和普通用户（仅限您显式启用的命令），请在 Discord 平台的 extra 块中添加 allow_admin_from 和 user_allowed_commands：

gateway:
  platforms:
    discord:
      extra:
        # 现有用户白名单（不变）
        allow_from:
          - "123456789012345678"  # 管理员用户 ID
          - "999888777666555444"  # 普通用户 ID
 
        # 新增 — 管理员获得所有斜杠命令（内置 + 插件）
        allow_admin_from:
          - "123456789012345678"
 
        # 新增 — 非管理员允许用户只能运行这些斜杠命令。
        # /help 和 /whoami 始终允许，以便用户查看其访问权限。
        user_allowed_commands:
          - status
          - model
          - history
 
        # 可选：用于服务器频道的独立管理员/命令列表
        group_allow_admin_from:
          - "123456789012345678"
        group_user_allowed_commands:
          - status

行为：

  • 某个作用域（DM 或服务器频道）的 allow_admin_from 中的用户可以通过实时命令注册表运行每个已注册的斜杠命令——内置和插件注册的。
  • 不在 allow_admin_from 中的用户只能运行 user_allowed_commands 中列出的命令，加上始终允许的基础命令：/help 和 /whoami。
  • 普通聊天（非斜杠消息）不受影响。非管理员用户仍然可以正常与 agent 对话；只是不能触发任意命令。
  • 向后兼容： 如果某个作用域未设置 allow_admin_from，则该作用域的斜杠命令门控被禁用。现有安装无需更改即可继续工作。
  • DM 管理员身份并不意味着服务器频道管理员身份。每个作用域都有自己的管理员列表。

使用 /whoami 查看当前作用域、您的层级（管理员/用户/无限制）以及您可以运行的斜杠命令。

交互式模型选择器

在 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 应用运行多个 Hermes 网关（例如预发布 + 生产），只有其中一个应该拥有全局斜杠命令注册的所有权——否则最后一次启动胜出，注册会摇摆不定。在”跟随”网关上关闭斜杠注册：

gateway:
  platforms:
    discord:
      extra:
        slash_commands: false   # 默认：true

在”主”网关上保持 true 可保持正常行为——内置命令和已安装技能的全局 / 菜单命令。

发送媒体（send_message + MEDIA: 标签）

Discord 适配器通过 send_message 工具和 agent 发出的内联 MEDIA:/path/to/file 标签，支持每种常见媒体类型的原生文件上传：

类型投递方式
图片（PNG/JPG/WebP）原生 Discord 图片附件，内联预览
动画 GIFsend_animation 以 animation.gif 上传，以便 Discord 内联播放（而不是静态缩略图）
视频（MP4/MOV）send_video — 原生视频播放器
音频/语音send_voice — 尽可能使用原生语音消息，否则文件附件
文档（PDF/ZIP/docx 等）send_document — 带下载按钮的原生附件

Discord 的每次上传大小限制取决于服务器的加速等级（免费 25 MB，最高 500 MB）。如果 Hermes 收到 HTTP 413，适配器会回退到指向本地缓存路径的链接，而不是静默失败。

接收任意文件类型

默认情况下，机器人缓存匹配内置白名单的上传——图片、音频、视频、PDF、文本/markdown/csv/log、JSON/XML/YAML/TOML、zip、docx/xlsx/pptx。其他任何内容（例如 .wav、.bin、自定义扩展名的转储）会被记录为 Unsupported document type 并在 agent 看到之前丢弃。

要接受任意文件类型，启用 discord.allow_any_attachment：

discord:
  allow_any_attachment: true
  # 可选 — 提高/禁用每个文件的大小上限。默认是 32 MiB。
  # 整个文件在缓存时保存在内存中，因此无限制
  # 上传会带来实际的内存成本。
  max_attachment_bytes: 33554432   # 字节；0 = 无限制

当此标志开启时，任何上传的文件都会被下载、缓存在 ~/.hermes/cache/documents/ 下，并作为 DOCUMENT 类型的消息事件以 application/octet-stream MIME 呈现给 agent。agent 会收到一条上下文注释，指向本地路径（通过 to_agent_visible_cache_path 为 Docker/Modal 沙盒终端自动翻译），并可以使用 terminal（ffprobe、unzip、file、strings 等）或 read_file 检查文件。文件内容不会内联到提示中——只有路径——因此二进制上传不会膨胀上下文窗口。

已在内置白名单中的已知文本格式（.txt、.md、.log）继续自动注入内容，最多 100 KiB；当标志开启时，此行为不变。

等效环境变量：DISCORD_ALLOW_ANY_ATTACHMENT=true 和 DISCORD_MAX_ATTACHMENT_BYTES=33554432（或 0 表示无上限）。

:::warning 无限制的内存成本 禁用大小上限（max_attachment_bytes: 0）意味着用户可以给机器人上传多 GB 的文件，网关会在缓存到磁盘的同时忠实地在内存中缓冲。仅在可信的单用户安装中设置此选项。对于共享机器人，保持默认的 32 MiB 或保守地提高。 :::

交互式提示（clarify）

当 agent 调用 clarify 工具时——询问您偏好的方法、获取任务后反馈或在非平凡决策前检查——Discord 会为每个选项渲染一个按钮：

我应该为仪表板使用哪个框架？

[1. Next.js] [2. Remix] [3. Astro] [其他（输入答案）]

点击编号按钮回答，或点击其他输入自由格式的回复（您在该频道中发送的下一条消息成为答案）。开放式 clarify 调用（无预设选项）跳过按钮，直接捕获您的下一条消息。

按钮在选择后会自动禁用，因此重复点击不会双重解析提示。通过 ~/.hermes/config.yaml 中的 agent.clarify_timeout 配置响应超时（默认 600 秒）。如果您在超时内未回复，agent 会发送一个哨兵消息并适应，而不是挂起。

主频道

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

使用斜杠命令

在机器人存在的任何 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 还可以加入语音频道，聆听用户说话，并在频道中回话。

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

论坛频道

Discord 论坛频道（类型 15）不接受直接消息——论坛中的每个帖子必须是一个线程。Hermes 自动检测论坛频道，并在需要发送时创建一个新的线程帖子，因此 send_message、TTS、图片、语音消息和文件附件都可以正常工作，无需 agent 特殊处理。

  • 线程名称来自消息的第一行（markdown 标题前缀被去除，限制 100 个字符）。当消息仅为附件时，文件名用作回退线程名称。
  • 附件随新线程的起始消息一起发送——无需单独的上传步骤，不会部分发送。
  • 一次调用，一个线程：每次论坛发送创建一个新线程。因此，对同一论坛的连续发送会产生独立的线程。
  • 检测分三层：首先是频道目录缓存，其次是进程本地探测缓存，最后是实时的 GET /channels/{id} 探测（其结果随后在进程生命周期内记忆）。

刷新目录（在暴露此功能的平台上的 /channels refresh，或网关重启）会填充机器人启动后创建的任何论坛频道到缓存中。

故障排除

机器人在线但不响应消息

原因： Message Content Intent 被禁用。

修复： 前往开发者门户 → 您的应用 → Bot → Privileged Gateway Intents → 启用 Message Content Intent → Save Changes。重启网关。

启动时出现”Disallowed Intents”错误

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

修复： 在 Bot 设置中启用所有三个特权网关意图（Presence、Server Members、Message Content），然后重启。

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

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

修复： 在 Discord 中，进入频道的设置 → Permissions → 添加机器人角色，并启用 View Channel 和 Read Message History。

403 Forbidden 错误

原因： 机器人缺少所需的权限。

修复： 使用第 5 步中的 URL 以正确的权限重新邀请机器人，或在 Server Settings → Roles 中手动调整机器人的角色权限。

机器人离线

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

修复： 检查 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

如果您有意想要共享房间对话，保持关闭——只是要预料到共享会话历史和共享中断行为。

安全性

:::warning 始终设置 DISCORD_ALLOWED_USERS（或 DISCORD_ALLOWED_ROLES）以限制可以与机器人交互的人。如果没有这两者，网关默认拒绝所有用户作为安全措施。只授权您信任的人——授权用户对 agent 的能力具有完全访问权限，包括工具使用和系统访问。 :::

基于角色的访问控制

对于通过角色而非个人用户列表管理访问的服务器（管理员团队、支持人员、内部工具），使用 DISCORD_ALLOWED_ROLES——逗号分隔的角色 ID。拥有其中任一角色的成员被授权。

# ~/.hermes/.env — 可与 DISCORD_ALLOWED_USERS 一起使用或替代它
DISCORD_ALLOWED_ROLES=987654321098765432,876543210987654321

语义：

  • 与用户白名单的”或”关系。 如果用户的 ID 在 DISCORD_ALLOWED_USERS 中或他们拥有 DISCORD_ALLOWED_ROLES 中的任一角色，则用户被授权。
  • Server Members Intent 自动启用。 当设置 DISCORD_ALLOWED_ROLES 时，机器人在连接时启用 Members intent——Discord 需要用此 intent 才能随成员记录发送角色信息。
  • 角色 ID，而非名称。 从 Discord 获取：用户设置 → 高级 → 开发者模式 ON，然后右键点击任意角色 → Copy Role ID。
  • 私信回退。 在私信中，角色检查扫描共同服务器；具有任何共享服务器中被允许角色的用户在私信中也被授权。

当管理团队轮换时，这是首选模式——新管理员在获得角色后即可获得访问权限，无需编辑 .env 或重启网关。

提及控制

默认情况下，Hermes 阻止机器人 @ 通知 @everyone、@here 和角色提及，即使其回复包含这些令牌。这防止措辞不当的提示或回显的用户内容污染整个服务器。个人 @user 通知和回复引用通知（小的”正在回复…”标签）保持启用，以便正常对话继续工作。

您可以通过环境变量或 config.yaml 放宽这些默认值：

# ~/.hermes/config.yaml
discord:
  allow_mentions:
    everyone: false      # 允许机器人 @ 通知 @everyone / @here
    roles: false         # 允许机器人 @ 通知 @role 提及
    users: true          # 允许机器人 @ 通知个人 @users
    replied_user: true   # 回复作者时 @ 通知他们
# ~/.hermes/.env — 环境变量优先于 config.yaml
DISCORD_ALLOW_MENTION_EVERYONE=false
DISCORD_ALLOW_MENTION_ROLES=false
DISCORD_ALLOW_MENTION_USERS=true
DISCORD_ALLOW_MENTION_REPLIED_USER=true

:::tip 除非您确切知道为什么需要，否则将 everyone 和 roles 保持在 false。LLM 很容易在看似正常的回复中产生字符串 @everyone；没有此保护，这会通知您服务器中的每个成员。 :::

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

关系图谱

反向链接