Discord

​

快速设置

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>

​

推荐：设置 guild 工作区

{
  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 的 guild／channel 元数据作为不可信上下文添加到模型提示中，而不是作为用户可见的回复前缀。如果模型将该封装复制回去，OpenClaw 会从出站回复以及未来的回放上下文中剥离复制的元数据。
• 默认情况下（session.dmScope=main），直接聊天共享代理主会话（agent:main:main）。
• Guild 频道使用隔离的会话键（agent:<agentId>:discord:channel:<channelId>）。
• 群聊 DM 默认被忽略（channels.discord.dm.groupEnabled=false）。
• 原生斜杠命令在隔离的命令会话中运行（agent:<agentId>:discord:slash:<userId>），同时仍然携带 CommandTargetSessionKey 到路由后的对话会话。
• 仅文本的 cron／heartbeat 宣告投递到 Discord 时会折叠为最终的、对助手可见的答案，并只发送一次。媒体和结构化组件负载在代理生成多个可投递负载时仍保持多条消息。

​

论坛频道

• 向论坛父频道（channel:<forumId>）发送消息以自动创建线程。线程标题为消息的第一行非空内容（会截断为 Discord 100 个字符的线程名称限制）。
• 使用 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: "选择一条路径",
    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" },
          ],
        },
      ],
    },
  },
}

​

访问控制与路由

{
  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: { enabled: true },
            help: { enabled: true, requireMention: true },
          },
        },
      },
    },
  },
}

​

Guild 频道映射是允许名单

{
  channels: {
    discord: {
      guilds: {
        YOUR_SERVER_ID: {
          requireMention: true,
          users: ["YOUR_USER_ID"],
          channels: {
            // 常驻房间：其中的每个人都可以和 bot 说话，不需要提及
            YOUR_CHANNEL_ID: { enabled: true, requireMention: false, users: ["*"] },
            // 其他所有频道都保持 guild 默认值
            "*": { enabled: true, requireMention: true },
          },
        },
      },
    },
  },
}

​

基于角色的 agent 路由

{
  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 允许列表／策略。
• 对于未授权用户，命令在 Discord UI 中仍可能可见；执行时会强制进行 OpenClaw 授权并回复“未授权”。
• 默认 slash 命令设置：ephemeral: true（channels.discord.slashCommand.ephemeral）。

​

功能详情

{
  channels: {
    discord: {
      suppressEmbeds: false,
    },
  },
}

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          maxLines: 8,
          maxLineChars: 120,
          toolProgress: false,
          commentary: false,
        },
      },
    },
  },
}

{
  "channels": {
    "discord": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

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

{
  agents: {
    entries: {
      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: {
      intents: { presence: true },
      guilds: {
        "111111111111111111": {
          presenceEvents: {
            channelId: "222222222222222222",
            users: ["333333333333333333"], // 可选；进一步缩小可见该频道的用户范围
            reconnectSuppressSeconds: 300, // 可选；新会话静默窗口（0 表示禁用）
            burstLimit: 8, // 可选；每个突发窗口内的最大事件数
            burstWindowSeconds: 60, // 可选；滑动突发检测窗口
          },
        },
      },
    },
  },
}

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

​

工具与操作门控

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

​

组件 v2 用户界面

• channels.discord.agentComponents.ttlMs 控制已发送的 Discord 组件回调保持注册的时长（默认值为 1800000，最大值为 86400000）。按账户设置：channels.discord.accounts.<id>.agentComponents.ttlMs。
• 存在组件 v2 时会忽略 embeds。
• 默认会抑制纯 URL 预览。当单个外发链接需要展开时，请在消息动作中设置 suppressEmbeds: false。

​

语音

​

语音频道

1. 在 Discord Developer Portal 中启用 Message Content Intent。
2. 当使用 role/user allowlist 时，启用 Server Members Intent。
3. 使用 bot 和 applications.commands scopes 邀请机器人。
4. 在目标 voice channel 中授予 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

openclaw channels capabilities --channel discord --target channel:<voice-channel-id>

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        model: "openai/gpt-5.6-sol",
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        allowedChannels: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        connectTimeoutMs: 30000,
        reconnectGraceMs: 15000,
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2.1",
          speakerVoice: "cedar",
        },
      },
    },
  },
}

