Discord Bot 接入 Hermes Agent 教程

1. 创建 Discord 应用和 Bot

进入 Discord Developer Portal，创建 Application，再在 Bot 页面添加机器人。Bot Token 只展示一次，复制后应立即保存到安全的环境变量。

export DISCORD_BOT_TOKEN="replace_with_discord_bot_token"

生产环境不要把 Token 写在前端页面、公开仓库或日志里。Discord Token 泄露后，任何人都可以控制你的 Bot。

2. Message Content Intent 是关键

Discord Bot 能否读取消息内容，取决于 Privileged Gateway Intents。对于 Agent 助手来说，通常至少需要开启 Message Content Intent，否则 Bot 只能收到事件，却看不到用户发了什么。

Intent	用途	是否常用
Server Members Intent	读取成员列表和成员事件	社区管理场景需要
Message Content Intent	读取消息文本内容	Agent 对话通常需要
Presence Intent	读取在线状态	一般不需要

常见问题：如果 Bot 能上线但不回复，第一优先级检查 Message Content Intent，其次检查频道权限。

3. 邀请 Bot 到服务器

OAuth2 URL Generator 中选择 bot 和必要权限，生成邀请链接。最小权限原则更安全：只给读取消息、发送消息、读取历史消息等必要权限。

Scopes:
  - bot
Permissions:
  - View Channels
  - Send Messages
  - Read Message History
  - Use Slash Commands

4. Hermes Gateway 配置

Discord Gateway 配置一般包含 Bot Token、允许服务器、允许频道和消息触发规则。

gateways:
  discord:
    enabled: true
    token: "${DISCORD_BOT_TOKEN}"
    allowed_guilds:
      - "123456789012345678"
    allowed_channels:
      - "234567890123456789"
    respond_when_mentioned: true

公开服务器建议只在指定频道启用 Agent，避免机器人在所有频道都参与对话，造成噪音和额度浪费。

Discord 接入常用工具

调试 Bot 时，最常遇到的是配置缩进、事件 JSON 和正则过滤规则。

JSON 格式化查看 Discord 事件结构 YAML 格式化检查 Gateway 配置正则表达式过滤触发消息 AI 提示词设计频道 Bot 角色

5. 频道内 Agent 的安全边界

Discord 服务器可能有多用户同时发言，Agent 的上下文和权限边界要比个人聊天更严格。建议设置三个边界：

只响应指定频道或被 @ 的消息。
禁止公开输出 Token、服务器路径和内部日志。
危险工具需要人工确认，不允许在公开频道直接执行。

6. 排错清单

Bot 离线：检查 Gateway 进程是否运行，Token 是否过期。
收不到消息：检查 Message Content Intent 和频道权限。
只能回复部分频道：检查频道覆盖权限和 allowed_channels。
回复太慢：先发送处理中状态，再等待 Agent 工具调用完成。