消息平台

Discord

状态：已准备就绪，可通过官方 Discord 网关进行私信和公会频道通信。

配对

Discord 私信默认为配对模式。

斜杠命令

原生命令行为和命令目录。

频道故障排除

跨频道诊断和修复流程。

快速设置

您需要创建一个带有机器人的新应用程序，将机器人添加到您的服务器，并将其与 OpenClaw 配对。我们建议将您的机器人添加到您自己的私人服务器。如果您还没有私人服务器，请先创建一个（选择 创建我自己的 > 为我和我的朋友）。

步骤 1：创建 Discord 应用程序和机器人

前往 Discord 开发者门户 并点击 新建应用程序。将其命名为类似“OpenClaw”的名称。点击侧边栏的 机器人。将 用户名 设置为您为 OpenClaw 智能体（agent）起的任何名称。

步骤 2：启用特权意图

仍在 机器人 页面，向下滚动到 特权网关意图 并启用：

  • 消息内容意图（必需）
  • 服务器成员意图（推荐；角色白名单和名称到 ID 匹配所需）
  • 在线状态意图（可选；仅在线状态更新时需要）

步骤 3：复制您的机器人令牌

在 机器人 页面上向上滚动并点击 重置令牌。

ℹ️ 尽管名称如此，这会生成您的第一个令牌——没有任何东西被“重置”。

复制令牌并保存在某处。这是您的 机器人令牌，您很快会需要它。

步骤 4：生成邀请 URL 并将机器人添加到您的服务器

点击侧边栏的 OAuth2。您将生成一个具有正确权限的邀请 URL，以便将机器人添加到您的服务器。向下滚动到 OAuth2 URL 生成器 并启用：

  • bot
  • applications.commands

下方将出现 机器人权限 部分。启用：

  • 查看频道
  • 发送消息
  • 读取消息历史记录
  • 嵌入链接
  • 附加文件
  • 添加反应（可选）

复制底部生成的 URL，将其粘贴到浏览器中，选择您的服务器，然后点击 继续 进行连接。您现在应该能在 Discord 服务器中看到您的机器人。

步骤 5：启用开发者模式并收集您的 ID

回到 Discord 应用程序，您需要启用开发者模式以便复制内部 ID。

  1. 点击 用户设置（头像旁边的齿轮图标）→ 高级 → 打开 开发者模式
  2. 右键点击侧边栏的 服务器图标 → 复制服务器 ID
  3. 右键点击 您自己的头像 → 复制用户 ID

将您的 服务器 ID 和 用户 ID 与机器人令牌一起保存——您将在下一步中将这三者发送给 OpenClaw。

步骤 6：允许来自服务器成员的私信

为了使配对工作，Discord 需要允许您的机器人向您发送私信。右键点击 服务器图标 → 隐私设置 → 打开 私信。这允许服务器成员（包括机器人）向您发送私信。如果您想使用 Discord 私信与 OpenClaw 交互，请保持此设置启用。如果您只计划使用公会频道，可以在配对后禁用私信。

步骤 7：步骤 0：安全设置您的机器人令牌（请勿在聊天中发送）

您的 Discord 机器人令牌是机密（类似于密码）。在运行 OpenClaw 的机器上设置它，然后再向您的智能体（agent）发送消息。

openclaw config set channels.discord.token '"YOUR_BOT_TOKEN"' --json
openclaw config set channels.discord.enabled true --json
openclaw gateway

如果 OpenClaw 已作为后台服务运行，请改用 openclaw gateway restart。

步骤 8：配置 OpenClaw 并进行配对

在任何现有频道（例如 Telegram）上与您的 OpenClaw 智能体（agent）聊天并告诉它。如果 Discord 是您的第一个频道，请改用 CLI / 配置选项卡。

“我已在配置中设置了 Discord 机器人令牌。请使用用户 ID <user_id> 和服务器 ID <server_id> 完成 Discord 设置。”

步骤 9：批准首次私信配对

等待网关运行，然后在 Discord 中向您的机器人发送私信。它将回复一个配对码。

将配对码发送到您现有频道上的智能体（agent）：

“批准此 Discord 配对码：<CODE>”

配对码在 1 小时后过期。您现在应该能够通过私信在 Discord 中与您的智能体（agent）聊天了。

ℹ️ 令牌解析是账户感知的。配置令牌值优先于环境变量回退。DISCORD_BOT_TOKEN 仅用于默认账户。

推荐：设置公会工作区

私信工作后，您可以将 Discord 服务器设置为完整的工作区，其中每个频道都获得自己的智能体（agent）会话及其自己的上下文。这推荐用于只有您和您的机器人的私人服务器。

步骤 1：将您的服务器添加到公会白名单

这使您的智能体（agent）能够在您服务器上的任何频道中响应，而不仅仅是私信。

“将我的 Discord 服务器 ID <server_id> 添加到公会白名单”

步骤 2：允许无需 @提及 的响应

默认情况下，您的智能体（agent）仅在公会频道中被 @提及 时才会响应。对于私人服务器，您可能希望它对每条消息都做出响应。

