本页提供完整的 OpenClaw Discord 集成步骤：从创建 Discord 应用、获取 Bot Token，到配对私信并配置服务器工作空间。关键操作：设置 DISCORD_BOT_TOKEN 环境变量，使用 openclaw config patch 注入配置，再通过私信完成配对。排查时运行 openclaw doctor 和 openclaw channels status --probe。支持语音频道、交互组件、多账号及基于角色的 Agent 路由。

OpenClaw Discord Bot 配置与故障排查

Discord Bot 集成状态：通过官方 Discord Gateway 支持私信和服务器频道。默认使用配对模式（dmPolicy 为 pairing），服务器频道需配置白名单。

快速设置：创建 Discord Bot 并接入 OpenClaw

你需要创建一个带 Bot 的 Discord 应用，添加到你的服务器，然后与 OpenClaw 配对。推荐添加到自己的私人服务器。若没有服务器，先创建一个（选择 Create My Own > For me and my friends）。

1. 创建 Discord 应用和 Bot

前往 Discord Developer Portal，点击 New Application，命名为 “OpenClaw” 等名称。侧边栏点击 Bot，设置 Username 为你的 Agent 名称。

2. 启用特权 Intent

在 Bot 页面向下滚动到 Privileged Gateway Intents，启用：

Message Content Intent（必需）
Server Members Intent（推荐；角色白名单和名称-ID 解析需要）
Presence Intent（可选，仅用于在线状态更新）

3. 复制 Bot Token

在 Bot 页面点击 Reset Token（实际是生成第一个 Token），复制保存。这是你的 Bot Token，稍后用于 OpenClaw 配置。

4. 生成邀请 URL 并添加 Bot 到服务器

侧边栏点击 OAuth2，在 OAuth2 URL Generator 中启用：

bot
applications.commands

下方 Bot Permissions 至少启用：

View Channels
Send Messages
Read Message History
Embed Links
Attach Files
Add Reactions（可选）

若需要在 Discord 线程中发消息（包括论坛/媒体频道），额外启用 Send Messages in Threads。复制底部 URL 访问，选择你的服务器完成添加。

5. 启用开发者模式并收集 ID

在 Discord 应用中：

用户设置 → Advanced → 开启 Developer Mode
右键服务器图标 → Copy Server ID
右键自己头像 → Copy User ID

保存 Server ID 和 User ID，与 Bot Token 一起备用。

6. 允许服务器成员发私信

右键服务器图标 → Privacy Settings → 开启 Direct Messages。配对完成后可关闭（仅用服务器频道时）。

7. 安全设置 Bot Token（不要在聊天中发送）

在运行 OpenClaw 的机器上设置环境变量：

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
cat > discord.patch.json5 <<'JSON5'
{
  channels: {
    discord: {
      enabled: true,
      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
    },
  },
}
JSON5
openclaw config patch --file ./discord.patch.json5 --dry-run
openclaw config patch --file ./discord.patch.json5
openclaw gateway

若 OpenClaw 已作为后台服务运行，重启服务或执行 openclaw gateway install（确保环境变量可用）。如果主机被 Discord 启动查询限流，设置 channels.discord.applicationId 跳过 REST 调用。

8. 配置 OpenClaw 并配对

通过 Agent 配置（已有其他渠道时）：

“I already set my Discord bot token in config. Please finish Discord setup with User ID <user_id> and Server ID <server_id>.”

通过 CLI / 配置文件：

{
  channels: {
    discord: {
      enabled: true,
      token: {
        source: "env",
        provider: "default",
        id: "DISCORD_BOT_TOKEN",
      },
    },
  },
}

环境变量回退：DISCORD_BOT_TOKEN=...。支持 SecretRef 多账号配置（见下）：

{
  channels: {
    discord: {
      enabled: true,
      accounts: {
        personal: {
          token: { source: "env", provider: "default", id: "DISCORD_PERSONAL_TOKEN" },
          applicationId: "111111111111111111",
        },
        work: {
          token: { source: "env", provider: "default", id: "DISCORD_WORK_TOKEN" },
          applicationId: "222222222222222222",
        },
      },
    },
  },
}

9. 审批第一次私信配对

Gateway 启动后，向 Bot 发私信。Bot 会回复一个配对码。将配对码发送给 Agent（通过其他渠道）或使用 CLI：

openclaw pairing list discord
openclaw pairing approve discord <CODE>

配对码 1 小时后过期。完成后即可在 Discord 私信中与 Agent 聊天。

Token 解析：配置中的 Token 值优先于环境变量回退。DISCORD_BOT_TOKEN 仅用于默认账号。若两个启用的 Discord 账号解析到相同 Token，OpenClaw 只启动一个 Gateway 监听器。

