前言

之前研究了飞书、WhatsApp、Telegram等渠道的集成。发现都不是很满意：

  • 飞书

    ：接口限额，调用频率受限

  • WhatsApp

    ：各种格式支持有限，消息类型受限

  • Telegram

    ：体验还算可以，但功能相对简单

试了下 Discord，发现它有很多优势：

  • ✅ 支持格式多（文本、图片、视频、文件等）

  • ✅ 支持 Markdown 格式

  • ✅ 可以在群聊、频道、私聊场景中使用机器人，可用于多Agent

  • ✅ 支持斜杠命令（Slash Commands）

  • ✅ 支持丰富的 Embed 消息格式

  • ✅ API 调用限额合理，适合生产环境

![[image-20260205102413692.png]]

下面详细介绍从零到一的集成步骤。

📋 准备工作

在开始之前，请确保你已经：

  • ✅ 拥有一个 Discord 账号（如果没有，请先注册：https://discord.com/）

  • ✅ 已安装 Node.js 环境（建议 v22+）

  • ✅ 已安装 OpenClaw 或 Clawdbot

  • ✅ 必须有梯子, 需要开启 TUN 模式 或全局代理

第一步：创建 Discord 应用和机器人

1.1 访问 Discord 开发者门户

  1. 打开浏览器，访问：https://discord.com/developers/applications

  2. 如果未登录，会提示你登录 Discord 账号

  3. 登录后，点击右上角的 “New Application” 按钮

1.2 创建应用

  1. 在弹出的对话框中，给你的应用命名（例如：OpenClaw Bot 或 MyBot）

  2. 点击 “Create” 按钮创建应用

  3. 应用创建后，会进入应用概览页面

提示：

  • 应用名称可以后续修改

  • 可以上传应用图标（推荐上传）

  • 填写应用描述（可选）

1.3 创建机器人

  1. 在左侧菜单中，点击 “Bot” 选项

  2. 在页面右侧，点击 “Add Bot” 按钮

  3. 确认对话框中点击 “Yes, do it!”

1.4 配置机器人权限（⚠️ 重要步骤）

在 Bot 页面中，找到 “Privileged Gateway Intents” 部分，必须开启以下权限：

权限名称

说明

是否必需

✅ MESSAGE CONTENT INTENT

用于读取消息内容

 必需

✅ SERVER MEMBERS INTENT

用于成员相关功能

可选

✅ PRESENCE INTENT

用于在线状态功能

可选

特别注意：

  • MESSAGE CONTENT INTENT

     是必需的，否则机器人无法读取消息内容

  • 这些权限开启后，机器人可以访问更丰富的消息数据

1.5 获取机器人 Token

  1. 在 Bot 页面的 “Build-A-Bot” 部分，点击 “Reset Token” 按钮

  2. 在确认对话框中点击 “Yes, do it!”

  3. 重要

    ：Token 只会显示一次，请立即复制并妥善保存！

  4. Token 格式示例：

    1. MTQ2NjY0MzE3OTA4NzU5MzU0NQ.Gc4idi.04PM1TqFYnOyW9IJyzyX-Rz4VMQakql_gVeY0k

安全提示：

  • ⚠️ Token 相当于机器人的密码，绝对不能分享给他人

  • ⚠️ 不要将 Token 提交到公开代码仓库（如 GitHub）

  • ⚠️ 如果 Token 泄露，立即点击 “Reset Token” 重新生成

1.6 配置 OAuth2 权限

