如何在 Discord 上部署 Hermes Agent（机器人 + 语音）

为什么要把 Hermes Agent 放进 Discord

如果你的项目、工作室或朋友们已经在某个 Discord 服务器里活动，那你的智能体也应该能在那里被找到。频道、语音房间和按角色分层的房间，都能给 Hermes 一个独立控制台无法提供的上下文：是谁在问、他在哪个频道、正在打字还是说话、答案应该出现在哪里。

Hermes Agent 提供了一流的 Discord 支持，同时覆盖服务器的文字与语音两侧。运行时通过标准的 Gateway WebSocket 主动向 Discord 建立连接，所以它可以跑在你的笔记本、一台小 VPS 上，甚至藏在家里的 NAT 后面，仍然可以实时收到消息。无需公开 webhook，也无需开放入站端口。同一个运行时既能回复文字消息，也能通过 /voice join 加入语音频道，用 STT 收音、再用 TTS 出声回答。

本指南会一口气讲完全部部署流程：创建 Discord 应用、生成机器人 token、启用 Discord 默默要求的 intents、配置白名单和主频道、用正确的 OAuth2 URL 把机器人拉进服务器，以及初次部署最容易踩到的坑。

开始之前你需要什么

一次干净的 Discord 部署需要准备好五样东西：

一个你有权限添加机器人的 Discord 服务器。如果不是你自己的，请找管理员协助，邀请 URL 只对目标服务器上具备"管理服务器"权限的人生效。
一个正在运行的 Hermes Agent 实例。Hermes Agent 的 Docker 指南是最干净的一条路；如果你用 Windows，WSL2 安装指南是等价方案。
一把模型服务商的 API 密钥。Anthropic、OpenAI、OpenRouter 或任何兼容 OpenAI 的接口都可以。运行时用它来真正回答消息。
你的 Discord 数字用户 ID，用于白名单（打开开发者模式 → 右键你的名字 → 复制用户 ID）。
第一次安装大约 15 分钟。之后的重新部署不到一分钟。

步骤 1 - 创建 Discord 应用与机器人

打开 Discord 开发者门户，点击 New Application，起个名字（比如 hermes-agent），并接受开发者条款。这会创建一个应用容器，用来存放机器人用户、OAuth2 凭据和 token。

从应用页面进入侧边栏的 Bot。Discord 现在不再要求在新应用里点 Add Bot，机器人用户会自动创建。你需要做的是给它一个显示名称、一个头像，如果你希望邀请 URL 只允许你自己使用，就把 Public Bot 关掉。

然后点击 Reset Token 显示机器人的 token。它长得像 MTA…。复制一次并直接粘进你的 .env，Discord 从此不会再展示给你看，只允许你重新生成。

请把这把 token 当作 SSH 密钥对待。谁拿到它就能以你的机器人身份行事、读遍机器人所在每个频道里的所有消息，并通过触发智能体来消耗你的模型服务商额度。

步骤 2 - 打开 Discord 强制要求的 Gateway Intents

这一步会静默毁掉大多数 Discord 机器人的部署。Discord 把"Discord 会推送给你的机器人什么"划分成若干 intents。其中一部分是特权 intents，你必须为每个应用显式打开，否则 Discord 依然会建立 WebSocket、下发事件，只是把你没申请的字段悄悄置空。

依旧在 Bot 页面里，向下找到 Privileged Gateway Intents 并启用：

Message Content Intent - 读消息文本的必需项。缺了它，Hermes 收到的消息事件正文永远是空的，机器人也就一直保持沉默。
Server Members Intent - 把白名单和真实成员 ID 对上，并能感知谁进谁出的必需项。
Presence Intent - 可选，如果你希望机器人对有人上线或加入语音频道作出反应，就打开它。

在页面底部点 Save Changes。这一步必须在开发者门户里完成，.env 里没有对应开关。

