Discord 配置指南
本指南将带你从零开始创建 Discord 机器人、配置权限，并将其连接到 Elftia，让 AI Agent 在你的 Discord 服务器中工作。
前置准备
- 一个 Discord 账号
- 你拥有管理权限的 Discord 服务器（或新建一个测试服务器）
- Elftia 已安装并至少配置了一个 LLM 提供商
第一步：创建 Discord 应用
- 打开 Discord Developer Portal
- 点击右上角 New Application
- 输入应用名称（例如
Elftia Bot），点击 Create - 在左侧菜单中点击 Bot
- 记录下页面中显示的 Bot 用户名
第二步：获取 Bot Token
- 在 Bot 页面中，找到 Token 区域
- 点击 Reset Token（如果是首次创建，会直接显示 Token）
- 复制 Token 并妥善保存
:::danger 安全警告 Bot Token 相当于机器人的密码，切勿将其公开分享或提交到代码仓库。如果 Token 泄露，请立即在 Developer Portal 中重置。 :::
第三步：配置 Bot 权限
在 Bot 页面中，找到 Privileged Gateway Intents 区域，启用以下两个选项：
- MESSAGE CONTENT INTENT — 允许机器人读取消息内容（必须启用）
- SERVER MEMBERS INTENT — 允许获取服务器成员信息（推荐启用）
点击页面底部的 Save Changes 保存。
:::info 为什么需要 Message Content Intent？ 从 2022 年起，Discord 要求所有机器人必须显式启用 Message Content Intent 才能读取消息内容。如果不启用，机器人只能收到空消息。 :::
第四步：生成邀请链接
- 在左侧菜单中点击 OAuth2 → URL Generator
- 在 SCOPES 中勾选
bot - 在 BOT PERMISSIONS 中勾选以下权限：
| 权限 | 说明 |
|---|---|
| Send Messages | 发送消息 |
| Read Message History | 读取历史消息 |
| View Channels | 查看频道 |
| Embed Links | 发送嵌入式链接 |
| Attach Files | 发送文件附件 |
| Add Reactions | 添加表情反应 |
| Use External Emojis | 使用外部表情 |
- 复制页面底部生成的 GENERATED URL
第五步：邀请机器人到服务器
- 在浏览器中打开上一步复制的邀请链接
- 选择目标服务器（你必须拥有该服务器的 管理服务器 权限）
- 确认权限列表
- 点击 授权，完成人机验证
邀请成功后，你可以在服务器的成员列表中看到机器人（显示为离线状态，因为还未连接）。
第六步：在 Elftia 中配置
- 打开 Elftia，进入 设置 → Channel
- 点击 添加渠道
- 选择 Discord（如果插件未安装，会自动从 Marketplace 下载）
- 在配置表单中填写：
| 字段 | 值 |
|---|---|
| 显示名称 | 为此实例起一个名字（如 我的 Discord Bot） |
| Bot Token | 粘贴第二步获取的 Token |
- 点击 测试连接 验证 Token 是否有效
- 点击 保存 创建 Channel 实例
第七步：配置触发规则
创建实例后，建议先配置合适的触发规则：
| 模式 | 推荐场景 | 设置说明 |
|---|---|---|
mention | 多人服务器 | Agent 仅在被 @提及 时回复。设置 mentionName 为机器人的用户名 |
all | 专属/测试服务器 | Agent 回复所有消息，适合个人使用 |
keyword | 特定话题频道 | 设置触发关键词列表，大小写不敏感 |
dm_only | 公开服务器 | Agent 只回复私信，群组中完全沉默 |
在 Channel 设置中选择触发模式并配置相应参数。
第八步：启动连接
- 在 Channel 页面中找到刚创建的 Discord 实例
- 点击 连接 按钮（或开启 自动连接）
- 等待状态变为 已连接（绿色指示器）
- 在 Discord 中向机器人发送一条消息进行测试
如果使用 mention 模式，记得在消息中 @提及 机器人：
@Elftia Bot 你好，请介绍一下自己
Discord 平台特性
| 特性 | 支持状态 |
|---|---|
| 群组聊天 | 支持 |
| 私信 (DM) | 支持 |
| 附件/文件发送 | 支持 |
| 打字指示器 | 支持 |
| 表情反应 | 支持 |
| 帖子/论坛 | 部分支持 |
| 消息长度限制 | 2,000 字符 |
当 Agent 回复超过 2,000 字符时，系统会自动将消息拆分为多条发送。拆分优先在换行符处断开，其次在空格处断开，最后才硬切。
常见问题
机器人显示离线
- 检查 Elftia 中 Channel 实例的状态是否为「已连接」
- 确认 Bot Token 正确无误
- 确认 Elftia 应用正在运行（Channel 插件在主进程中运行，关闭应用则机器人离线）
机器人在线但不回复
- 检查触发规则配置是否正确。如果使用
mention模式，确保mentionName与机器人实际用户名一致 - 确认 MESSAGE CONTENT INTENT 已在 Developer Portal 中启用
- 查看 Elftia 日志中是否有安全管线拦截的记录（RateLimiter、PromptGuardian 等）
- 确认 Agent 已正确配置 LLM 提供商和模型
消息被截断
Discord 单条消息上限为 2,000 字符。如果 Agent 回复过长，系统会自动分片发送。如果看到回复不完整，请检查是否有后续消息。
权限错误 (Missing Permissions)
- 确认机器人在目标频道中具有 Send Messages 和 View Channel 权限
- 检查服务器角色设置中是否有覆盖规则限制了机器人的权限
- 在 Developer Portal 中重新生成邀请链接，确保勾选了必要的权限
多个 Discord 实例
你可以在 Elftia 中创建多个 Discord Channel 实例，每个实例使用不同的 Bot Token，连接到不同的服务器。每个实例可以配置独立的触发规则和安全策略。