• 对于仅文本配置，Discord voice 默认是可选启用的；设置 channels.discord.voice.enabled=true（或保留现有的 channels.discord.voice 块）即可启用 /vc 命令、语音运行时以及 GuildVoiceStates 网关 intent。channels.discord.intents.voiceStates 可以显式覆盖 intent 订阅；若留空，则跟随实际生效的语音启用状态。
• voice.mode 控制对话路径。默认值是 agent-proxy：一个实时语音前端负责处理轮次时机、中断和播放，通过 openclaw_agent_consult 将实质性工作委派给路由后的 OpenClaw agent，并将结果视为来自该说话者的 Discord 文字提示。stt-tts 保留旧的批处理 STT + TTS 流程。bidi 让实时模型直接对话，同时通过 openclaw_agent_consult 暴露 OpenClaw 大脑。
• voice.agentSession 控制哪个 OpenClaw 会话接收语音轮次。保持未设置时使用语音频道自身的会话，或者设置 { mode: "target", target: "channel:<text-channel-id>" }，让语音频道充当现有 Discord 文本频道会话（例如 #maintainers）的麦克风／扬声器扩展。
• voice.model 会覆盖用于 Discord 语音回复和实时咨询的 OpenClaw agent 大脑。若留空，则继承所路由的 agent 模型。它与 voice.realtime.model 相互独立。
• voice.followUsers 允许机器人跟随选定用户加入、移动和离开 Discord 语音。参见 跟随语音中的用户。
• agent-proxy 通过 discord-voice 路由语音，它会为说话者和目标会话保留正常的 owner/tool 授权，但会隐藏 agent 的 tts 工具，因为 Discord voice 自己负责播放。默认情况下，agent-proxy 会为 owner 说话者的 consult 提供完全等同 owner 的工具访问权限（voice.realtime.toolPolicy: "owner"），并强烈倾向于在给出实质性回答前先咨询 OpenClaw agent（voice.realtime.consultPolicy: "always"）。在默认的 always 模式下，实时层不会在 consult 回答前自动播放填充语音；它会捕获并转写语音，然后播放路由后的 OpenClaw 回答。如果多个强制 consult 回答在 Discord 仍在播放第一个回答时完成，后续的逐字回答会排队，直到播放空闲后再输出，而不是在句中替换语音。
• 在 stt-tts 模式下，STT 使用 tools.media.audio；voice.model 不影响转录。
• 在实时模式下，voice.realtime.provider、voice.realtime.model 和 voice.realtime.speakerVoice 用于配置实时音频会话。对于 OpenAI Realtime 2.1 搭配 Codex brain，可使用 voice.realtime.model: "gpt-realtime-2.1" 和 voice.model: "openai/gpt-5.6-sol"。
• 默认情况下，实时语音模式会在 realtime provider 指令中包含较小的 IDENTITY.md、USER.md 和 SOUL.md 配置文件，以便快速直接轮次保持与路由后的 OpenClaw agent 相同的身份、用户上下文和人格。将 voice.realtime.bootstrapContextFiles 设为其子集可以自定义这一点，或设为 [] 以禁用。仅支持这些配置文件；AGENTS.md 仍保留在正常的 agent 上下文中。注入的 profile 上下文不会替代 openclaw_agent_consult 来处理工作区工作、当前事实、记忆检索或工具驱动操作。
• 在 OpenAI agent-proxy 实时模式下，wake-name 门控会默认根据房间情况自适应：一个人时可以自然说话而无需 wake name，两个或更多人时则必须在轮次开头或结尾带上 wake name。其他机器人不计入人数。设置 voice.realtime.requireWakeName: true 可始终要求 wake name，或设为 false 以从不要求。配置的 wake name 必须是一个或两个词。若 voice.realtime.wakeNames 未设置，OpenClaw 会使用所路由 agent 的 name 加上 OpenClaw，若仍无则回退为 agent id 加上 OpenClaw。启用的 wake-name 门控会禁用 realtime provider 自动响应，将被接受的轮次通过 OpenClaw agent consult 路径处理，并在最终转录到达前，当从部分转录中识别出前置 wake name 时发出简短语音确认。该策略会随着实时加入和离开动态变化，无需重新连接语音。
• OpenAI realtime provider 支持当前 Realtime 2 事件名称以及用于输出音频和转录事件的旧版 Codex 兼容别名，因此兼容的 provider 快照可以在不丢失助手音频的情况下发生漂移。
• voice.realtime.bargeIn 控制 Discord 说话开始事件是否会中断正在播放的实时语音。若未设置，则遵循 realtime provider 的输入音频中断设置。
• voice.realtime.minBargeInAudioEndMs 控制 OpenAI realtime barge-in 截断音频前，助手播放至少持续的最小时长。默认值：250。在回声较低的房间中可设为 0 以立即中断，或在扬声器回声较重的环境中提高该值。
• voice.tts 仅覆盖 stt-tts 语音播放的 tts；实时模式改用 voice.realtime.speakerVoice。若要在 Discord 播放中使用 OpenAI voice，请设置 voice.tts.provider: "openai"，并在 voice.tts.providers.openai.speakerVoice 下选择一个 Text-to-speech 语音。对于当前 OpenAI TTS 模型，cedar 是一个不错的男性音色选择。
• 按频道的 Discord systemPrompt 覆盖会应用于该语音频道的语音转录轮次。
• 当 OpenClaw 加入语音频道时，路由后的 agent 会话会收到一个带有当前参与者名单的静默系统事件。之后参与者的加入和离开会更新该会话，但不会触发非请求式的口头回复；Discord 显示名称被视为不可信标签。授权的语音轮次也会接收到新的参与者名单快照。
• 语音转录轮次和 /vc 命令使用 commands.ownerAllowFrom 中的 Discord 条目来判断 owner 状态。当未配置 Discord 命令 owner 时，所选 Discord 账号的 allowFrom（或旧的 dm.allowFrom）仍可授权语音访问，但不会授予 owner 状态。Agent 工具可见性遵循所路由会话配置的工具策略。
• 如果 voice.autoJoin 中同一个 guild 有多个条目，OpenClaw 会加入该 guild 最后配置的频道。
• voice.allowedChannels 是可选的驻留 allowlist。保持未设置可允许 /vc join 加入任意已授权的 Discord 语音频道。设置后，/vc join、启动时自动加入以及机器人语音状态移动都将限制为列表中的 { guildId, channelId } 条目。将其设为空数组可拒绝所有 Discord 语音加入。如果 Discord 将机器人移动到 allowlist 之外，OpenClaw 会离开该频道，并在可用时重新加入配置的自动加入目标。
• voice.daveEncryption 和 voice.decryptionFailureTolerance 会透传给 @discordjs/voice 的 join 选项；上游默认值为 daveEncryption=true 和 decryptionFailureTolerance=24。
• OpenClaw 使用捆绑的 libopus-wasm 编解码器来接收 Discord 语音并播放实时原始 PCM。它附带固定版本的 libopus WebAssembly 构建，不需要本地 opus addon。
• voice.connectTimeoutMs 控制 /vc join 和自动加入尝试时 @discordjs/voice 的初始 Ready 等待时间。默认值：30000。
• voice.reconnectGraceMs 控制 OpenClaw 在销毁断开连接的语音会话前，会等待其开始重连的时长。默认值：15000。
• 在 stt-tts 模式下，语音播放不会因为其他用户开始说话就停止。为了避免反馈回路，OpenClaw 会在 TTS 播放期间忽略新的语音捕获；请在播放结束后再说下一轮。
• 在实时模式下，扬声器通过开放麦克风产生的回声可能看起来像 barge-in 并中断播放。对于回声较重的 Discord 房间，设置 voice.realtime.providers.openai.interruptResponseOnInputAudio: false 以防 OpenAI 在输入音频上自动中断。如果你仍希望 Discord 的说话开始事件中断当前播放，再添加 voice.realtime.bargeIn: true。OpenAI realtime bridge 会把短于 voice.realtime.minBargeInAudioEndMs 的播放截断视为可能的回声／噪声并忽略，而不是清除 Discord 播放。
• voice.captureSilenceGraceMs 控制 OpenClaw 在 Discord 报告说话者停止后，等待多久再为 STT 完成该音频片段。默认值：2000；如果 Discord 将正常停顿切分成碎片化的部分转录，可适当调高。
• 当 ElevenLabs 是所选的 TTS provider 时，Discord 语音播放会使用流式 TTS，并从 provider 的响应流开始播放。不支持流式的 provider 会回退到合成的临时文件路径。
• OpenClaw 会监视接收解密失败，并在短时间内多次失败后，通过离开／重新加入语音频道进行自动恢复。
• 如果接收日志在更新后持续出现 DecryptionFailed(UnencryptedWhenPassthroughDisabled)，请收集依赖报告和日志。捆绑的 @discordjs/voice 版本包含 discord.js PR #11449 中的上游 padding 修复，该修复关闭了 discord.js issue #11419。
• 出现 The operation was aborted 的接收事件是 OpenClaw 完成某个已捕获的说话者片段时的预期行为；它们是详细诊断信息，不是警告。
• 详细的 Discord 语音日志会为每个被接受的说话者片段提供一个有边界的单行 STT 转录预览，因此调试时可以同时看到用户端和 agent 回复端，而不会倾倒无限制的转录文本。
• 在 agent-proxy 模式下，强制 consult 回退会跳过可能不完整的转录片段，例如以 ... 结尾的文本、以 “and” 之类的尾随连接词结尾的文本，以及明显不可操作的结尾语句如 “be right back” 或 “bye”。当这避免了一个过时的排队回答时，日志会显示 forced agent consult skipped reason=...。

