跳到主要内容

Discord 设置

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

在设置之前，这是大多数人都想知道的部分：Hermes 加入你的服务器后的行为。

Hermes 的行为​

上下文行为
DMHermes 响应每条消息。无需 @mention。每个 DM 有自己的会话。
服务器频道默认情况下，Hermes 只在你 @mention 它时响应。如果你在没有提及它的情况下发布到频道，Hermes 会忽略该消息。
自由响应频道你可以用 DISCORD_FREE_RESPONSE_CHANNELS 使特定频道无需提及，或用 DISCORD_REQUIRE_MENTION=false 全局禁用提及。
线程Hermes 在同一线程中回复。线程规则仍然适用，除非该线程或其父频道配置为自由响应。线程与会话历史的父频道隔离。
与多个用户共享频道默认情况下，Hermes 在频道内按用户隔离会话历史以确保安全和清晰。两个人在同一频道中与 Hermes 交谈不会共享一个记录，除非你明确禁用它。
提及其他用户的消息当 DISCORD_IGNORE_NO_MENTION 为 true（默认）时，如果消息 @mention 其他用户但没有提及机器人，Hermes 保持沉默。这防止机器人在针对其他人的对话中跳跃。如果设置为 false，则希望机器人在提及所有消息时都响应。这仅适用于服务器频道，不适用于 DM。
提示

如果你想要一个正常的机器人帮助频道，让人们每次都标记它与 Hermes 交谈，将该频道添加到 DISCORD_FREE_RESPONSE_CHANNELS。

Discord Gateway 模型​

Discord 上的 Hermes 不是无状态回复的 Webhook。它通过完整的消息网关运行，这意味着每条传入消息都经过：

  1. 授权（DISCORD_ALLOWED_USERS）
  2. 提及/自由响应检查
  3. 会话查找
  4. 会话记录加载
  5. 正常 Hermes 代理执行，包括工具、记忆和斜杠命令
  6. 响应传递回 Discord

这很重要，因为在繁忙服务器中的行为取决于 Discord 路由和 Hermes 会话策略。

Discord 中的会话模型​

默认情况下：

  • 每个 DM 有自己的会话
  • 每个服务器线程有自己的会话命名空间
  • 共享频道中的每个用户在频道内有自己的会话

所以如果 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 只中断她自己在该频道中的进行中请求只会影响 Alice 的会话
  • Bob 可以在同一频道中继续交谈而不继承 Alice 的历史或中断 Alice 的运行

group_sessions_per_user: false：

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

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

步骤 1：创建 Discord 应用程序​

  1. 进入 Discord Developer Portal 并用你的 Discord 账户登录。
  2. 点击右上角的 New Application。
  3. 输入应用程序名称（例如"Hermes Agent"）并接受开发者服务条款。
  4. 点击 Create。

你将进入常规信息页面。注意Application ID——你稍后需要用它来构建邀请 URL。

步骤 2：创建机器人​

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

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

私人机器人替代方案

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

步骤 3：启用特权 Gateway Intents​

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

在 Bot 页面，向下滚动到 Privileged Gateway Intents。你会看到三个切换：

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

启用 Server Members Intent 和 Message Content Intent 都切换到 ON。

  • 没有 Message Content Intent，你的机器人接收消息事件但消息文本为空——机器人实际上看不到你输入的内容。
  • 没有 Server Members Intent，机器人无法为允许用户列表解析用户名，可能无法识别谁在给它发消息。
这是 Discord 机器人不工作的 #1 原因

如果你的机器人在线但从不响应消息，Message Content Intent 几乎肯定被禁用了。返回 Developer Portal，选择你的应用程序 → Bot → Privileged Gateway Intents，并确保 Message Content Intent 切换到 ON。点击 Save Changes。

关于服务器计数：

  • 如果你的机器人在 少于 100 个服务器中，你可以自由切换 Intents。
  • 如果你的机器人在 100 个或更多服务器中，Discord 要求你提交验证申请以使用特权 Intents。对于个人使用，这不是问题。

点击页面底部的 Save Changes。

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

机器人令牌是 Hermes Agent 用来登录为你的机器人的凭证。仍在 Bot 页面：

  1. 在 Token 部分，点击 Reset Token。
  2. 如果你在 Discord 账户上启用了两步验证，输入你的 2FA 代码。
  3. Discord 将显示你的新令牌。立即复制。
令牌只显示一次

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

将令牌保存在安全的地方（例如密码管理器）。你需要在步骤 8 中使用它。

步骤 5：生成邀请 URL​

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

选项 A：使用安装选项卡（推荐）​

需要 Public Bot

此方法需要在步骤 2 中将 Public Bot 设置为 ON。如果你将 Public Bot 设置为 OFF，请改用下面的 Manual 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：Manual URL​

你可以直接使用此格式构建邀请 URL：

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

将 YOUR_APP_ID 替换为步骤 1 中的 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

步骤 6：邀请到你的服务器​

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

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

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

步骤 7：找到你的 Discord 用户 ID​

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

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

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

提示

开发者模式还允许你以相同方式复制频道 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 中并上线。给它发送消息——无论是 DM 还是它能看到频道——来测试。

提示

你可以 hermes gateway 在后台运行或作为 systemd 服务以持久运行。参阅部署文档了解详细信息。