“允许我的智能体（agent）在此服务器上响应而无需被 @提及”

步骤 3：为公会频道规划内存

默认情况下，长期记忆（MEMORY.md）仅在私信会话中加载。公会频道不会自动加载 MEMORY.md。

“当我在 Discord 频道中提问时，如果需要来自 MEMORY.md 的长期上下文，请使用 memory_search 或 memory_get。”

现在在您的 Discord 服务器上创建一些频道并开始聊天。您的智能体（agent）可以看到频道名称，并且每个频道都有自己独立的会话——因此您可以设置 #coding、#home、#research 或任何适合您工作流程的频道。

运行时模型

  • 网关拥有 Discord 连接。
  • 回复路由是确定性的：Discord 入站消息回复回 Discord。
  • 默认情况下（session.dmScope=main），直接聊天共享智能体（agent）主会话（agent:main:main）。
  • 公会频道是独立的会话键（agent:<agentId>:discord:channel:<channelId>）。
  • 默认忽略群组私信（channels.discord.dm.groupEnabled=false）。
  • 原生斜杠命令在独立的命令会话中运行（agent:<agentId>:discord:slash:<userId>），同时仍将 CommandTargetSessionKey 携带到路由的对话会话。

论坛频道

Discord 论坛和媒体频道仅接受帖子回复。OpenClaw 支持两种创建方式：

  • 向论坛父级（channel:<forumId>）发送消息以自动创建帖子。帖子标题使用您消息的第一行非空行。
  • 使用 openclaw message thread create 直接创建帖子。对于论坛频道，不要传递 --message-id。

示例：发送到论坛父级以创建帖子

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

示例：显式创建论坛帖子

openclaw message thread create --channel discord --target channel:<forumId> \
  --thread-name "Topic title" --message "Body of the post"

论坛父级不接受 Discord 组件。如果您需要组件，请发送到帖子本身（channel:<threadId>）。

交互式组件

OpenClaw 支持 Discord 组件 v2 容器用于智能体（agent）消息。使用带有 components 负载的消息工具。交互结果作为正常的入站消息路由回智能体（agent），并遵循现有的 Discord replyToMode 设置。支持的块：

  • text、section、separator、actions、media-gallery、file
  • 操作行最多允许 5 个按钮或单个选择菜单
  • 选择类型：string、user、role、mentionable、channel

默认情况下，组件是单次使用的。设置 components.reusable=true 以允许按钮、选择菜单和表单在过期前多次使用。要限制谁可以点击按钮，请在该按钮上设置 allowedUsers（Discord 用户 ID、标签或 *）。配置后，不匹配的用户会收到一个临时拒绝消息。/model 和 /models 斜杠命令会打开一个交互式模型选择器，包含提供商和模型下拉列表以及一个提交步骤。选择器回复是临时的，只有调用用户可以使用它。文件附件：

  • file 块必须指向附件引用（attachment://<filename>）
  • 通过 media/path/filePath 提供附件（单个文件）；使用 media-gallery 处理多个文件
  • 使用 filename 在需要匹配附件引用时覆盖上传名称

模态表单：

  • 添加 components.modal，最多包含 5 个字段
  • 字段类型：text、checkbox、radio、select、role-select、user-select
  • OpenClaw 会自动添加一个触发按钮

示例：

{
  channel: "discord",
  action: "send",
  to: "channel:123456789012345678",
  message: "Optional fallback text",
  components: {
    reusable: true,
    text: "Choose a path",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "Approve",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "Decline", style: "danger" },
        ],
      },
      {
        type: "actions",
        select: {
          type: "string",
          placeholder: "Pick an option",
          options: [
            { label: "Option A", value: "a" },
            { label: "Option B", value: "b" },
          ],
        },
      },
    ],
    modal: {
      title: "Details",
      triggerLabel: "Open form",
      fields: [
        { type: "text", label: "Requester" },
        {
          type: "select",
          label: "Priority",
          options: [
            { label: "Low", value: "low" },
            { label: "High", value: "high" },
          ],
        },
      ],
    },
  },
}

访问控制和路由

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

  • pairing（默认）
  • allowlist
  • open（需要 channels.discord.allowFrom 包含 "*"；旧版：channels.discord.dm.allowFrom）
  • disabled

如果私信策略不是 open，未知用户将被阻止（或在 pairing 模式下提示配对）。多账户优先级：

  • channels.discord.accounts.default.allowFrom 仅适用于 default 账户。
  • 命名账户在其自身的 allowFrom 未设置时继承 channels.discord.allowFrom。
  • 命名账户不继承 channels.discord.accounts.default.allowFrom。

用于传递的私信目标格式：

  • user:<id>
  • <@id> 提及

裸数字 ID 是模糊的，除非提供了明确的用户/频道目标类型，否则会被拒绝。

基于角色的智能体（agent）路由

使用 bindings[].match.roles 通过角色 ID 将 Discord 公会成员路由到不同的智能体（agent）。基于角色的绑定仅接受角色 ID，并在对等或父对等绑定之后、仅公会绑定之前进行评估。如果绑定还设置了其他匹配字段（例如 peer + guildId + roles），则所有配置的字段都必须匹配。

