Skip to main content

​
Discord（Bot API）

通过官方 Discord 机器人网关支持私信和服务器文字频道通信。

​
快速设置

1

创建 Discord 应用

前往 Discord 开发者门户：
  1. 点击 New Application
  2. 输入应用名称
  3. 进入 Bot 标签
  4. 点击 Add Bot
  5. 复制 Bot Token
2

启用必需的意图

在 Bot → Privileged Gateway Intents 中启用：
  • ✅ Message Content Intent（必需）
  • ✅ Server Members Intent（推荐）
没有 Message Content Intent，机器人无法读取消息内容。
3

配置 OpenClaw

export DISCORD_BOT_TOKEN="your-bot-token"
或在配置文件中：
{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "your-bot-token"
    }
  }
}
4

生成邀请 URL

在 OAuth2 → URL Generator 中：Scopes：
  • bot
  • applications.commands
Bot Permissions：
  • View Channels
  • Send Messages
  • Read Message History
  • Embed Links
  • Attach Files
  • Add Reactions
复制生成的 URL 并邀请机器人到你的服务器。

​
配置选项

​
基础配置

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "dm": {
        "enabled": true,
        "policy": "pairing"
      },
      "groupPolicy": "allowlist",
      "guilds": {
        "123456789012345678": {
          "requireMention": true,
          "channels": {
            "general": { "allow": true }
          }
        }
      }
    }
  }
}

{
  "channels": {
    "discord": {
      "dm": {
        "enabled": true,
        "policy": "pairing"
      }
    }
  }
}

{
  "channels": {
    "discord": {
      "guilds": {
        "*": {
          "requireMention": true
        },
        "123456789012345678": {
          "slug": "my-server",
          "requireMention": false,
          "users": ["987654321098765432"],
          "channels": {
            "general": { "allow": true },
            "help": {
              "allow": true,
              "requireMention": true,
              "users": ["987654321098765432"],
              "skills": ["search", "docs"],
              "systemPrompt": "保持回答简短。"
            }
          }
        }
      }
    }
  }
}
使用 "*" 设置所有服务器的默认值。显式服务器条目会覆盖通配符。

​
获取 ID

1

启用开发者模式

Discord → 用户设置 → 高级 → 启用 开发者模式
2

复制 ID

右键点击：
  • 服务器名称 → 复制服务器 ID
  • 频道（如 #help）→ 复制频道 ID
  • 你的用户 → 复制用户 ID

​
高级功能

Discord 支持私信中执行审批的按钮界面：
{
  "channels": {
    "discord": {
      "execApprovals": {
        "enabled": true,
        "approvers": ["123456789012345678"]
      }
    }
  }
}
用户会收到带有以下按钮的私信：
  • Allow once - 允许一次
  • Always allow - 始终允许
  • Deny - 拒绝
解析 PluralKit 代理消息，使系统成员显示为不同的发送者：
{
  "channels": {
    "discord": {
      "pluralkit": {
        "enabled": true,
        "token": "pk_live_..."  // 可选，私有系统需要
      }
    }
  }
}
在允许列表中使用 pk:<memberId> 引用 PK 成员。
控制智能体可以使用的 Discord 功能：
{
  "channels": {
    "discord": {
      "actions": {
        "reactions": true,
        "stickers": true,
        "polls": true,
        "messages": true,
        "threads": true,
        "pins": true,
        "search": true,
        "roles": false,        // 默认禁用
        "moderation": false    // 默认禁用
      }
    }
  }
}

​
回复和线程

​
回复标签

模型可以使用标签控制回复行为： 
[[reply_to_current]]  # 回复触发的消息
[[reply_to:123456]]   # 回复特定消息 ID

​
回复模式

{
  "channels": {
    "discord": {
      "replyToMode": "off"  // off | first | all
    }
  }
}
模式行为
off忽略回复标签（默认）
first只有第一个出站块/附件是回复
all每个出站块/附件都是回复

​
媒体处理

​
支持的类型

  • 图片（JPEG、PNG、GIF、WebP）
  • 视频（MP4、WEBM、MOV）
  • 音频（MP3、WAV、OGG）
  • 文档（任意文件）

​
限制

{
  "channels": {
    "discord": {
      "textChunkLimit": 2000,
      "maxLinesPerMessage": 17,
      "mediaMaxMb": 8
    }
  }
}

​
表情反应

​
表情反应通知

控制机器人何时通知智能体有关表情反应的信息： 
{
  "channels": {
    "discord": {
      "guilds": {
        "123456789012345678": {
          "reactionNotifications": "own"  // off | own | all | allowlist
        }
      }
    }
  }
}
模式描述
off无表情反应事件
own仅机器人自己消息上的表情反应（默认）
all所有消息上的所有表情反应
allowlist仅来自允许列表用户的表情反应

​
故障排除

检查项：
  1. Message Content Intent 已启用
  2. 机器人有频道权限（View/Send/Read History）
  3. 消息包含提及（如果 requireMention: true）
  4. 频道在允许列表中（如果使用 groupPolicy: "allowlist"）
运行诊断：
openclaw doctor
openclaw channels status --probe
原因： 未启用特权网关意图解决方案：
  1. 前往开发者门户
  2. 在 Bot 标签中启用 Message Content Intent
  3. 可选启用 Server Members Intent
  4. 重启 Gateway 网关
原因： groupPolicy 默认为 allowlist解决方案：
{
  "channels": {
    "discord": {
      "groupPolicy": "open"
    }
  }
}
或添加服务器到允许列表。
检查项：
  1. execApprovals.enabled: true
  2. 你的用户 ID 在 execApprovals.approvers 中
  3. 使用私信提示中的按钮，不要使用 /approve 命令
参见执行审批了解详情。

​
多账户支持

运行多个 Discord 机器人： 
{
  "channels": {
    "discord": {
      "accounts": {
        "main": {
          "name": "主机器人",
          "token": "token1",
          "dm": { "policy": "pairing" }
        },
        "community": {
          "name": "社区机器人",
          "token": "token2",
          "guilds": {
            "123456789012345678": {
              "requireMention": false
            }
          }
        }
      }
    }
  }
}

​
相关资源

配对系统

了解如何批准新用户

斜杠命令

配置 Discord 斜杠命令

执行审批

配置命令执行审批

配置参考

完整的 Discord 配置选项