hermes教程-Discord

Discord 设置

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

在开始设置之前，以下是大多数人想了解的部分：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 对话，Hermes 默认会将其视为独立的对话，即使他们使用的是同一个可见的 Discord 频道。

这由 config.yaml 控制：

group_sessions_per_user: true

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

group_sessions_per_user: false

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

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

中断与并发

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

使用默认的 group_sessions_per_user: true：

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

使用 group_sessions_per_user: false：

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

本指南将引导您完成完整的设置过程——从在 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 提供的邀请链接（推荐）。这允许安装选项卡生成默认的授权 URL。
   • 将 Require OAuth2 Code Grant 保持为 OFF。

提示

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

:::info[私有机器人替代方案] 如果您希望保持机器人私有（Public Bot = OFF），则必须在步骤 5 中使用 Manual URL 方法，而不是安装选项卡。Discord 提供的链接需要启用 Public Bot。 :::

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

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

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

同时启用 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：生成邀请链接

您需要一个 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 的 Guild Install 下：
   • Scopes：选择 bot 和 applications.commands
   • Permissions：选择下面列出的权限。

选项 B：手动 URL

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

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

必需权限

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

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

推荐附加权限

• Send Messages in Threads — 在线程对话中响应
• Add Reactions — 对消息添加反应以进行确认

权限整数

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

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

信息

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

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

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

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

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

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

提示

开发者模式还允许您以相同方式复制 频道 ID 和 服务器 ID——右键单击频道或服务器名称，然后选择复制 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 中。向其发送一条消息——无论是私信还是它可以看到的频道中的消息——以进行测试。

提示

您可以在后台运行 hermes gateway 或将其作为 systemd 服务运行以实现持久运行。有关详细信息，请参阅部署文档。

配置参考

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

环境变量（.env）

配置文件（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:                 # 机器人允许 ping 的内容（安全默认值）
    everyone: false               # @everyone / @here ping（默认：false）
    roles: false                  # @role ping（默认：false）
    users: true                   # @user ping（默认：true）
    replied_user: true            # 回复引用 ping 作者（默认：true）
## 会话隔离（适用于所有网关平台，不仅仅是 Discord）
group_sessions_per_user: true     # 在共享频道中按用户隔离会话

discord.require_mention

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

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

discord.thread_require_mention

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

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

在多机器人线程中，用户每轮针对一个机器人，这个默认行为就会成为一个隐患——线程中的每个其他机器人也会对每条消息触发，消耗积分并刷屏。设置 thread_require_mention: true 以禁用线程内快捷方式，使线程与频道一样需要门控。显式的 @提及 仍然有效。

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

discord.free_response_channels

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

在这些频道中，机器人无需 @提及 即可响应所有消息。接受逗号分隔的字符串或 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

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

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

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

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

discord.no_thread_channels

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

在这些频道中，机器人直接在频道中响应，而不是自动创建线程。这仅在 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 时：Alice 和 Bob 在 #research 中交谈，各自与 Hermes 有独立的对话。当为 false 时：整个频道共享一个对话记录和一个正在运行的代理槽位。

group_sessions_per_user: true

有关每种模式的完整含义，请参阅上面的会话模型部分。

display.tool_progress

类型： 字符串 — 默认值： "all" — 值： off、new、all、verbose

控制机器人在处理时是否在聊天中发送进度消息（例如 "Reading file..."、"Running terminal command..."）。这是一个全局网关设置，适用于所有平台。

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

斜杠命令访问控制

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

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

行为：

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

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

交互式模型选择器

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

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

选择器在 120 秒后超时。只有授权用户（在 DISCORD_ALLOWED_USERS 中的用户）才能与其交互。如果您知道模型名称，请直接输入 /model <名称>。

技能的原生斜杠命令

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 工具和代理发出的内联 MEDIA:/path/to/file 标签支持每种常见媒体类型的原生文件上传：

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

接收任意文件类型

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

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

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