推荐：配置 Discord 服务器工作区

私信正常工作后，将 Discord 服务器设置为完整工作区，每个频道拥有独立 Agent 会话和上下文。

1. 将服务器加入 Guild 白名单

{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        YOUR_SERVER_ID: {
          requireMention: true,
          users: ["YOUR_USER_ID"],
        },
      },
    },
  },
}

2. 允许无 @提及回复

默认只对 @提及回复。私人服务器可取消：

{
  channels: {
    discord: {
      guilds: {
        YOUR_SERVER_ID: {
          requireMention: false,
        },
      },
    },
  },
}

若需要 Agent 潜伏并在认为有用时才回复，设置 messages.groupChat.visibleReplies: "message_tool"（需要最新模型支持）。

3. 规划频道内存

长期记忆（MEMORY.md）默认只在私信会话加载。服务器频道不会自动加载。可将稳定指令放在 AGENTS.md 或 USER.md 中（注入所有会话），长期笔记放在 MEMORY.md 中通过记忆工具按需访问。

运行时模型

Gateway 拥有 Discord 连接
回复路由确定：Discord 入站回复回到 Discord
私信共享 Agent 主会话（session.dmScope=main 下）
服务器频道使用独立会话密钥：agent:<agentId>:discord:channel:<channelId>
群组私信默认忽略（channels.discord.dm.groupEnabled=false）
原生 Slash 命令在独立命令会话中运行，但携带 CommandTargetSessionKey 到路由对话

论坛频道

Discord 论坛和媒体频道只接受线程帖子。两种创建方式：

向论坛父频道发消息（channel:<forumId>）自动创建线程，标题使用消息第一个非空行
使用 openclaw message thread create 直接创建（不要传 --message-id）

示例：

openclaw message send --channel discord --target channel:<forumId> \
  --message "Topic title\nBody of the post"

论坛父频道不接受 Discord 组件；如需组件，向线程本身发送（channel:<threadId>）。

交互组件

OpenClaw 支持 Discord Components v2 容器。通过消息工具发送 components 载荷，交互结果作为普通入站消息路由回 Agent。

支持的块类型：text、section、separator、actions、media-gallery、file。操作行最多 5 个按钮或一个选择菜单（类型：string、user、role、mentionable、channel）。

默认组件单次使用。设置 components.reusable=true 允许多次使用。allowedUsers 限制按钮点击者。

组件回调默认 30 分钟过期，可通过 channels.discord.agentComponents.ttlMs 调整（最大 86400000 毫秒）。

/model 和 /models 命令打开交互式模型选择器。模态表单支持 text、checkbox、radio、select、role-select、user-select 字段。

完整示例见原文。

访问控制和路由

DM 策略

channels.discord.dmPolicy 控制私信访问（旧版 channels.discord.dm.policy 仍兼容）：

pairing（默认）
allowlist
open（需 allowFrom 包含 "*"）
disabled

DM 目标格式：user:<id> 或 <@id>。裸数字 ID 在 DM 上下文中被作为用户目标处理（当列在 allowFrom 时）。

访问组（Access Groups）

支持动态和静态访问组。例如，允许 #maintainers 频道可见的用户发私信：

{
  accessGroups: {
    maintainers: {
      type: "discord.channelAudience",
      guildId: "1456350064065904867",
      channelId: "1456744319972282449",
    },
  },
  channels: {
    discord: {
      dmPolicy: "allowlist",
      allowFrom: ["accessGroup:maintainers"],
    },
  },
}

需要启用 Server Members Intent。

Guild 策略

channels.discord.groupPolicy：

open
allowlist（推荐，存在 channels.discord 时默认）
disabled

allowlist 行为：guild 必须匹配 channels.discord.guilds 中的 ID 或 slug；可选用户/角色白名单；若配置了 channels，未列出频道被拒绝。

基于角色的 Agent 路由

使用 bindings[].match.roles 按角色 ID 路由：

{
  bindings: [
    {
      agentId: "opus",
      match: { channel: "discord", guildId: "123456789012345678", roles: ["111111111111111111"] },
    },
    { agentId: "sonnet", match: { channel: "discord", guildId: "123456789012345678" } },
  ],
}

原生命令和命令授权

commands.native 默认 "auto"，Discord 已启用
覆盖：channels.discord.commands.native
禁用原生命令不会自动删除已注册的命令，需手动在 Discord 应用管理移除
授权与普通消息相同的白名单/策略

Slash 命令默认 ephemeral: true。详细目录见 Slash 命令。

功能详情

回复标签和原生回复

支持 [[reply_to_current]] 和 [[reply_to:<id>]]。channels.discord.replyToMode 控制：

