OpenClaw Discord 集成：机器人设置与 Gateway Intents 详解
创建 Discord 机器人并连接 OpenClaw 的完整指南，涵盖 Gateway Intents 详解、私信安全策略配置以及服务器频道访问控制设置。
OpenClaw Guides
Tutorial Authors
概述
Discord 集成让您可以通过 Discord 机器人与 OpenClaw 进行对话，支持私信（DM）和服务器文字频道两种通信方式。本指南涵盖创建机器人、理解 Gateway Intents、配置私信安全策略以及设置服务器频道访问控制——所有内容均基于 OpenClaw 官方文档。
前提条件
- 已安装并运行 OpenClaw
- 一个 Discord 账户
- 一个您拥有管理员权限的 Discord 服务器（用于测试）
工作原理
在深入了解之前，先了解 OpenClaw 如何路由 Discord 消息：
- 私信对话 会合并到一个共享会话（
agent:main:main），默认使用基于配对的安全机制。 - 服务器频道对话 按频道隔离，使用
agent:<agentId>:discord:channel:<channelId>的模式。 - 群组私信 默认被忽略，但可以通过
channels.discord.dm.groupEnabled启用。
当存在有效令牌且 enabled 未设为 false 时，网关会自动启动。
步骤1：创建 Discord 应用
前往 Discord Developer Portal
- 访问 Discord Developer Portal
- 点击 New Application
- 输入名称（例如 "OpenClaw Assistant"）
- 点击 Create
设置机器人
- 在应用中，进入 Bot 选项卡
- 点击 Add Bot → Yes, do it!
- 在 Token 下，点击 Copy 复制机器人令牌
重要： 机器人令牌应视同密码处理。切勿公开分享。如果泄露，请立即重新生成。
步骤2：启用特权 Gateway Intents
Gateway Intents 控制您的机器人从 Discord 接收哪些事件。OpenClaw 需要特定的特权 intents 才能正常运行。
所需 Intents
| Intent | 用途 | 是否必需 | |--------|------|----------| | Message Content Intent | 读取服务器频道中的消息文本 | 必需 — 缺少此 intent 时，机器人会显示 "Used disallowed intents" 错误，或连接成功但无法响应 | | Server Members Intent | 成员查询和白名单匹配 | 推荐 — 基于白名单的访问控制需要此 intent |
在 Developer Portal 中启用 Intents
- 在 Developer Portal 中进入 Bot 选项卡
- 滚动到 Privileged Gateway Intents
- 启用 MESSAGE CONTENT INTENT（必须开启）
- 启用 SERVER MEMBERS INTENT（推荐开启）
- 点击 Save Changes
注意： 加入 100 个以上服务器的机器人需要通过 Discord 验证才能使用特权 intents。
步骤3：生成机器人邀请 URL
配置 OAuth2
-
进入 OAuth2 → URL Generator
-
选择作用域：
botapplications.commands（原生斜杠命令需要此项）
-
选择机器人权限：
View ChannelsSend MessagesRead Message HistoryEmbed LinksAttach FilesAdd Reactions（可选但推荐）Use External Emojis（可选）
警告： 除非正在进行调试，否则请避免授予 Administrator 权限。仅授予必要的权限。
- 复制生成的 URL
邀请机器人
- 在浏览器中打开 URL
- 选择您的测试服务器
- 点击 Authorize
获取数字 ID
在 Discord 中启用 Developer Mode（用户设置 → 应用设置 → 高级 → 开发者模式），这样您就可以右键点击复制服务器、频道和用户 ID——配置时会用到这些信息。
步骤4：配置 OpenClaw
方式 A：环境变量
将令牌设置为环境变量：
export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
方式 B：配置文件
直接在 OpenClaw 配置文件中填入令牌：
{
channels: {
discord: {
enabled: true,
token: "YOUR_BOT_TOKEN"
}
}
}
注意： 当环境变量和配置文件中同时存在令牌时，配置文件优先。
方式 C：多账户支持
运行多个机器人账户：
{
channels: {
discord: {
accounts: [
{ token: "BOT_TOKEN_1", name: "assistant-1" },
{ token: "BOT_TOKEN_2", name: "assistant-2" }
]
}
}
}
步骤5：启动并测试
启动或重启 OpenClaw 网关：
openclaw gateway restart
检查频道状态：
openclaw channels status --probe
如果发现异常，运行诊断：
openclaw doctor
首次私信联系时，机器人默认使用配对机制——发送者会收到一个限时验证码（1 小时后过期），需要通过审批后对话才能开始。
私信安全策略
OpenClaw 提供三种私信访问控制策略：
配对模式（默认）
未知发送者会收到一个限时配对验证码，1 小时后过期。验证码必须通过审批后对话才能继续。
{
channels: {
discord: {
dm: {
enabled: true,
policy: "pairing"
}
}
}
}
白名单模式
仅允许配置的用户 ID 或用户名发送私信：
{
channels: {
discord: {
dm: {
enabled: true,
policy: "allowlist",
allowFrom: ["123456789012345678", "username#1234"]
}
}
}
}
开放模式
任何人都可以发送私信（请谨慎使用）：
{
channels: {
discord: {
dm: {
enabled: true,
policy: "open",
allowFrom: ["*"]
}
}
}
}
服务器频道配置
基本服务器访问控制
将机器人限制在特定服务器和频道，并设置提及要求：
{
channels: {
discord: {
guilds: {
"GUILD_ID": {
requireMention: true,
channels: {
"CHANNEL_ID": {
enabled: true
}
}
}
}
}
}
}
重要：
requireMention必须在服务器或频道级别配置，不能放在 Discord 配置的顶层。
按频道设置
您可以为每个频道配置白名单和技能限制：
{
channels: {
discord: {
guilds: {
"GUILD_ID": {
channels: {
"CHANNEL_ID_1": {
enabled: true,
requireMention: true
},
"CHANNEL_ID_2": {
enabled: true,
requireMention: false
}
}
}
}
}
}
}
配置参数
消息设置
| 参数 | 默认值 | 说明 |
|------|--------|------|
| textChunkLimit | 2000 | 每条发送消息的最大字符数 |
| chunkMode | — | 设置在应用长度限制前按空行（段落边界）分割 |
| maxLinesPerMessage | 17 | 每条消息的最大行数 |
| mediaMaxMb | 8 | 媒体文件的最大大小（MB） |
上下文历史
{
channels: {
discord: {
historyLimit: 20 // 作为上下文包含的最近消息数量（默认：20，设为 0 禁用）
}
}
}
回复线程
原生回复线程默认关闭。通过以下方式启用：
{
channels: {
discord: {
replyToMode: "on" // 启用原生回复线程
}
}
}
在智能体回复中使用回复标签控制线程行为：
[[reply_to_current]]— 回复当前正在处理的消息[[reply_to:<message_id>]]— 回复特定消息
表情反应通知
按服务器配置表情反应事件通知：
{
channels: {
discord: {
guilds: {
"GUILD_ID": {
reactionNotifications: "own" // 选项："off", "own", "all", "allowlist"
}
}
}
}
}
工具操作
智能体可以调用 discord 工具在 Discord 中执行操作。大多数操作默认启用，但角色和管理操作默认禁用。
可用操作
| 类别 | 操作 | |------|------| | 表情反应 | react, sticker, poll | | 消息 | readMessages, sendMessage, editMessage, deleteMessage, searchMessages | | 线程 | threadCreate, threadList, threadReply | | 置顶 | pinMessage, unpinMessage, listPins | | 频道 | channelInfo, channelList | | 成员 | memberInfo, roleInfo, permissions | | 角色 | roleAdd, roleRemove（默认禁用） | | 管理 | timeout, kick, ban（默认禁用） | | 其他 | emojiList, voiceStatus, eventList, eventCreate, setPresence |
高级功能
PluralKit 支持
启用后，OpenClaw 会将代理消息解析为其底层系统成员，将发送者显示为 "Member (PK:System)" 以防止意外的 Discord 提及通知。
执行审批按钮界面
在私信对话中，OpenClaw 可以展示执行审批按钮，用于工具操作的交互式确认。
重试配置
发送 API 调用在遇到速率限制时会自动重试，使用 Discord 的 retry_after 头信息进行指数退避。可通过 channels.discord.retry 参数配置重试行为。
故障排除
机器人在线但不响应
-
检查 Message Content Intent： 缺少此 intent 时，机器人可以连接但无法读取消息文本。前往 Developer Portal → Bot → Privileged Gateway Intents，确保 MESSAGE CONTENT INTENT 已启用。
-
验证频道权限： 确保机器人在目标频道中拥有 View Channels 和 Send Messages 权限。
-
检查提及要求： 如果服务器或频道启用了
requireMention，您必须 @提及机器人。 -
检查服务器/频道白名单： 确认频道未被白名单配置阻止。
"Used Disallowed Intents" 错误
这意味着所需的 intents 未在 Developer Portal 中启用：
- 前往 Developer Portal → Bot → Privileged Gateway Intents
- 启用 MESSAGE CONTENT INTENT
- 保存并重启 OpenClaw 网关
私信不工作
- 确认
dm.enabled未设为false - 检查私信策略——如果设为 "allowlist"，确保用户 ID 已包含在列表中
- 如果使用 "pairing" 策略，检查配对验证码是否已过期（1 小时限制）
诊断命令
使用内置诊断工具排查问题：
# 运行完整诊断 openclaw doctor # 检查频道状态并探测连接 openclaw channels status --probe
最佳实践
- 将机器人令牌视同密码 — 在受管主机上使用环境变量，切勿将令牌提交到源代码管理。
- 仅授予必要权限 — 除非正在调试，否则避免使用 Administrator 权限。
- 使用配对或白名单私信策略 — "open" 策略仅应用于已配置适当速率限制的公开机器人。
- 启用 Server Members Intent — 如果使用基于白名单的访问控制，可实现更可靠的成员匹配。
- 在繁忙的服务器中使用
requireMention— 防止机器人对每条消息都进行响应。 - 使用
--force重启网关 — 如果网关卡住：openclaw gateway restart --force。