跳到主要内容

Discord 配置

Hermes Agent 可作为机器人与 Discord 集成，让您通过私信或服务器频道与 AI 助手交流。机器人接收您的消息，通过 Hermes Agent 流水线（包括工具使用、记忆和推理）处理，并实时响应。支持文字、语音消息、文件附件和斜杠命令。

在配置之前，先了解大多数人最想知道的内容：Hermes 在您的服务器中的行为方式。

Hermes 行为说明​

场景行为
私信Hermes 响应所有消息，无需 @提及。每个私信拥有独立会话。
服务器频道默认情况下，Hermes 仅在被 @提及 时响应。不提及直接发消息时，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 网关模型​

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

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

  • 用户共享上下文增长和 Token 消耗
  • 一个人的长时工具密集型任务可能会膨胀其他人的上下文
  • 一个人正在执行的任务可能会被同一房间中另一个人的后续消息中断

中断与并发​

Hermes 按会话键追踪运行中的 Agent。

在默认的 group_sessions_per_user: true 下：

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

在 group_sessions_per_user: false 下：

  • 整个房间共享该频道/帖子的一个运行中 Agent 槽位
  • 不同人的后续消息可能互相中断或排队等待

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

第一步：创建 Discord 应用​

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

您将进入 General Information 页面。记录 Application ID —— 后续构建邀请 URL 时需要用到。

第二步：创建机器人​

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

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

私有机器人替代方案

如果您希望保持机器人私有（Public Bot = OFF），必须在第五步中使用手动 URL 方式，而不是 Installation 标签页。Discord 提供的链接要求启用 Public Bot。

第三步：启用特权网关 Intent​

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

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

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

请将 Server Members Intent 和 Message Content Intent 都切换为开启状态。

  • 没有 Message Content Intent，机器人收到消息事件但消息文本为空 —— 机器人根本无法看到您输入的内容。
  • 没有 Server Members Intent，机器人无法解析允许用户列表中的用户名，可能无法识别发消息的人。
这是 Discord 机器人不工作的第一大原因

如果您的机器人在线但从不响应消息，Message Content Intent 几乎肯定是未启用的。返回开发者门户，选择您的应用 → Bot → Privileged Gateway Intents，确保 Message Content Intent 已切换为 ON。点击 Save Changes。

关于服务器数量：

  • 如果您的机器人在少于 100 个服务器中，可以自由切换 Intent。
  • 如果在 100 个或以上服务器中，Discord 要求您提交验证申请才能使用特权 Intent。对于个人使用，无需担心此问题。

点击页面底部的 Save Changes。

第四步：获取机器人 Token​

机器人 Token 是 Hermes Agent 用来以您的机器人身份登录的凭据。仍在 Bot 页面上：

  1. 在 Token 部分，点击 Reset Token。
  2. 如果您的 Discord 账号启用了双重认证，请输入 2FA 代码。
  3. Discord 将显示您的新 Token。立即复制它。
Token 仅显示一次

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

将 Token 存储在安全位置（例如密码管理器）。第八步时会用到。

第五步：生成邀请 URL​

您需要 OAuth2 URL 将机器人邀请到您的服务器。有两种方式：

方式 A：使用 Installation 标签页（推荐）​

需要 Public Bot

此方式要求在第二步中将 Public Bot 设置为 ON。若设置为 OFF，请使用下方的手动 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 替换为第一步中的 Application ID。

必要权限​

机器人所需的最低权限：

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

推荐的额外权限​

  • Send Messages in Threads — 在帖子对话中回复
  • Add Reactions — 对消息添加反应

权限整数​

级别权限整数包含内容
最小117760View Channels、Send Messages、Read Message History、Attach Files
推荐274878286912以上所有，加上 Embed Links、Send Messages in Threads、Add Reactions

第六步：邀请到您的服务器​

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

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

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

第七步：找到您的 Discord 用户 ID​

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

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

您的用户 ID 是一串类似 284102345871466496 的长数字。

提示

Developer Mode 还允许您用同样的方式复制频道 ID 和服务器 ID —— 右键点击频道或服务器名称，选择 Copy ID。如果您想手动设置主频道，需要用到频道 ID。

第八步：配置 Hermes Agent​

方式 A：交互式配置（推荐）​

运行引导式配置命令：

hermes gateway setup

出现提示时选择 Discord，然后粘贴机器人 Token 和用户 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）​