off（默认）：禁用隐式回复串，但显式标签仍生效
first：仅第一则消息附加原生回复
all
batched：仅在入站是批次聚合时附加

链接预览

默认 OpenClaw 抑制 Discord 自动生成的 URL 嵌入。设置 channels.discord.suppressEmbeds: false 允许展开。消息工具可单次覆盖。

实时流式预览

channels.discord.streaming 控制流式编辑：off（默认）| partial | block | progress。progress 模式支持工具进度显示。详细配置见原文。

历史上下文和线程

Guild 频道历史限制：channels.discord.historyLimit（默认 20），回退 messages.groupChat.historyLimit
DM 历史限制：channels.discord.dmHistoryLimit
线程继承父频道配置，但不会自动复制父会话历史
channels.discord.thread.inheritParent 控制新线程是否从父会话转录种子

线程绑定会话（Subagents）

通过 /focus <target> 绑定线程到子 Agent 或 ACP 会话。配置：

{
  session: {
    threadBindings: { enabled: true, idleHours: 24, maxAgeHours: 0 },
  },
  channels: {
    discord: {
      threadBindings: { enabled: true, idleHours: 24, maxAgeHours: 0, spawnSessions: true, defaultSpawnContext: "fork" },
    },
  },
}

确认反应（Ack Reaction）

ackReaction 发送处理中的表情。解析顺序：账号级 → 渠道级 → messages.ackReaction → Agent 身份 emoji。设为 "" 禁用。

网关代理

channels.discord.proxy 设置 HTTP(S) 代理，路由 WebSocket 和 REST 流量。

PluralKit 支持

启用后映射代理消息到系统成员身份。channels.discord.pluralkit.enabled = true，可选 token 用于私有系统。白名单支持 pk:<memberId>。

提及别名

channels.discord.mentionAliases 让 Agent 输出时使用可读别名替代用户 ID。

在线状态配置

设置 channels.discord.status（如 idle）和 activity（如 "Focus time" 等）。autoPresence 根据运行时健康状态自动切换（online/idle/dnd）。

审批（Exec Approvals）

支持按钮审批。配置 channels.discord.execApprovals.enabled，目标可选 dm（默认）、channel、both。需要至少一个审批者（来自 execApprovals.approvers 或 commands.ownerAllowFrom）。

工具和动作门控

动作门控位于 channels.discord.actions.*。默认：

reactions、messages、threads、pins、polls、search、memberInfo、roleInfo、channelInfo、channels、voiceStatus、events、stickers 等：启用
roles、moderation、presence：禁用

Components v2 UI

OpenClaw 使用 Discord Components v2 容器。可配置强调色 channels.discord.ui.components.accentColor。组件回调 TTL 通过 agentComponents.ttlMs 控制。

语音频道

支持实时语音频道和语音消息附件。

语音频道要求

启用 Message Content Intent 和 Server Members Intent
使用 bot + applications.commands 作用域邀请 Bot
目标语音频道需 Connect、Speak、Send Messages、Read Message History 权限
启用原生命令
配置 channels.discord.voice

使用原生命令 /vc join、/vc leave、/vc status 控制。自动加入示例：

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        model: "openai-codex/gpt-5.5",
        autoJoin: [{ guildId: "123456789012345678", channelId: "234567890123456789" }],
        realtime: { provider: "openai", model: "gpt-realtime-2", voice: "cedar" },
      },
    },
  },
}

语音模式：

agent-proxy（默认）：实时语音前端处理时序和中断，实际回答委托给 OpenClaw Agent
stt-tts：传统批量转写 + TTS
bidi：实时模型直接对话，但仍可咨询 OpenClaw

跟随用户模式：voice.followUsers 让 Bot 自动加入用户所在的语音频道。

语音消息附件

发送 OGG/Opus 格式语音消息，需要 ffmpeg 和 ffprobe。提供本地文件路径（URL 被拒绝），省略文本内容。OpenClaw 自动生成波形预览。

故障排除

Discord Bot 收不到消息或看不到服务器消息

确认已启用 Message Content Intent 和 Server Members Intent
重启 Gateway 后重试
运行 openclaw doctor 和 openclaw channels status --probe

服务器消息被意外阻止

检查 groupPolicy 是否为 allowlist
检查 channels.discord.guilds 是否包含正确的服务器 ID
如果 guilds 下有 channels 映射，只有列出的频道允许访问
确认 requireMention 设置正确

要求不提及但 Bot 仍不回复

常见原因：

groupPolicy="allowlist" 但没有匹配的 guild/channel 白名单
requireMention 配置在了错误位置（必须在 channels.discord.guilds 或频道条目下）
发送者被 users 或 roles 白名单阻止

长时间运行的处理超时或重复回复

增加 listener 超时：