一旦你的机器人通过了验证并进入了 100 个以上服务器，Discord 会强制你申请这些 intents。在这个阈值以下，勾选开关就够了。

步骤 3 - 找到你的 Discord 数字用户 ID

Hermes Agent 只会回应 DISCORD_ALLOWED_USERS 里列出的 ID。它是整个部署里最重要的安全阀门，要求的是数字 ID，而不是 @handle。

在 Discord 中打开 用户设置 → 高级，把 开发者模式 打开。关掉设置后，在任意频道或成员列表里右键你的名字，选择 复制用户 ID。ID 长这样：284102345871466496。对每一位想授权的同伴各做一次。

跳过白名单等于把服务商密钥晾给整个服务器。如果一个可以从公开服务器访问到的 Hermes 实例白名单为空，机器人能读到的每一条消息都会消耗你的额度，在语音频道里，它能听到的每一点声音都会被转写。

步骤 4 - 配置 Hermes 运行时

打开 ~/.hermes/.env（或者你的容器实际读取的那个 .env），加入：

DISCORD_BOT_TOKEN=MTA...你的-bot-token...
DISCORD_ALLOWED_USERS=284102345871466496,297811223344556677
DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"

逐一说明：

DISCORD_BOT_TOKEN - 步骤 1 中复制的 token。
DISCORD_ALLOWED_USERS - 用逗号分隔的数字用户 ID 列表。机器人会忽略所有其他人，包括服务器管理员和其他机器人。
DISCORD_HOME_CHANNEL（可选）- 主动消息、计划任务输出和技能触发通知所使用的频道 ID。在 Discord 中右键频道 → 复制频道 ID。留空时，主动输出会发到机器人与第一个白名单用户的私聊里。
DISCORD_HOME_CHANNEL_NAME（可选）- 一个仅用于日志的人类可读标签，不影响路由。

保存后执行 chmod 600 ~/.hermes/.env。token 拥有对你机器人的完整权限，请像 SSH 密钥一样对待。

步骤 5 - 把机器人邀请到你的服务器

机器人不会主动加入服务器，需要通过一个 OAuth2 URL 邀请，并在 URL 里预先声明想要的 scope 和权限。Hermes 期望的组合是：

Scope：bot 与 applications.commands（后者会启用 /voice 斜杠命令）。
Permissions integer：274878286912，覆盖查看频道、发送消息、嵌入链接、附加文件、读取消息历史、在线程中发送消息以及添加反应。

在门户的 General Information 里拿到应用的 Client ID，套进下面这个模板：

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

打开 URL，选择你的服务器，确认权限，Discord 就会把机器人以成员身份放进去。如果你更喜欢勾选框，也可以在门户里通过 OAuth2 → URL Generator 生成一模一样的 URL。

如果要用语音，你还需要在你打算使用的那个语音频道上给机器人开启 连接 与 发言 权限。如果邀请之后这两项缺失，就给机器人加一个能授予它们的角色，或者直接在频道的权限覆盖里编辑。

步骤 6 - 启动 gateway 并发送第一条消息

重启 gateway 让它加载新的环境变量：

hermes gateway restart

或者用 Docker Compose：

docker compose restart gateway

跟踪日志，等待 Discord 的握手：

hermes gateway logs --follow

你要找的是按此顺序出现的两行：

discord: connecting to Gateway
discord: connected as 你的-bot-name#1234 (guilds: 1)

如果只看到第一行、后面什么都没有，说明 token 写错了或者已被重置。如果机器人连上了但在频道里始终不回复，那要么门户里的 Message Content Intent 没打开，要么你的 ID 没写进 DISCORD_ALLOWED_USERS。

上线之后，给它发一条 DM，或者在它能看到的频道里用 @ 提到它。Hermes 会在同一个会话中回复，记忆与技能上下文完整保留。从这里开始，Hermes 的所有能力，包括持久化记忆、计划任务和自定义技能，都和它在 Telegram 交付面上表现完全一致。

