II. 频道系统 - 3. Discord

📍 课程位置

阶段：II. 频道系统
课序：第 3 课
前置知识：I. 核心架构（Gateway/Session/Tools）
后续课程：II-4. Slack

---

🎯 本课核心问题（你不懂我就这样教你）

Discord 接入经常踩这些坑：

1. 我怎么创建 Discord Bot，并接到 OpenClaw？
2. Bot 为什么收不到消息/发不出去？是不是权限没配对？
3. 群里机器人为什么乱回？能不能必须 @ 才回？
4. Discord 的 Thread/Slash 命令/权限模型跟其他平台有什么不同？

这一篇我们用“能跑通 + 安全可控 + 可排障”的方式讲清楚。

---

🧠 心智模型：Discord = 服务器（Guild）+ 频道（Channel）+ 权限（Permissions）

一句话：

Discord 的难点不在 token，而在 Bot 权限和事件订阅。

类比：

• Discord 服务器（Guild）像“公司”
• 频道（Channel）像“部门群”
• Bot 像“新员工”
• 你必须给它：
  • 进门权限（invite + scopes）
  • 说话权限（Send Messages）
  • 看消息权限（Read Message History）

---

✅ 你要达到的结果（验收标准）

• 创建 Discord 应用并生成 Bot token
• 把 Bot 邀请进某个服务器（Guild）
• OpenClaw 能收到频道消息
• OpenClaw 能在频道里回复
• 配置 requireMention，避免乱回

---

🔧 第一步：创建 Discord Bot 并拿 Token

1. 打开 Discord Developer Portal
2. New Application
3. 进入 Bot 页面，Create Bot
4. 复制 Bot Token（注意保密）

---

🔧 第二步：把 Bot 邀请进服务器（最常见卡点）

你需要生成 Invite URL（OAuth2）。

必须要的 Scopes（常见）

• bot
• （如果你用 slash commands）applications.commands

必须要的 Bot Permissions（最低可用）

• View Channels
• Send Messages
• Read Message History

如果你想让它在群里能 @ 人，还要：

• Mention Everyone（谨慎）

---

🔧 第三步：在 OpenClaw 配置启用 Discord

在 ~/.openclaw/openclaw.json：

{
  channels: {
    discord: {
      enabled: true,
      botToken: "YOUR_DISCORD_BOT_TOKEN",

      // 安全策略
      dmPolicy: "pairing",         // pairing | allowlist | open | disabled
      allowFrom: ["dc:123456789"], // 需要时才填

      groupPolicy: "open"
    }
  }
}

重点：Discord 常见问题不是 dmPolicy，而是 bot 本身没权限/没进群。

---

🧩 群聊不乱回：必须 @ 才响应

Discord 原生支持 @mention，建议默认开启 requireMention。

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  }
}

这样你能控制：

• 只有别人 @ 你，Agent 才回答
• 避免机器人打断群聊
• 降低注入风险

---

🧵 Discord 的 Thread（线程）与会话绑定

Discord 很常用 Thread（话题线程）。

建议：

• 把 Thread 当成“独立会话”的承载
• 让不同线程不串上下文

你可以结合 session threadBindings 来实现更清晰的路由（不同版本字段略有差异，原则不变）：

• thread = 一个 session
• thread idle/max-age = 自动清理

---

⚠️ Discord 最常见的坑（以及怎么排）

现象	常见原因	排查/解决
Bot 不在线	token 错/未启动/被禁用	看 gateway 日志；确认 token
收不到消息	没开事件/权限不足	检查 bot 权限；确认能读频道
发不出去	没有 Send Messages 权限	给 bot 添加权限
群里乱回	没启用 requireMention	开启 mention gating
线程串上下文	线程绑定没开	开 threadBindings/按 thread 建 session

---

📝 学习心得

Discord 的核心是“权限模型”。

很多人把时间花在“配置字段”上，但真正卡点往往是：

• 没把 bot 正确邀请进 guild
• bot 权限不够（看不到/发不了）

所以我推荐顺序：

1. 先确保 bot 在 guild 里、能发能收
2. 再加安全策略（requireMention、dmPolicy）
3. 再谈高级能力（threads、slash commands）

---

✅ 本课总结（记住 5 句话）

1. Discord 难点在 权限与邀请，不是 token。
2. Invite URL 要包含正确 scopes（bot / applications.commands）。
3. 机器人至少要有：View Channels / Send Messages / Read History。
4. 群聊建议默认 requireMention，避免乱回。
5. Thread 是天然的会话边界，用好 threadBindings 可以避免串线。

---

🔗 相关资源

• 官方文档：https://docs.openclaw.ai/channels/discord
• Discord 开发者门户：https://discord.com/developers/applications
• 配置参考：https://docs.openclaw.ai/gateway/configuration-reference
• 下一课：II-4. Slack