​

在语音中跟随用户

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        followUsersEnabled: true,
        followUsers: ["discord:123456789012345678"],
        allowedChannels: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
      },
    },
  },
}

• followUsers 接受原始 Discord 用户 ID 和 discord:<id> 值。OpenClaw 在匹配语音状态事件之前会规范化这两种形式。
• 当配置了 followUsers 时，followUsersEnabled 默认值为 true。将其设为 false 可保留已保存列表，但停止自动语音跟随。
• followUsers 只控制语音驻留。它不会授予发言者权限或所有者权限；请分别配置 commands.ownerAllowFrom 以及公会或频道的用户和角色。
• 当被跟随用户加入一个允许的语音频道时，OpenClaw 会加入该频道。当用户移动时，OpenClaw 也会随之移动。当当前被跟随用户断开连接时，OpenClaw 会离开。
• 如果同一公会中有多个被跟随用户，而当前活跃的被跟随用户离开，OpenClaw 会在离开公会前先移动到另一个被跟踪用户所在的频道。如果多个被跟随用户同时移动，则以最新观察到的语音状态事件为准。
• allowedChannels 仍然生效。位于不允许频道中的被跟随用户会被忽略，而一个跟随拥有的会话会移动到另一个被跟随用户那里，或者离开。
• OpenClaw 会在启动时以及以受限间隔校正遗漏的语音状态事件。校正会采样已配置的公会，并对每次运行的 REST 查询数量设上限，因此非常大的 followUsers 列表可能需要超过一个间隔才能收敛。
• 如果 Discord 或管理员在机器人跟随用户时移动了机器人，OpenClaw 会重建语音会话，并在目标位置允许时保留跟随所有权。如果机器人被移动到 allowedChannels 之外，OpenClaw 会离开，并在存在已配置目标时重新加入该目标。
• DAVE 接收恢复在连续解密失败后可能会离开并重新加入同一频道。跟随拥有的会话会在该恢复路径中保留其跟随所有权，因此稍后被跟随用户断开时仍会离开频道。

