Discord

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

快速设置

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

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

DISCORD_BOT_TOKEN=...

{
  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",
        },
      },
    },
  },
}

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,
        },
      },
    },
  },
}

​

运行时模型

• Gateway 负责 Discord 连接。
• 回复路由是确定性的：Discord 的入站回复会回到 Discord。
• Discord 服务器/频道元数据会作为不受信任的上下文添加到模型提示中，而不是作为对用户可见的回复前缀。如果模型将该封装复制回去，OpenClaw 会从出站回复以及未来的回放上下文中剥离复制的元数据。
• 默认情况下（session.dmScope=main），直接聊天共享代理主会话（agent:main:main）。
• 服务器频道是隔离的会话键（agent:<agentId>:discord:channel:<channelId>）。
• 群组 DM 默认被忽略（channels.discord.dm.groupEnabled=false）。
• 原生斜杠命令在隔离的命令会话中运行（agent:<agentId>:discord:slash:<userId>），同时仍携带指向路由会话的 CommandTargetSessionKey。
• 仅文本的 cron/heartbeat 宣告发往 Discord 时，会使用最终的、用户可见的助手答案一次。媒体和结构化组件载荷在代理发出多个可交付载荷时仍保持多消息。

​

论坛频道

• 向论坛父频道发送消息（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"

​

交互式组件

• 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: "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" },
          ],
        },
      ],
    },
  },
}

​

访问控制与路由

{
  accessGroups: {
    operators: {
      type: "message.senders",
      members: {
        "*": ["global-owner-id"],
        discord: ["discord:123456789012345678"],
        telegram: ["987654321"],
      },
    },
  },
  channels: {
    discord: {
      dmPolicy: "allowlist",
      allowFrom: ["accessGroup:operators"],
    },
  },
}

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

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

{
  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 slash 命令注册和清理。先前注册的命令可能仍会在 Discord 中可见，直到你将它们从 Discord 应用中移除。
• 原生命令授权使用与普通消息处理相同的 Discord allowlist/策略。
• 对于未授权用户，命令仍可能在 Discord UI 中可见；执行时仍会强制 OpenClaw 授权并返回 “not authorized”。

• ephemeral: true

​

功能细节

{
  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,
        spawnSessions: true,
        defaultSpawnContext: "fork",
      },
    },
  },
}

{
  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: {
      mentionAliases: {
        Vladislava: "123456789012345678",
      },
      accounts: {
        ops: {
          mentionAliases: {
            OpsLead: "234567890123456789",
          },
        },
      },
    },
  },
}

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

{
  channels: {
    discord: {
      activity: "Focus time",
      activityType: 4,
    },
  },
}

{
  channels: {
    discord: {
      activity: "Live coding",
      activityType: 1,
      activityUrl: "https://twitch.tv/openclaw",
    },
  },
}

{
  channels: {
    discord: {
      autoPresence: {
        enabled: true,
        intervalMs: 30000,
        minUpdateIntervalMs: 15000,
        exhaustedText: "token exhausted",
      },
    },
  },
}

​

工具与动作门禁

• 消息：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",
        },
      },
    },
  },
}

​

语音

​

语音频道

1. 在 Discord Developer Portal 中启用 Message Content Intent。
2. 当使用角色/用户允许名单时，启用 Server Members Intent。
3. 使用 bot 和 applications.commands 范围邀请机器人。
4. 在目标语音频道中授予 Connect、Speak、Send Messages 和 Read Message History 权限。
5. 启用原生命令（commands.native 或 channels.discord.commands.native）。
6. 配置 channels.discord.voice。

/vc join channel:<voice-channel-id>
/vc status
/vc leave

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        model: "openai/gpt-5.4-mini",
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        connectTimeoutMs: 30000,
        reconnectGraceMs: 15000,
        tts: {
          provider: "openai",
          openai: { voice: "onyx" },
        },
      },
    },
  },
}

• voice.tts 仅覆盖语音播放所用的 messages.tts。
• voice.model 仅覆盖 Discord 语音频道响应所使用的 LLM。保持未设置可继承路由后的 agent 模型。
• STT 使用 tools.media.audio；voice.model 不影响转写。
• 逐频道的 Discord systemPrompt 覆盖会应用于该语音频道的语音转写轮次。
• 语音转写轮次会从 Discord allowFrom（或 dm.allowFrom）派生所有者状态；非所有者说话者无法访问仅所有者可用的工具（例如 gateway 和 cron）。
• 对于仅文本配置，Discord 语音是可选启用的；设置 channels.discord.voice.enabled=true（或保留现有的 channels.discord.voice 块）即可启用 /vc 命令、语音运行时和 GuildVoiceStates 网关 intent。
• channels.discord.intents.voiceStates 可以显式覆盖 voice-state intent 订阅。保持未设置可让该 intent 跟随实际的语音启用状态。
• voice.daveEncryption 和 voice.decryptionFailureTolerance 会透传到 @discordjs/voice 的 join 选项。
• 如果未设置，@discordjs/voice 的默认值为 daveEncryption=true 和 decryptionFailureTolerance=24。
• voice.connectTimeoutMs 控制 /vc join 和自动加入尝试时，@discordjs/voice 初始 Ready 等待时长。默认值：30000。
• voice.reconnectGraceMs 控制 OpenClaw 在销毁断开的语音会话之前，等待其开始重新连接的时间。默认值：15000。
• OpenClaw 还会监控接收解密失败，并在短时间内重复失败后通过离开/重新加入语音频道来自行恢复。
• 如果在更新后接收日志持续出现 DecryptionFailed(UnencryptedWhenPassthroughDisabled)，请收集依赖报告和日志。捆绑的 @discordjs/voice 版本包含 discord.js PR #11449 中的上游 padding 修复，该修复关闭了 discord.js issue #11419。

• Discord PCM 捕获会转换为 WAV 临时文件。
• tools.media.audio 负责 STT，例如 openai/gpt-4o-mini-transcribe。
• 转写内容会通过 Discord ingress 和路由传递，而响应 LLM 会在语音输出策略下运行，该策略会隐藏 agent 的 tts 工具并请求返回文本，因为 Discord 语音负责最终的 TTS 播放。
• 当设置了 voice.model 时，它只会覆盖该语音频道回合的响应 LLM。
• voice.tts 会基于 messages.tts 进行合并；生成的音频会在加入的频道中播放。

​

语音消息

• 提供一个本地文件路径（不接受 URL）。
• 省略文本内容（Discord 会拒绝同一 payload 中同时包含文本和语音消息）。
• 接受任何音频格式；OpenClaw 会按需转换为 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,
          },
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      accounts: {
        mantis: {
          // 螳螂只会在其他机器人提及她时监听它们。
          allowBots: "mentions",
        },
        molty: {
          // Molty 会监听所有机器人发送的 Discord 消息。
          allowBots: true,
          mentionAliases: {
            // 允许 Molty 写出 "@Mantis" 并发送真正的 Discord 提及。
            Mantis: "MANTIS_DISCORD_USER_ID",
          },
        },
      },
    },
  },
}

​

配置参考

​

安全与运维

• 将 bot token 视为密钥（在受监管环境中优先使用 DISCORD_BOT_TOKEN）。
• 授予最小权限的 Discord 权限。
• 如果命令部署/状态已过期，重启 gateway，并使用 openclaw channels status --probe 重新检查。

​

相关内容