​

Discord（机器人 API）

​

快速设置

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

{
  channels: {
    discord: {
      enabled: true,
      token: "YOUR_BOT_TOKEN",
    },
  },
}

DISCORD_BOT_TOKEN=...

openclaw pairing list discord
openclaw pairing approve discord <CODE>

​

推荐：设置公会工作区

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

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

​

运行时模型

• 网关拥有 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 以路由至对话会话。

​

论坛频道

• 向论坛父频道 (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 "帖子内容"

​

交互组件

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

• 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: "可选回退文本",
  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" },
          ],
        },
      ],
    },
  },
}

​

访问控制与路由

{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        "123456789012345678": {
          requireMention: true,
          ignoreOtherMentions: true,
          users: ["987654321098765432"],
          roles: ["123456789012345678"],
          channels: {
            general: { allow: true },
            help: { allow: true, requireMention: true },
          },
        },
      },
    },
  },
}

​

基于角色的代理路由

{
  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

​

功能详情

{
  channels: {
    discord: {
      streaming: "partial",
    },
  },
}

{
  channels: {
    discord: {
      streaming: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph",
      },
    },
  },
}

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // 需选择加入
      },
    },
  },
}

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      configWrites: false,
    },
  },
}

{
  channels: {
    discord: {
      proxy: "http://proxy.example:8080",
    },
  },
}

{
  channels: {
    discord: {
      accounts: {
        primary: {
          proxy: "http://proxy.example:8080",
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      pluralkit: {
        enabled: true,
        token: "pk_live_...", // 可选，私有系统需提供
      },
    },
  },
}

{
  channels: {
    discord: {
      status: "idle",
    },
  },
}

{
  channels: {
    discord: {
      activity: "专注时间",
      activityType: 4,
    },
  },
}

{
  channels: {
    discord: {
      activity: "直播编程",
      activityType: 1,
      activityUrl: "https://twitch.tv/openclaw",
    },
  },
}

{
  channels: {
    discord: {
      autoPresence: {
        enabled: true,
        intervalMs: 30000,
        minUpdateIntervalMs: 15000,
        exhaustedText: "令牌耗尽",
      },
    },
  },
}

​

工具和操作门控

• 消息：sendMessage，readMessages，editMessage，deleteMessage，threadReply
• 表情：react，reactions，emojiList
• 审核：timeout，kick，ban
• 在线状态：setPresence

​

Components v2 UI

• channels.discord.ui.components.accentColor 设置 Discord 组件容器的强调色（十六进制）。
• 也可为账号单独设置：channels.discord.accounts.<id>.ui.components.accentColor。
• 存在 components v2 时忽略 embeds。

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

​

语音频道

• 启用原生命令（commands.native 或 channels.discord.commands.native）。
• 配置 channels.discord.voice。
• 此机器人需在目标语音频道具备连接及发言权限。

{
  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。

​

语音消息

• 提供本地文件路径（拒绝 URL）。
• 省略文本内容（Discord 不允许文本+语音消息同载荷）。
• 接受任意音频格式，必要时自动转换为 OGG/Opus。

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

​

故障排除

openclaw doctor
openclaw channels status --probe
openclaw logs --follow

{
  channels: {
    discord: {
      accounts: {
        default: {
          eventQueue: {
            listenerTimeout: 120000,
          },
          inboundWorker: {
            runTimeoutMs: 1800000,
          },
        },
      },
    },
  },
}

​

配置参考指引

• 配置参考 - Discord

• 启动/授权：enabled，token，accounts.*，allowBots
• 策略：groupPolicy，dm.*，guilds.*，guilds.*.channels.*
• 命令：commands.native，commands.useAccessGroups，configWrites，slashCommand.*
• 事件队列：eventQueue.listenerTimeout（监听器预算），eventQueue.maxQueueSize，eventQueue.maxConcurrency
• 入站工作线程：inboundWorker.runTimeoutMs
• 回复/历史：replyToMode，historyLimit，dmHistoryLimit，dms.*.historyLimit
• 交付：textChunkLimit，chunkMode，maxLinesPerMessage
• 流式：streaming（旧别名：streamMode），draftChunk，blockStreaming，blockStreamingCoalesce
• 媒体/重试：mediaMaxMb，retry
• 操作：actions.*
• 在线状态：activity，status，activityType，activityUrl
• UI：ui.components.accentColor
• 功能：threadBindings，顶层绑定 bindings[] （type: "acp"），pluralkit，execApprovals，intents，agentComponents，heartbeat，responsePrefix

​

安全与运维

• 视机器人令牌为机密（受监督环境推荐使用 DISCORD_BOT_TOKEN）。
• 赋予最小权限的 Discord 权限。
• 如命令部署或状态信息过期，重启网关并用 openclaw channels status --probe 重新检查。

​

相关链接

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