这一步用于生成邀请机器人到服务器的链接。

  1. 在左侧菜单中，点击 “OAuth2” → “URL Generator”

  2. 在 “Scopes” 部分，勾选以下选项：

  • ✅ bot - 机器人身份

  • ✅ applications.commands - 斜杠命令权限

  • 在 “Bot Permissions” 部分，勾选以下权限：

    • ✅ Read Messages/View Channels - 读取消息

    • ✅ Send Messages - 发送消息

    • ✅ Embed Links - 发送富文本链接

    • ✅ Attach Files - 发送文件

    • ✅ Use Slash Commands - 使用斜杠命令

    • ✅ Read Message History - 读取消息历史（可选）

    • ✅ Mention Everyone - @所有人权限（谨慎使用）

    • ✅ Add Reactions - 添加 Emoji 反应（推荐，用于点赞、标记等）

  • 复制生成的 URL（页面底部的 “Generated URL” 部分）

  • 1.7 邀请机器人到服务器

    1. 将复制的 URL 粘贴到浏览器中打开

    2. 在下拉菜单中选择要添加机器人的服务器（如果没有，可以创建一个新服务器）

    3. 点击 “授权” 按钮

    4. 确认授权后，机器人就会被添加到服务器

    验证：

    • 打开 Discord 客户端，进入你的服务器

    • 在右侧成员列表中应该能看到机器人（状态通常是离线）

    • 机器人的名称后面会有 “BOT” 标识

    获取 ID（服务器/用户/频道）：

    Discord 到处使用数字 ID；OpenClaw 配置优先使用 ID。

    1. Discord（桌面/网页）→ 用户设置 → 高级 → 启用 开发者模式

    2. 右键点击：

    • 服务器名称 → 复制服务器 ID（服务器 ID）

    • 频道（例如 #help）→ 复制频道 ID

    • 你的用户 → 复制用户 ID

    第二步：配置 Discord 通道

    3.1 定位配置文件

    OpenClaw/Clawdbot 的配置文件通常位于：

    • Linux/Mac: ~/.openclaw/openclaw.json

    • Windows: C:\Users\你的用户名\.openclaw\openclaw.json

    3.2 编辑配置文件

    使用你喜欢的编辑器打开配置文件，添加 Discord 通道配置：

    基础配置（最小可用配置）：

    {"plugins":{"entries":{"discord":{"enabled":true}}},"channels":{"discord":{"token":"你的Discord机器人Token","enabled":true}}}

    第四步：启动/重启 OpenClaw 网关

    4.1 重启网关

    配置文件修改后，需要重启网关使配置生效：

    clawdbot gateway restart

    4.2 检查网关状态

    查看网关是否正常运行：

    clawdbot gateway status

    4.3 查看日志（如果需要）

    如果遇到问题，可以查看详细日志：

    clawdbot logs

    或者查看 Discord 插件相关日志：

    clawdbot logs --filter discord

    4.4 自动热重载（可选）

    如果你的 OpenClaw 配置了文件监视，配置文件修改后会自动重载。这种方式无需手动重启。

    配置方法（在 openclaw.json 中）：

    {"watchConfig":true}

    第五步：测试与验证

    5.1 检查机器人在线状态

    1. 打开 Discord 客户端

    2. 进入你添加机器人的服务器

    3. 在右侧成员列表中查看机器人状态

    • ✅ 机器人显示为 在线（绿色圆点）- 表示连接成功

    • ❌ 机器人显示为 离线（灰色圆点）- 表示连接失败

    5.2 群组消息测试

    在服务器频道中发送消息：

    Hello, bot!

    期望结果：

    • 机器人应该能够读取到消息（如果配置正确）

    • 根据你的 OpenClaw 配置，机器人可能会有响应

    5.3 私聊测试（如果配置了 dmPolicy: “pairing” 或 “open”）

    1. 在 Discord 中找到机器人（在成员列表）

    2. 右键点击机器人，选择 “Message”

    3. 发送测试消息：或

      1. 你好，机器人
      1. /ping

    注意：

    • 如果使用 pairing 模式，可能需要先进行配对流程

    • 配对方法取决于 OpenClaw 的具体实现

    5.4 斜杠命令测试

    1. 在任意频道中，输入 / 键

    2. 应该能看到机器人提供的命令列表

    3. 常见的默认命令：

    • /ping

       - 检查机器人状态

    • /help

       - 获取帮助信息

    • /status

       - 查看机器人状态

    5.5 富文本消息测试

    测试机器人是否支持富文本格式：

    Markdown 测试：

    **粗体文本***斜体文本*`代码文本`[链接文本](https://example.com)

    Embed 测试：
    如果机器人配置了 Embed 消息，应该能看到格式化的消息卡片。

    5.6 验证清单

    使用以下清单确认所有功能正常：

    测试项

    状态

    备注

    机器人在线显示

    ☐ / ☐

    检查 Discord 客户端

    群组消息读取

    ☐ / ☐

    在频道发送消息

    群组消息发送

    ☐ / ☐

    检查机器人是否回复

    私聊功能

    ☐ / ☐

    如果启用了私信

    斜杠命令

    ☐ / ☐

    输入 / 查看命令

    Markdown 格式

    ☐ / ☐

    发送格式化文本

    文件附件

    ☐ / ☐

    上传文件测试

    Emoji 反应

    ☐ / ☐

    对消息添加 Emoji

    第六步：常见问题排查

    6.1 机器人不在线

    症状：机器人在 Discord 中显示为离线状态

    可能原因及解决方案：

    1. Token 错误

    • 检查 Token 是否正确复制（注意不要有多余空格）

    • 重新生成 Token（开发者门户 → Bot → Reset Token）

    • 确认 Token 在配置文件中格式正确（不要有引号问题）

  • 网络问题

    • 检查服务器网络连接，确保服务器或本地环境可以正常访问 Discord API。如果使用了代理软件（如 Clash、V2Ray 等），需要开启 TUN 模式 或全局代理

    • 确认防火墙没有阻止 Discord API 连接

    • 尝试重启网关：clawdbot gateway restart

  • 网关未运行

    • 检查网关状态：clawdbot gateway status

    • 如果未运行，启动网关：clawdbot gateway start

  • 查看日志

    查找错误信息，如：

    • “Invalid token”

    • “Connection refused”

    • “Timeout”

    1. clawdbot logs --tail 50--filter discord

    6.2 无法读取消息

    症状：机器人在线，但无法读取或响应消息

    解决方案：

    1. 检查 MESSAGE CONTENT INTENT

    • 回到 Discord 开发者门户

    • 进入应用 → Bot

    • 确保 MESSAGE CONTENT INTENT 已勾选

    • 保存后重启网关

  • 检查频道权限

    • 在 Discord 服务器中，点击服务器名称 → Server Settings → Roles

    • 找到机器人的角色

    • 确保有 “Read Messages” 和 “Read Message History” 权限

  • 检查机器人权限

    • 进入 Discord 开发者门户

    • 重新生成 OAuth2 URL（确保勾选了正确权限）

    • 重新邀请机器人到服务器

    6.3 Token 泄露

    症状：Token 被泄露或怀疑泄露

    紧急处理步骤：

    1. 立即重置 Token

    • 进入 Discord 开发者门户

    • Bot → Reset Token

    • 复制新 Token

  • 更新配置文件

    • 使用新 Token 更新配置文件

    • 重启网关

  • 检查异常活动

    • 查看机器人日志，查找异常活动

    • 考虑启用更多安全措施

    6.4 速率限制

    症状：机器人响应变慢或提示速率限制

    解决方案：

    1. Discord 速率限制

    • Discord API 有速率限制（如：每秒最多发送 10 条消息）

    • 实现消息队列或延迟发送

  • 检查日志

    1. clawdbot logs --filter "rate limit"

  • 优化发送逻辑

    • 合并多条消息

    • 使用 Embed 格式减少消息数量

    6.5 斜杠命令不工作

    症状：输入 / 后看不到机器人的命令

    解决方案：

    1. 检查 OAuth2 权限

    • 确保在 Scopes 中勾选了 applications.commands

    • 重新生成邀请链接并重新授权

  • 等待命令注册

    • 新添加的命令可能需要几分钟才能生效

    • 重启机器人可以加速命令注册

  • 查看命令注册日志

    1. clawdbot logs --filter "command"

    Discord 特有功能

    1. 斜杠命令（Slash Commands）

    Discord 的斜杠命令是官方推荐的消息交互方式，提供更好的用户体验。

    特点：

    • ✅ 自动补全和提示

    • ✅ 参数验证

    • ✅ 集成的帮助文档

    • ✅ 更好的权限控制

    默认命令：

    • /ping

       - 检查机器人延迟

    • /help

       - 显示帮助信息

    • /status

       - 查看机器人状态

    自定义命令示例：

    {"customCommands":{"weather":{"description":"查询天气","options":[{"name":"city","description":"城市名称","type":"string","required":true}]},"translate":{"description":"翻译文本","options":[{"name":"text","description":"要翻译的文本","type":"string","required":true},{"name":"from","description":"源语言","type":"string","required":false},{"name":"to","description":"目标语言","type":"string","required":false}]}}}

    2. 消息反应（Message Reactions）

    支持对消息添加 Emoji 反应，实现投票、反馈等功能。

    使用场景：

    • 📊 投票统计

    • 👍👎 反馈收集

    • ✅❌ 任务确认

    • ⭐⭐⭐⭐⭐ 评分系统

    示例：

    // 添加消息反应await message.react('👍');await message.react('👎');// 监听反应client.on('messageReactionAdd',(reaction, user)=>{  console.log(`${user} reacted with ${reaction.emoji.name}`);});

    3. 富文本消息（Embeds）

    Discord 的 Embed 消息提供了丰富的格式化选项，可以创建美观的消息卡片。

    Embed 特性：

    • 🎨 自定义颜色

    • 📝 多个字段

    • 🖼️ 缩略图和图片

    • 🔗 作者和页脚信息

    • 📅 时间戳

    Embed 示例：

    {"embed":{"title":"📊 每日报告","description":"以下是今天的数据统计","color":3447003,"fields":[{"name":"用户增长","value":"+1,234","inline":true},{"name":"活跃度","value":"85%","inline":true},{"name":"错误率","value":"0.02%","inline":true}],"footer":{"text":"自动生成 | OpenClaw Bot","icon_url":"https://example.com/icon.png"},"timestamp":"2024-01-15T10:00:00Z"}}

    4. 文件附件

    支持发送各种类型的文件，包括图片、视频、文档等。

    支持的文件类型：

    • 📷 图片：PNG, JPG, GIF, WebP

    • 🎬 视频：MP4, WEBM, MOV

    • 📄 文档：PDF, DOC, TXT

    • 💾 其他：ZIP, JSON, CSV 等

    发送文件示例：

    // 发送本地文件await channel.send({  files:[{    attachment:'/path/to/file.pdf',    name:'报告.pdf',    description:'月度报告'}]});// 发送 Bufferconst buffer =Buffer.from(data);await channel.send({  files:[{    attachment: buffer,    name:'data.json'}]});

    5. 语音频道集成（高级）

    机器人可以加入语音频道，实现以下功能：

    • 🎵 音乐播放

    • 🎙️ 语音转文字

    • 🗣️ 文字转语音

    • 🔊 音效播放

    配置示例：

    {"voice":{"enabled":true,"autoJoin":false,"channels":["123456789012345678"]}}

    6. Webhook 支持

    使用 Webhook 可以在特定频道发送消息，无需机器人在线。

    使用场景：

    • 📢 系统通知

    • 🔔 警报推送

    • 📈 定时报告

    • 🎉 事件提醒

    Webhook 创建方法：

    1. 进入服务器设置

    2. 选择频道

    3. 集成 → Webhooks → 创建 Webhook

    4. 复制 Webhook URL

    7. 线程（Threads）

    Discord 的线程功能允许在频道中创建子讨论，适合复杂的对话场景。

    使用场景：

    • 💬 长对话讨论

    • 🔍 问题追踪

    • 📋 任务管理

    • 🎯 用户支持

    线程示例：

    // 创建线程const thread = await message.startThread({  name:'讨论主题',  autoArchiveDuration:1440// 24小时});// 在线程中发送消息await thread.send('这是线程中的消息');

    8. 按钮和选择菜单（交互组件）

    Discord 支持交互式 UI 组件，提升用户体验。

    按钮示例：

    {"components":[{"type":1,"components":[{"type":2,"label":"确认","style":3,"custom_id":"confirm_button"},{"type":2,"label":"取消","style":4,"custom_id":"cancel_button"}]}]}

    最佳实践

    安全建议

    1. Token 管理

    • ❌ 不要将 Token 提交到版本控制系统

    • ❌ 不要在公开渠道分享 Token

    • ✅ 使用环境变量存储 Token

    • ✅ 定期更换 Token

  • 权限控制

    • ✅ 遵循最小权限原则

    • ✅ 使用白名单机制

    • ✅ 定期审查机器人权限

  • 日志管理

    • ✅ 记录关键操作日志

    • ❌ 不要记录敏感信息（Token、用户密码）

    • ✅ 定期清理旧日志

    性能优化

    1. 消息缓存

    • 合理设置 historyLimit

    • 避免缓存过多历史消息

  • 速率限制处理

    • 实现消息队列

    • 添加重试机制

    • 监控 API 调用量

  • 错误处理

    • 捕获所有可能的异常

    • 提供友好的错误提示

    • 实现自动恢复机制

    用户体验

    1. 响应时间

    • 及时响应用户消息

    • 对于长时间操作，显示加载状态

  • 帮助文档

    • 提供清晰的命令说明

    • 使用示例和提示

  • 状态反馈

    • 明确的操作反馈

    • 错误信息易于理解

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

OpenClaw部署和使用心得

avatar 龙虾开发者社区

AI 龙虾 | 对学习工作的影响和未来前瞻

AI 龙虾（OpenClaw）是能自主操控设备、完成全流程任务的 AI 智能体，核心是 “动口即执行”，正从工具升级为数字生产力单元，深刻重塑学习与工作模式。

avatar 龙虾开发者社区
cover

动手写个agent（四）：实现接入MCP 协议

avatar 龙虾开发者社区