变量必填默认值说明
DISCORD_BOT_TOKEN是—来自 Discord 开发者门户的机器人 Token。
DISCORD_ALLOWED_USERS是—允许与机器人交互的 Discord 用户 ID（逗号分隔）。没有此项或 DISCORD_ALLOWED_ROLES，网关将拒绝所有用户。
DISCORD_ALLOWED_ROLES否—Discord 角色 ID（逗号分隔）。拥有这些角色之一的成员即被授权 —— 与 DISCORD_ALLOWED_USERS 为 OR 关系。连接时自动启用 Server Members Intent。当管理团队变动时很有用：新管理员获得角色后即可访问，无需推送配置。
DISCORD_HOME_CHANNEL否—机器人发送主动消息（定时输出、提醒、通知）的频道 ID。
DISCORD_HOME_CHANNEL_NAME否"Home"主频道在日志和状态输出中的显示名称。
DISCORD_COMMAND_SYNC_POLICY否"safe"控制原生斜杠命令的启动同步。"safe" 对比现有全局命令，只更新变化的内容，当 Discord 元数据无法通过 patch 应用时重建命令。"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_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（默认）时，机器人无法 ping @everyone 或 @here，即使其响应包含这些词元。设为 true 可恢复此功能。详见下方提及控制。
DISCORD_ALLOW_MENTION_ROLES否false为 false（默认）时，机器人无法 ping @角色 提及。设为 true 可允许。
DISCORD_ALLOW_MENTION_USERS否true为 true（默认）时，机器人可以通过 ID ping 个别用户。
DISCORD_ALLOW_MENTION_REPLIED_USER否true为 true（默认）时，回复消息会 ping 原作者。
DISCORD_PROXY否—Discord 连接的代理 URL（HTTP、WebSocket、REST）。覆盖 HTTPS_PROXY/ALL_PROXY。支持 http://、https:// 和 socks5:// 方案。
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:                 # 机器人允许 ping 的对象（安全默认值）
    everyone: false               # @everyone / @here ping（默认：false）
    roles: false                  # @角色 ping（默认：false）
    users: true                   # @用户 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​

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

机器人无需 @提及 即可响应所有消息的频道 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 斜杠命令在网关中可用，让您无需编辑 config.yaml 就能循环切换工具进度模式（off → new → all → verbose → off）。

display:
  tool_progress_command: true

交互式模型选择器​

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

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

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

技能的原生斜杠命令​

Hermes 自动将已安装的技能（Skills）注册为 Discord 原生应用命令，这意味着技能会出现在 Discord 的自动完成 / 菜单中，与内置命令并列。

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

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

禁用斜杠命令注册​

如果您对同一个 Discord 应用运行多个 Hermes 网关（例如 staging + production），只有一个应该拥有全局斜杠命令注册 —— 否则最后一次启动会覆盖注册。在"从属"网关上关闭斜杠注册：

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

主频道​

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

使用斜杠命令​

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

手动配置​

在 ~/.hermes/.env 中添加：

DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"

将 ID 替换为实际频道 ID（开启 Developer Mode 后右键点击 → Copy Channel ID）。

语音消息​

Hermes Agent 支持 Discord 语音消息：

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

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

论坛频道​

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

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

刷新目录（在支持此功能的平台上使用 /channels refresh，或重启网关）会将机器人启动后创建的所有论坛频道填充到缓存中。

斜杠命令访问控制​

默认情况下，每个被允许的用户都可以运行所有斜杠命令。要将你的允许列表拆分为管理员（完整的斜杠命令访问权限）和普通用户（仅你显式启用的命令），请将 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 中列出的某作用域（DM 或服务器频道）的用户可以运行每个已注册的斜杠命令 —— 内置命令和插件注册的命令 —— 通过实时注册表。
  • 不在 allow_admin_from 中的用户只能运行 user_allowed_commands 中列出的命令，加上始终允许的基线：/help 和 /whoami。
  • 普通聊天（非斜杠消息）不受影响。非管理员用户仍然可以与 Agent 正常交谈，他们只是不能触发任意命令。
  • 向后兼容： 如果未为某个作用域设置 allow_admin_from，该作用域的斜杠命令门控被禁用。现有安装无需更改即可继续工作。
  • DM 管理员状态并不意味着服务器频道管理员状态。每个作用域都有自己的管理员列表。

使用 /whoami 查看活动作用域、你的层级（管理员/用户/无限制）以及你可以运行哪些斜杠命令。

故障排查​

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

原因：Message Content Intent 已禁用。

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

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

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

解决方案：在 Bot 设置中启用所有三个特权网关 Intent（Presence、Server Members、Message Content），然后重启。

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

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

解决方案：在 Discord 中，进入频道设置 → 权限 → 为机器人角色添加 View Channel 和 Read Message History 权限。

403 Forbidden 错误​

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

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

机器人离线​

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

解决方案：检查 hermes gateway 是否正在运行。验证 .env 文件中的 DISCORD_BOT_TOKEN。如果您最近重置了 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）以限制可与机器人交互的用户。没有任一设置时，网关默认拒绝所有用户作为安全措施。只授权您信任的人 —— 授权用户拥有 Agent 全部功能的完整访问权限，包括工具使用和系统访问。

基于角色的访问控制​

对于通过角色而非个人用户列表管理访问权限的服务器（管理团队、支持人员、内部工具），使用 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 Intent —— Discord 需要此权限才能在成员记录中发送角色信息。
  • 使用角色 ID，不是名称。 从 Discord 获取：用户设置 → 高级 → 开启 Developer Mode，然后右键点击任意角色 → Copy Role ID。
  • 私信回退。 在私信中，角色检查会扫描共同的服务器；在任意共享服务器中拥有允许角色的用户在私信中也被授权。

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

提及控制​

默认情况下，Hermes 会阻止机器人 ping @everyone、@here 和角色提及，即使其回复包含这些词元。这防止了措辞不当的提示词或用户内容中包含的词元向整个服务器发送通知。个别 @用户 ping 和回复引用 ping（"回复..." 小标签）保持启用，确保正常对话仍能工作。

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

# ~/.hermes/config.yaml
discord:
  allow_mentions:
    everyone: false      # 允许机器人 ping @everyone / @here
    roles: false         # 允许机器人 ping @角色 提及
    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 部署的更多信息，请参阅安全指南。