Discord 接入——社区服务器里的 AI 助手

把 Hermes Agent 接进你的 Discord 服务器，等于给社区请了一位 24 小时在线的 AI 助手。它不仅能陪你私聊，还能在频道里回答问题、处理文件、听语音消息，甚至支持斜杠命令。今天我们就一步步把它请进服务器。

它在你服务器里会怎么表现？

先搞清楚 Hermes 的“性格”，免得它乱说话：

私聊（DM）：每条消息都回，不用 @它，而且每个私聊都有独立的会话记忆。
普通频道：默认只有你 @它才回应，不 @ 就装看不见。
自由响应频道：如果你想让某个频道不用 @ 也能聊，把它加进 DISCORD_FREE_RESPONSE_CHANNELS 环境变量就行（也可以用 DISCORD_REQUIRE_MENTION=false 全局关掉 @ 要求）。这种频道里 Hermes 默认直接内联回复，不建线程，保持频道轻快。想让每条顶层消息都自动开一个线程、同时又不要求 @，就把 discord.free_response_auto_thread 设成 true。
线程：会在原线程里回复，会话历史跟主频道隔离。
多人共用的频道：默认每个用户有独立的会话历史，Alice 和 Bob 在同一个频道里跟 Hermes 聊天，彼此互不干扰。

小提示：想开一个“机器人帮助频道”，让大家不用 @ 就能问问题？把那个频道加进 DISCORD_FREE_RESPONSE_CHANNELS 就搞定了。

还有一个贴心设定：如果一条消息 @ 了别人但没 @ Hermes，它默认会保持沉默（DISCORD_IGNORE_NO_MENTION=true），不会插嘴别人的对话。

背后的会话模型

Hermes 在 Discord 里不是简单的“收到消息就回复”，而是走完整的消息网关：授权检查 → 提及/自由响应判断 → 会话查找 → 加载历史 → 执行智能体逻辑（工具、记忆、斜杠命令）→ 回复。

默认情况下，每个私聊、每个线程、每个用户在共享频道里都有自己的独立会话。这个行为由 config.yaml 控制：

group_sessions_per_user: true

如果你想要整个房间共享一个对话（适合协作场景），改成：

group_sessions_per_user: false

但要注意：共享会话意味着大家共享上下文和 token 消耗，一个人跑个耗时任务可能会拖慢所有人。

并发与中断

默认模式下，Alice 中断自己的请求只影响她自己，Bob 可以继续在同一个频道聊天，互不干扰。但如果关闭了按用户隔离，整个频道共享一个运行槽位，不同人的消息就可能互相打断或排队。

连接健康监控

新版增加了 WebSocket 健康检查——REST 接口正常不代表网关连接正常。Hermes 会综合判断连接状态、心跳 ACK 年龄、延迟，以及距离上一条解析到的网关事件过了多久，连续异常后自动重连。其中传输层已经关闭（socket_closed / client_closed）属于确认死亡，第一次采样就会强制重连；而阈值只作用于软信号（心跳 ACK 过期、延迟、事件静默）。你可以在 config.yaml 里调整阈值：

discord:
  websocket_liveness_interval_seconds: 15
  websocket_liveness_failure_threshold: 2
  websocket_heartbeat_ack_max_age_seconds: 60
  websocket_max_latency_seconds: 30
  websocket_event_max_silence_seconds: 14400

最后那个 websocket_event_max_silence_seconds 专门盯着“事件派发”这一项：连接可能一直 ESTABLISHED、心跳也照常 ACK，却一条事件都不发，光看传输层是发现不了的。默认 4 小时，安静的服务器本来就可能几小时没事件，所以别调太小。注意它是唯一例外：设成 0 只关掉这一项检查，ready/ACK/延迟仍然照常守护；其他项设成 0 才会关掉整个 WebSocket 探活，解析不出正数的值（比如 15s、nan、true、-1）也一样会关掉并打警告——探活没生效就去翻 gateway.log。

第一步：创建 Discord 应用

打开 Discord Developer Portal 并登录。
点右上角 New Application，给它起个名字（比如 “Hermes Agent”）。
同意条款，点 Create。

记下 Application ID，后面拼邀请链接要用。

第二步：创建机器人

左侧菜单点 Bot。
Discord 会自动创建一个机器人用户，你可以改它的名字。
在 Authorization Flow 里，把 Public Bot 打开——这样才能用 Discord 提供的邀请链接。

第三步：打开 Message Content Intent（最关键的一步）

