Discord

Discord（机器人 API）

状态：已通过官方 Discord 网关准备好私聊和服务器频道支持。

快速设置

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

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

推荐：设置服务器工作区

私聊正常工作后，你可以将 Discord 服务器设置为完整的工作区，每个频道获得自己的代理会话和上下文。建议在只有你和机器人的私人服务器上使用此设置。

现在在你的 Discord 服务器上创建一些频道并开始聊天。代理可以看到频道名称，每个频道都有自己的隔离会话——因此你可以设置 #coding、#home、#research 或任何适合你工作流的频道。

运行时模型

• 网关拥有 Discord 连接。
• 回复路由是确定性的：Discord 入站回复回 Discord。
• 默认情况下（session.dmScope=main），直接聊天共享代理主会话（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 "主题标题\n正文内容"

示例：显式创建论坛主题

openclaw message thread create --channel discord --target channel:<forumId> \
  --thread-name "主题标题" --message "正文内容"

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

交互式组件

OpenClaw 支持用于代理消息的 Discord 组件 v2 容器。使用带有 components 负载的消息工具。交互结果作为普通入站消息路由回代理，并遵循现有的 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 在上传名称应与附件引用匹配时覆盖

模态表单：

• 添加带有最多 5 个字段的 components.modal
• 字段类型：text、checkbox、radio、select、role-select、user-select
• OpenClaw 自动添加触发按钮

示例：

{
  channel: "discord",
  action: "send",
  to: "channel:123456789012345678",
  message: "可选回退文本",
  components: {
    reusable: true,
    text: "选择路径",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "批准",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "拒绝", style: "danger" },
        ],
      },
      {
        type: "actions",
        select: {
          type: "string",
          placeholder: "选择一个选项",
          options: [
            { label: "选项 A", value: "a" },
            { label: "选项 B", value: "b" },
          ],
        },
      },
    ],
    modal: {
      title: "详情",
      triggerLabel: "打开表单",
      fields: [
        { type: "text", label: "请求者" },
        {
          type: "select",
          label: "优先级",
          options: [
            { label: "低", value: "low" },
            { label: "高", value: "high" },
          ],
        },
      ],
    },
  },
}

访问控制和路由

基于角色的代理路由

使用 bindings[].match.roles 根据角色 ID 将 Discord 服务器成员路由到不同的代理。基于角色的绑定仅接受角色 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.* 下。

默认门行为：

组件 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 控制会话。该命令使用账户默认代理并遵循与其他 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 接收 bug，在 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

高信号 Discord 字段：

• 启动/认证：enabled、token、accounts.*、allowBots
• 策略：groupPolicy、dm.*、guilds.*、guilds.*.channels.*
• 命令：commands.native、commands.useAccessGroups、configWrites、slashCommand.*
• 事件队列：eventQueue.listenerTimeout（规范）、eventQueue.maxQueueSize、eventQueue.maxConcurrency
• 回复/历史：replyToMode、historyLimit、dmHistoryLimit、dms.*.historyLimit
• 传递：textChunkLimit、chunkMode、maxLinesPerMessage
• 流式传输：streaming（旧版别名：streamMode）、draftChunk、blockStreaming、blockStreamingCoalesce
• 媒体/重试：mediaMaxMb、retry
• 动作：actions.*
• 在线状态：activity、status、activityType、activityUrl
• UI：ui.components.accentColor
• 功能：pluralkit、execApprovals、intents、agentComponents、heartbeat、responsePrefix

安全和操作

• 将机器人令牌视为机密（在监督环境中首选 DISCORD_BOT_TOKEN）。
• 授予最低特权的 Discord 权限。
• 如果命令部署/状态过时，重启网关并使用 openclaw channels status --probe 重新检查。

相关

• 配对
• 频道路由
• 多代理路由
• 故障排除
• 斜杠命令