步骤 7 - 打开语音（可选，但很好玩）

Discord 的语音频道是 Hermes 的一等交付面。当机器人已经带着 连接 和 发言 权限进入服务器后，你自己进入某个语音频道，然后在任意机器人能看到的文字频道里输入：

/voice join

机器人会加入你当前所在的语音频道，通过你配置的 STT 服务商开始收音，并通过 TTS 出声回复。命令面如下：

/voice join - 加入你当前所在的语音频道。
/voice channel - /voice join 的别名。
/voice leave - 从语音频道断开。
/voice status - 报告语音模式是否开启、机器人当前在哪一个频道。

只有 DISCORD_ALLOWED_USERS 里列出的用户会被转写，其余人的音频会被忽略。当语音频道里还有没被你明确授权的人时，这一点尤其重要。若想为 Discord 的 Opus 流挑一套合适的 STT/TTS 组合，可参见 Hermes 语音模式概览作为下一步阅读。

最先咬到你的几个坑

大约五个错误就能解释几乎所有"Discord 设置坏了"的求助帖：

Message Content Intent 依然是关的。 机器人连上了、进了服务器，但对什么都不回复。Discord 不会给你警告。到门户里打开它，然后重启 gateway。

DISCORD_ALLOWED_USERS 是空的。 默认就是忽略所有人。这是刻意的安全默认值，但会让第一次上手却忘了添加自己 ID 的人以为机器人坏了。

邀请时权限选错了。 如果机器人看不到频道，或者没有 发送消息 权限，就算是授权用户对它说话它也会保持沉默。用 274878286912 这个 permissions integer 重新邀请，或者在 服务器设置 → 身份组里修正身份组。

某个具体频道缺少语音权限。 机器人在服务器级别有 连接 与 发言，但某个频道的权限覆盖把它们撤销了。Discord 会显示机器人"已连接"，但两个方向都不出音。检查该语音频道的权限标签页。

两个 gateway 进程指向同一个数据卷。 如果你在同一个 /data 目录上同时启动一个 Discord 模式的 gateway 和一个 Telegram 模式的 gateway，消息顺序和记忆写入会在几分钟内互相破坏。要同时使用两种交付面，就在 .env 里同时设置 DISCORD_* 与 TELEGRAM_* 段，让同一个 gateway 原生复用两个通道。

如果问题看起来像 Discord，症状却更像通用故障，Telegram 故障排查指南对底层 gateway 与服务商问题讲得更深，而且大多数问题与交付面无关。

Discord 与 Telegram 对照

关注点	Discord	Telegram
部署耗时	15 分钟（应用 + intents + 邀请）	5 分钟（一个 BotFather token）
可达性	防火墙后（Gateway WebSocket）	防火墙后（long-poll）
白名单字段	`DISCORD_ALLOWED_USERS`（数字 ID）	`TELEGRAM_ALLOWED_USERS`（数字 ID）
最适合	社区、语音房间、项目服务器	个人使用、移动优先、语音便条
线程	原生（频道 + 线程）	只有引用回复
语音	加入语音频道，实时 STT/TTS	语音便条、转写回复

两种交付面并不互斥。同一个 Hermes 运行时可以同时服务两者，特别适合个人 Telegram 聊天和共享 Discord 语音房间共用同一份持久化记忆的场景。

跳过 Discord 的管道工作

单看步骤并不难，但主机的所有权仍在你手上：备份、控制台 TLS、日志轮转、升级节奏都要你管。个人级安装尚可，但如果一个服务器希望机器人几分钟就能上线，之后不再有运维负担，那么 Hermify 会为你在 Telegram 上提供一个托管的 Hermes 运行时，保持持久化记忆稳定，并在你不动 .env 的情况下自动轮换 token。

你提供模型服务商密钥和想要的交付面；平台负责下面的一切。如果你正在你自己的 VPS 之前评估这份取舍，自托管与托管的对比会带你走一遍成本与维护数字。