这是整个配置里最容易翻车的地方。Hermes 需要读取消息内容，所以必须让 Discord 允许它这么做：

还在 Bot 页面，往下滚到 Privileged Gateway Intents。
把 Message Content Intent 打开。
点 Save Changes。

如果这个开关是关的，Discord 会直接拒绝机器人的连接，机器人永远上不了线，gateway.log 里会看到类似 “Discord rejected the connection because privileged Gateway Intents are not enabled” 的报错。遇到这种情况，回到 Developer Portal 把它打开、保存，再重启网关就行。

第四步：生成邀请链接，把机器人拉进服务器

在 OAuth2 → URL Generator 里勾选 bot 和 applications.commands 两个 scope，再按下面的表格勾权限，就能拿到邀请链接。也可以直接用这条现成的（把 YOUR_APP_ID 换成你的 Application ID）：

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

权限怎么选，看这张表：

档位	权限值	包含什么
最小	`117760`	View Channels、Send Messages、Embed Links、Attach Files、Read Message History
推荐	`309237763136`	上面全部，外加 Create Public Threads、Send Messages in Threads、Add Reactions
完整（`hermes gateway setup` 打印的就是这个）	`309240908864`	推荐档，外加 Connect 和 Speak（语音频道）

注意：已经装好的机器人不会自动获得新加的权限。如果你之前用的是旧的推荐链接，需要用上面的链接重新邀请一次机器人，才能拿到 Create Public Threads（/thread 命令和自动开线程都靠它）。

第五步：配置环境变量

把机器人的 token 和允许使用的人填进环境变量：

变量	是否必填	说明
`DISCORD_ALLOWED_USERS`	视情况	允许跟机器人互动的 Discord 用户 ID，逗号分隔。如果这个和 `DISCORD_ALLOWED_ROLES` 都没设，网关默认拒绝所有用户，除非你设了 `DISCORD_ALLOW_ALL_USERS=true`、`GATEWAY_ALLOW_ALL_USERS=true`，或者用 `DISCORD_ALLOWED_CHANNELS` 明确限定服务器访问范围。用户名也可以写，机器人连接时会自动解析成 ID（需要 Server Members Intent）。显示名和服务器昵称永远不匹配，因为任何人都能改。

偷懒捷径：让向导帮你搞定第五到第七步

如果你不想手动折腾，有个更省事的办法：先把应用建好、token 复制出来（也就是上面第一到第四步），然后运行

hermes gateway setup

在提示里选 Discord。向导会帮你把 token 拿去 Discord 验证（错的或过期的 token 会在保存前就被拒绝），检查 Message Content Intent 有没有打开（没开会告诉你，还直接给你跳到开关的链接），打印一条现成的邀请链接，并且顺手把你自己加进机器人的 owner 白名单——全程不用开开发者模式。想再加人，用用户 ID 或用户名都行。

斜杠命令与交互按钮

Hermes 支持斜杠命令，比如 /thread 用来开一个隔离的对话线程。当机器人抛出需要你选择的交互按钮时，一旦你点了某个选项，按钮就会自己禁用，避免手抖连点导致重复响应。响应超时时间可以在 ~/.hermes/config.yaml 里用 agent.clarify_timeout 调整（默认 3600 秒，设成 0 或负数表示不限时）。超时没回应的话，智能体会以 "outcome": "timed_out" 解除阻塞并继续往下走，不会一直卡着。想跳过某个问题，直接回复 skip 就行。

常见问题排查

机器人一直离线，gateway.log 里提到 privileged Gateway Intents：说明 Message Content Intent 没开。回到 Developer Portal，选中你的应用 → Bot → Privileged Gateway Intents，把 Message Content Intent 打开，点 Save Changes。

机器人上线了但谁说话都不理：通常是没配访问策略，Discord 认证默认“失败即拒绝”。检查一下 DISCORD_ALLOWED_USERS 或 DISCORD_ALLOWED_ROLES 是不是空的。（如果机器人压根没上线，那是 Message Content Intent 的问题，见上面第三步。）

/thread 报 Discord 错误 50001（Missing Access）：去父频道里确认机器人的实际权限。它需要 View Channel、Send Messages、Create Public Threads 和 Send Messages in Threads。别忘了也检查一下父分类和频道级别的权限覆盖——那里的一条显式拒绝，会盖掉服务器角色给的权限。

接下来就是拿邀请链接把机器人拉进你的服务器，然后配置好环境变量，你的社区 AI 助手就正式上岗了！