• 对于个人或 operator 设置，如果希望机器人在你进入语音时自动跟随，就使用 followUsers。
• 对于固定房间机器人，如果即使没有被跟踪用户在语音中也应始终存在，就使用 autoJoin。
• 对于一次性加入，或自动语音存在会让人意外的房间，就使用 /vc join。

• 语音接收日志会显示 discord voice: opus decoder: libopus-wasm。
• 实时播放会在把数据包交给 @discordjs/voice 之前，使用同一个内置的 libopus-wasm 包将原始 48 kHz 立体声 PCM 编码为 Opus。
• 文件和 provider 流播放会先用 ffmpeg 转码为原始 48 kHz 立体声 PCM，然后使用 libopus-wasm 生成发送到 Discord 的 Opus 数据包流。

• Discord PCM 捕获会转换为一个 WAV 临时文件。
• tools.media.audio 负责 STT，例如 openai/gpt-4o-mini-transcribe。
• 转写会通过 Discord ingress 和 routing 发送，而响应 LLM 会使用一个语音输出策略：隐藏 agent 的 tts 工具并要求返回文本，因为 Discord 语音负责最终的 TTS 播放。
• voice.model 在设置时，只会覆盖此语音频道轮次的响应 LLM。
• voice.tts 会覆盖合并到 tts 之上；支持流式的 provider 会直接把音频送给播放器，否则生成的音频文件会在已加入的频道中播放。

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        model: "openai/gpt-5.6-sol",
        followUsersEnabled: true,
        followUsers: ["123456789012345678"],
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2.1",
          speakerVoice: "cedar",
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        mode: "stt-tts",
        model: "openai/gpt-5.4-mini",
        tts: {
          provider: "openai",
          providers: {
            openai: {
              model: "gpt-4o-mini-tts",
              speakerVoice: "cedar",
            },
          },
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        mode: "bidi",
        model: "openai/gpt-5.6-sol",
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2.1",
          speakerVoice: "cedar",
          toolPolicy: "safe-read-only",
          consultPolicy: "always",
        },
      },
    },
  },
}

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        mode: "agent-proxy",
        model: "openai/gpt-5.6-sol",
        agentSession: {
          mode: "target",
          target: "channel:123456789012345678",
        },
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2.1",
          speakerVoice: "cedar",
        },
      },
    },
  },
}