当此标志打开时，任何上传的文件都会被下载，缓存在 ~/.hermes/cache/documents/ 下，并以 DOCUMENT 类型的消息事件呈现给代理，MIME 类型为 application/octet-stream。代理会收到一个指向本地路径的上下文注释（通过 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 表示无上限）。

警告——无上限的内存成本

禁用大小上限（max_attachment_bytes: 0）意味着用户可以给机器人上传一个多 GB 的文件，网关会忠实地通过内存缓冲并缓存到磁盘。仅在受信任的单用户安装中设置此选项。对于共享机器人，请保留默认的 32 MiB 或保守地提高。

交互式提示（clarify）

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

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

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

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

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

主频道

您可以指定一个“主频道”，机器人会向其中发送主动消息（例如 cron 作业输出、提醒和通知）。有两种设置方法：

使用斜杠命令

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

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

• 语音模式
• 将语音模式与 Hermes 一起使用

语音频道音效（环境音 + 口头确认）

当机器人在语音频道中时，您可以赋予它更对话式的感觉：在开始工作前发出简短的口头确认（"让我查一下"），以及在工具运行时播放微妙的“思考”环境音——语音会降低环境音，并在完成后将其恢复，类似于 Grok 语音模式。

discord.py 每个连接只播放一个音频流，因此 Hermes 在传出流上安装了一个软件混音器，将环境循环、确认音和 TTS 回复合并到该单个流中——它们重叠而不是相互切断。

此功能默认关闭。在 config.yaml 中启用：

discord:
  voice_fx:
    enabled: true          # 主开关
    ambient_enabled: true  # 工具运行时空闲的“思考”背景音
    ambient_path: ""       # 自定义循环文件（任何音频格式）；"" = 内置合成垫音
    ambient_gain: 0.18     # 空闲背景音音量（0.0–1.0）
    duck_gain: 0.06        # 机器人说话时的环境音音量
    speech_gain: 1.0       # TTS / 确认音音量
    ack_enabled: true      # 在每轮第一次工具调用前说一句简短短语
    ack_phrases:           # 随机选择；设置为 [] 以禁用口头确认
      - "让我查一下。"
      - "请稍等。"
      - "正在检查。"

注意：

• 确认音每轮最多触发一次，仅当机器人在语音频道中且混音器处于活动状态时。它使用您配置的 TTS 提供商。
• ambient_path 接受任何 ffmpeg 可以解码的文件；它会无缝循环。留空以使用内置合成垫音（无需资产）。
• 所有设置都在 config.yaml 中（而不是 .env）——它们是行为性的，不是秘密。
• 当 voice_fx.enabled 为 false 时，语音播放使用原始的一次性路径，没有任何变化。

论坛频道

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

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

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

故障排除

机器人在线但不响应消息

原因：Message Content Intent 被禁用。

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

启动时出现“Disallowed Intents”错误

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

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

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

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

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

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（或 DISCORD_ALLOWED_ROLES）以限制谁可以与机器人交互。如果没有这两者，网关默认会拒绝所有用户作为安全措施。仅授权您信任的人——授权用户对代理的能力拥有完全访问权限，包括工具使用和系统访问。

基于角色的访问控制

对于通过角色而不是单个用户列表管理访问权限的服务器（版主团队、支持人员、内部工具），请使用 DISCORD_ALLOWED_ROLES——一个逗号分隔的角色 ID 列表。任何拥有这些角色之一的成员都将被授权。

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

语义：

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

当管理团队人员变动时，这是首选模式——新版主一旦获得角色即可获得访问权限，无需编辑 .env 或重启网关。

提及控制

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

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

## ~/.hermes/config.yaml
discord:
  allow_mentions:
    everyone: false      # 允许机器人 ping @everyone / @here
    roles: false         # 允许机器人 ping @role 提及
    users: true          # 允许机器人 ping 单个 @用户
    replied_user: true   # 回复消息时 ping 作者

## ~/.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

提示

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

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