配置参考​

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

环境变量（.env）​

变量必需默认描述
DISCORD_BOT_TOKEN是—来自 Discord Developer Portal 的机器人令牌。
DISCORD_ALLOWED_USERS是—允许与机器人交互的逗号分隔的 Discord 用户 ID。没有这个，网关拒绝所有用户。
DISCORD_HOME_CHANNEL否—机器人发送主动消息（cron 输出、提醒、通知）的频道 ID。
DISCORD_HOME_CHANNEL_NAME否"Home"日志和状态输出中主频道的显示名称。
DISCORD_REQUIRE_MENTION否true当为 true 时，机器人在服务器频道中仅在被 @mention 时响应。设置为 false 以响应每个频道中的所有消息。
DISCORD_FREE_RESPONSE_CHANNELS否—逗号分隔的频道 ID，机器人在其中无需 @mention 即可响应，即使 DISCORD_REQUIRE_MENTION 为 true。
DISCORD_IGNORE_NO_MENTION否true当为 true 时，如果消息 @mention 其他用户但没有提及机器人，机器人保持沉默。防止机器人在针对其他人的对话中跳跃。仅适用于服务器频道，不适用于 DM。
DISCORD_AUTO_THREAD否true当为 true 时，在文本频道中每次 @mention 自动创建新线程，以便每个对话隔离（类似于 Slack 行为）。已经在线程中或 DM 中发送的消息不受影响。
DISCORD_ALLOW_BOTS否"none"控制机器人如何处理来自其他 Discord 机器人的消息。"none" — 忽略所有其他机器人。"mentions" — 仅接受 @mention Hermes 的机器人消息。"all" — 接受所有机器人消息。
DISCORD_REACTIONS否true当为 true 时，机器人在处理过程中向消息添加表情符号反应（👀 开始时，✅ 成功时，❌ 错误时）。设置为 false 完全禁用反应。
DISCORD_IGNORED_CHANNELS否—机器人绝不响应的逗号分隔的频道 ID，即使被 @mention。这优先于所有其他频道设置。
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 特定设置
discord:
  require_mention: true           # 在服务器频道中需要 @mention
  free_response_channels: ""      # 逗号分隔的频道 ID（或 YAML 列表）
  auto_thread: true               # 在 @mention 时自动创建线程
  reactions: true                 # 在处理过程中添加表情符号反应
  ignored_channels: []            # 机器人绝不响应的频道 ID
  no_thread_channels: []          # 机器人不通过线程响应的频道 ID

# 会话隔离（适用于所有网关平台，而不仅仅是 Discord）
group_sessions_per_user: true     # 在共享频道中按用户隔离会话

discord.require_mention​

类型： boolean — 默认： true

启用后，机器人在服务器频道中仅在被直接 @mention 时响应。DM 始终获得响应，无论此设置如何。

discord.free_response_channels​

类型： string or list — 默认： ""

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

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

# 列表格式
discord:
  free_response_channels:
    - 1234567890
    - 9876543210

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

discord.auto_thread​

类型： boolean — 默认： true

启用后，常规文本频道中每次 @mention 自动为对话创建新线程。这保持主频道整洁，并给每个对话自己的隔离会话历史。一旦线程创建，该线程中的后续消息不需要 @mention — 机器人知道它已经参与。

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

discord.reactions​

类型： boolean — 默认： true

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

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

如果你发现反应分散注意力或机器人的角色没有添加反应权限，请禁用。

discord.ignored_channels​

类型： string or list — 默认： []

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

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

# 列表格式
discord:
  ignored_channels:
    - 1234567890
    - 9876543210

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

discord.no_thread_channels​

类型： string or list — 默认： []

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

discord:
  no_thread_channels:
    - 1234567890  # 机器人在此内联响应

适用于专门用于机器人交互的频道，在这些频道中线程会增加不必要的噪音。

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

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

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

display.tool_progress_command​

类型： boolean — 默认： false

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

display:
  tool_progress_command: true

交互式模型选择器​

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

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

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

用于技能的本机斜杠命令​

Hermes 自动将已安装的技能注册为原生 Discord Application Commands。这意味着技能出现在 Discord 的自动完成 / 菜单中，与内置命令一起。

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

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

主频道​

你可以指定一个"主频道"，机器人发送主动消息（cron 作业输出、提醒和通知）。有两种方法设置：

使用斜杠命令​

在机器人存在的任何 Discord 频道中输入 /sethome。该频道成为主频道。

手动配置​

将这些添加到你的 ~/.hermes/.env：

DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"

将 ID 替换为实际频道 ID（打开开发者模式后右键 → Copy Channel 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 被禁用。

修复：进入 Developer Portal → 你的应用 → Bot → Privileged Gateway Intents → 启用 Message Content Intent → Save Changes。重启网关。

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

原因：你的代码请求未在 Developer Portal 中启用的 Intents。

修复：在 Bot 设置中启用所有三个 Privileged Gateway Intents（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。如果你最近重置了令牌，请更新。

"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 以限制谁可以与机器人交互。没有它，网关默认拒绝所有用户作为安全措施。只添加你信任的人的用户 ID — 授权用户可以完全访问代理的功能，包括工具使用和系统访问。

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