• target: "channel:123456789012345678" 通过 Discord 文本频道会话路由。
• target: "123456789012345678" 会被视为频道目标。
• target: "dm:123456789012345678" 或 target: "user:123456789012345678" 通过该私信会话路由。

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        mode: "bidi",
        model: "openai/gpt-5.6-sol",
        realtime: {
          provider: "openai",
          model: "gpt-realtime-2.1",
          speakerVoice: "cedar",
          bargeIn: true,
          minBargeInAudioEndMs: 500,
          consultPolicy: "always",
          providers: {
            openai: {
              interruptResponseOnInputAudio: false,
            },
          },
        },
      },
    },
  },
}

• 加入时：discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• realtime 开始时：discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• 有说话者音频时：discord voice: realtime speaker turn opened ...、discord voice: realtime input audio started ... outputAudioMs=... outputActive=...，以及 discord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=...
• 跳过陈旧语音时：discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... 或 reason=non-actionable-closing ...
• realtime 响应完成时：discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• 播放停止／重置时：discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• realtime consult 时：discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• agent 答复时：discord voice: agent turn answer ...
• 排队的精确语音时：discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=...，随后是 discord voice: realtime exact speech dequeued reason=player-idle ...
• 检测到 barge-in 时：discord voice: realtime barge-in detected source=speaker-start ... 或 discord voice: realtime barge-in detected source=active-speaker-audio ...，随后是 discord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=...
• realtime 中断时：discord voice: realtime model interrupt requested client:response.cancel reason=barge-in，随后会出现 discord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=... 或 discord voice: realtime model interrupt confirmed server:response.done status=cancelled ...
• 忽略回声／噪音时：discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• 禁用 barge-in 时：discord voice: realtime capture ignored during playback (barge-in disabled) ...
• 空闲播放时：discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