{
  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。
  • commands.native=false 显式清除先前注册的 Discord 原生命令。
  • 原生命令认证使用与正常消息处理相同的 Discord 白名单/策略。
  • 命令可能仍然对未经授权的用户在 Discord UI 中可见；执行时仍会强制执行 OpenClaw 认证并返回“未授权”。

有关命令目录和行为，请参阅斜杠命令。默认斜杠命令设置：

  • ephemeral: true

功能详情

工具和操作门控

Discord 消息操作包括消息传递、频道管理、审核、在线状态和元数据操作。核心示例：

  • 消息传递：sendMessage、readMessages、editMessage、deleteMessage、threadReply
  • 反应：react、reactions、emojiList
  • 审核：timeout、kick、ban
  • 在线状态：setPresence

操作门控位于 channels.discord.actions.* 下。默认门控行为：

操作组默认
reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions启用
roles禁用
moderation禁用
presence禁用

组件 v2 UI

OpenClaw 使用 Discord 组件 v2 进行执行批准和跨上下文标记。Discord 消息操作也可以接受 components 用于自定义 UI（高级；需要 Carbon 组件实例），而旧版 embeds 仍然可用但不推荐。

  • channels.discord.ui.components.accentColor 设置 Discord 组件容器使用的强调色（十六进制）。
  • 使用 channels.discord.accounts.<id>.ui.components.accentColor 按账户设置。
  • 当存在组件 v2 时，embeds 被忽略。

示例：

{
  channels: {
    discord: {
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
    },
  },
}

语音频道

OpenClaw 可以加入 Discord 语音频道进行实时、连续的对话。这与语音消息附件是分开的。要求：

  • 启用原生命令（commands.native 或 channels.discord.commands.native）。
  • 配置 channels.discord.voice。
  • 机器人在目标语音频道中需要连接 + 说话权限。

使用仅限 Discord 的原生命令 /vc join|leave|status 来控制会话。该命令使用账户默认智能体（agent），并遵循与其他 Discord 命令相同的白名单和群组策略规则。自动加入示例：

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
    },
  },
}

注意：

  • voice.tts 仅覆盖语音播放的 messages.tts。
  • 语音转录轮次从 Discord allowFrom（或 dm.allowFrom）派生所有者状态；非所有者说话者无法访问仅限所有者的工具（例如 gateway 和 cron）。
  • 默认启用语音；设置 channels.discord.voice.enabled=false 以禁用它。
  • voice.daveEncryption 和 voice.decryptionFailureTolerance 传递给 @discordjs/voice 加入选项。
  • 如果未设置，@discordjs/voice 默认值为 daveEncryption=true 和 decryptionFailureTolerance=24。
  • OpenClaw 还会监视接收解密失败，并在短时间内重复失败后通过离开/重新加入语音频道来自动恢复。
  • 如果接收日志重复显示 DecryptionFailed(UnencryptedWhenPassthroughDisabled)，这可能是上游 @discordjs/voice 接收错误，在 discord.js #11419 中跟踪。

语音消息

Discord 语音消息显示波形预览，需要 OGG/Opus 音频和元数据。OpenClaw 会自动生成波形，但需要网关主机上可用的 ffmpeg 和 ffprobe 来检查和转换音频文件。要求和约束：

  • 提供本地文件路径（URL 被拒绝）。
  • 省略文本内容（Discord 不允许在同一负载中同时包含文本和语音消息）。
  • 接受任何音频格式；需要时 OpenClaw 会转换为 OGG/Opus。

示例：

message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)

故障排除

配置参考要点

主要参考：

高信号 Discord 字段：

  • startup/auth: enabled, token, accounts.*, allowBots
  • policy: groupPolicy, dm.*, guilds.*, guilds.*.channels.*
  • command: commands.native, commands.useAccessGroups, configWrites, slashCommand.*
  • event queue: eventQueue.listenerTimeout（监听器预算）, eventQueue.maxQueueSize, eventQueue.maxConcurrency
  • inbound worker: inboundWorker.runTimeoutMs
  • reply/history: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
  • delivery: textChunkLimit, chunkMode, maxLinesPerMessage
  • streaming: streaming（旧别名：streamMode）, draftChunk, blockStreaming, blockStreamingCoalesce
  • media/retry: mediaMaxMb, retry
    • mediaMaxMb 限制 Discord 出站上传（默认：8MB）
  • actions: actions.*
  • presence: activity, status, activityType, activityUrl
  • UI: ui.components.accentColor
  • features: threadBindings, 顶层 bindings[]（type: "acp"）, pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

安全与运维

  • 将机器人令牌视为机密（在受管环境中优先使用 DISCORD_BOT_TOKEN）。
  • 授予最小权限的 Discord 权限。
  • 若命令部署/状态过期，请重启网关并用 openclaw channels status --probe 重新检查。

相关链接

BlueBubblesFeishu