{
  channels: {
    discord: {
      accounts: {
        default: {
          eventQueue: { listenerTimeout: 120000 },
        },
      },
    },
  },
}

语音频道无法加入或声音问题

确认 Bot 有 Connect + Speak 权限
运行 openclaw channels capabilities --channel discord --target channel:<voice-channel-id> 检查权限
刷新 Gateway 后重试
若出现解密失败（DecryptionFailed），保持 DAVE 加密启用，调整 decryptionFailureTolerance

DM 或配对失败

检查 channels.discord.dm.enabled 未设为 false
检查 dmPolicy 未设为 disabled
配对码过期（1 小时），重新发送私信获取新码

Gateway 元数据查找超时

设置 channels.discord.gatewayInfoTimeoutMs（默认 30000ms，最大 120000ms）。

Gateway READY 超时重启

有多个账号时可能需要更长等待时间。调整 gatewayReadyTimeoutMs（默认 15000ms）或 gatewayRuntimeReadyTimeoutMs（默认 30000ms）。

配置参考

主要参考：配置参考 - Discord。

高信号字段：

enabled、token、accounts.*、allowBots
groupPolicy、dmPolicy、guilds.*、guilds.*.channels.*
commands.native、configWrites
eventQueue.listenerTimeout、eventQueue.maxQueueSize
gatewayInfoTimeoutMs、gatewayReadyTimeoutMs
replyToMode、historyLimit、dmHistoryLimit
streaming、draftChunk
mediaMaxMb（默认 100MB）、retry
actions.*、activity、status
ui.components.accentColor
threadBindings、pluralkit、execApprovals

安全和运维

将 Bot Token 当密钥处理，建议使用环境变量 DISCORD_BOT_TOKEN
授予最小必要权限
若命令部署状态异常，重启 Gateway 并用 openclaw channels status --probe 检查

常见问题

Discord Bot 如何正确设置 Token 而不在聊天中泄露？

在运行 OpenClaw 的机器上通过环境变量设置 DISCORD_BOT_TOKEN，然后使用 openclaw config patch 注入 SecretRef 配置。切勿直接在聊天中发送 Token。

怎样允许 Bot 在频道中无需 @提及回复？

在 guild 配置中将 requireMention 设为 false。例如：

{
  channels: {
    discord: {
      guilds: {
        "YOUR_SERVER_ID": {
          requireMention: false,
        },
      },
    },
  },
}

若是公共频道，考虑使用 messages.groupChat.visibleReplies: "message_tool" 模式。

语音频道加入后听不到声音或声音中断

检查 Bot 在语音频道的权限（Connect、Speak、View Channels）。确保启用了原生命令，并正确配置了 voice 块。如果使用实时模式，确认 voice.realtime.provider 和模型可用。查看 Gateway 日志中的 discord voice: 消息排查。

OpenClaw Discord Bot 配置与故障排查 #

快速设置：创建 Discord Bot 并接入 OpenClaw #

1. 创建 Discord 应用和 Bot #

2. 启用特权 Intent #

3. 复制 Bot Token #

4. 生成邀请 URL 并添加 Bot 到服务器 #

5. 启用开发者模式并收集 ID #

6. 允许服务器成员发私信 #

7. 安全设置 Bot Token（不要在聊天中发送） #

8. 配置 OpenClaw 并配对 #

9. 审批第一次私信配对 #

推荐：配置 Discord 服务器工作区 #

1. 将服务器加入 Guild 白名单 #

2. 允许无 @提及回复 #

3. 规划频道内存 #

运行时模型 #

论坛频道 #

交互组件 #

访问控制和路由 #

DM 策略 #

访问组（Access Groups） #

Guild 策略 #

基于角色的 Agent 路由 #

原生命令和命令授权 #

功能详情 #

回复标签和原生回复 #

链接预览 #

实时流式预览 #

历史上下文和线程 #

线程绑定会话（Subagents） #

确认反应（Ack Reaction） #

网关代理 #

PluralKit 支持 #

提及别名 #

在线状态配置 #

审批（Exec Approvals） #

工具和动作门控 #

Components v2 UI #

语音频道 #

语音频道要求 #

语音消息附件 #

故障排除 #

Discord Bot 收不到消息或看不到服务器消息 #

服务器消息被意外阻止 #

要求不提及但 Bot 仍不回复 #

长时间运行的处理超时或重复回复 #

语音频道无法加入或声音问题 #

DM 或配对失败 #

Gateway 元数据查找超时 #

Gateway READY 超时重启 #

配置参考 #

安全和运维 #

常见问题 #

Discord Bot 如何正确设置 Token 而不在聊天中泄露？ #

怎样允许 Bot 在频道中无需 @提及回复？ #

语音频道加入后听不到声音或声音中断 #