1. realtime audio playback started 表示 Discord 已开始播放 assistant 音频。从此时起，bridge 开始统计 assistant 输出 chunk、Discord PCM 字节、provider realtime 字节以及合成音频时长。
2. realtime speaker turn opened 标记 Discord 中某个说话者变为活跃状态。如果播放已在进行且启用了 bargeIn，这之后可能会出现 barge-in detected source=speaker-start。
3. realtime input audio started 标记该说话者轮次收到的第一帧实际音频。这里若 outputActive=true 或 outputAudioMs 非零，表示麦克风在 assistant 播放仍然活跃时正在输入。
4. barge-in detected source=active-speaker-audio 表示 OpenClaw 在 assistant 播放活跃时看到实时说话者音频。这有助于区分真正的中断和只是 Discord 说话开始事件但没有有效音频的情况。
5. barge-in requested reason=... 表示 OpenClaw 请求 realtime provider 取消或截断当前响应。它包含 outputAudioMs、outputActive 和 playbackChunks，这样你可以看到在中断前到底播放了多少 assistant 音频。
6. realtime audio playback stopped reason=... 是本地 Discord 播放重置点。reason 指明是谁停止了播放：barge-in、player-idle、provider-clear-audio、forced-agent-consult、stream-close 或 session-close。
7. realtime speaker turn closed 会总结捕获到的输入轮次。chunks=0 或 hasAudio=false 表示说话者轮次已打开，但没有可用音频到达 realtime bridge。interruptedPlayback=true 表示该输入轮次与 assistant 输出重叠并触发了 barge-in 逻辑。

• outputAudioMs：realtime provider 在该日志行之前生成的 assistant 音频时长。
• audioMs：OpenClaw 在播放停止前统计的 assistant 音频时长。
• elapsedMs：打开和关闭播放流或说话者轮次之间的墙钟时间。
• discordBytes：发送到或从 Discord voice 接收的 48 kHz 立体声 PCM 字节数。
• realtimeBytes：发送到或从 realtime provider 接收的 provider 格式 PCM 字节数。
• playbackChunks：当前响应转发到 Discord 的 assistant 音频 chunk 数。
• sinceLastAudioMs：最后一帧捕获到的说话者音频与说话者轮次关闭之间的间隔。

• 立即截断，且 source=active-speaker-audio、outputAudioMs 很小，并且附近是同一用户，通常说明扬声器回声进入了麦克风。可提高 voice.realtime.minBargeInAudioEndMs、降低扬声器音量、使用耳机，或设置 voice.realtime.providers.openai.interruptResponseOnInputAudio: false。
• source=speaker-start 后接 speaker turn closed ... hasAudio=false，表示 Discord 报告了说话开始，但没有音频到达 OpenClaw。这可能是临时的 Discord voice 事件、噪声门行为，或客户端短暂触发麦克风。
• audio playback stopped reason=stream-close 且附近没有 barge-in 或 provider-clear-audio，表示本地 Discord 播放流意外结束。请检查前面的 provider 和 Discord 播放器日志。
• capture ignored during playback (barge-in disabled) 表示 OpenClaw 有意在 assistant 音频活跃时丢弃输入。如果你希望语音打断播放，请启用 voice.realtime.bargeIn。
• barge-in ignored ... outputActive=false 表示 Discord 或 provider VAD 报告了语音，但 OpenClaw 没有可中断的活动播放。这不应导致音频被截断。

​

语音消息

• 提供一个 本地文件路径（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: {
    defaults: {
      botLoopProtection: {
        maxEventsPerWindow: 20,
        windowSeconds: 60,
        cooldownSeconds: 60,
      },
    },
    discord: {
      // 可选的 Discord 全局覆盖。账号块会覆盖单独字段，
      // 并从这里继承未显式填写的字段。
      botLoopProtection: {
        maxEventsPerWindow: 4,
      },
      accounts: {
        alpha: {
          // Alpha 仅在其他 bot mention 它时监听。
          allowBots: "mentions",
        },
        bravo: {
          // Bravo 监听所有由 bot 发出的 Discord 消息。
          allowBots: true,
          mentionAliases: {
            // 让 Bravo 使用配置的 user id 写出 Alpha 的 Discord mention。
            Alpha: "ALPHA_DISCORD_USER_ID",
          },
          botLoopProtection: {
            // 在抑制该 pair 之前，允许每分钟最多五条消息。
            maxEventsPerWindow: 5,
            windowSeconds: 60,
            cooldownSeconds: 90,
          },
        },
      },
    },
  },
}

​

配置参考

​

Discord 活动

• activities.clientSecret：Discord 应用的 OAuth2 客户端密钥；若未设置，则回退为 DISCORD_CLIENT_SECRET
• activities.applicationId：可选的活动应用 ID；默认使用网关启动时获取到的机器人应用 ID

​

安全与运维

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

​

相关