Discord

已可通过官方 Discord Gateway 网关用于私信和服务器频道。

快速设置

你需要创建一个带有机器人的新应用，将该机器人添加到你的服务器，并将其配对到 OpenClaw。我们建议将机器人添加到你自己的私有服务器。如果你还没有服务器，请先创建一个（选择 Create My Own > For me and my friends）。

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" },},},}JSON5openclaw config patch --file ./discord.patch.json5 --dry-runopenclaw config patch --file ./discord.patch.json5openclaw 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 discordopenclaw pairing approve discord <CODE>

推荐：设置服务器工作区

私信可用后，你可以将 Discord 服务器设置为完整工作区，其中每个频道都有自己的智能体会话和独立上下文。对于只有你和你的机器人的私有服务器，推荐这样做。

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

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

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

运行时模型

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

论坛频道

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 容器。使用带 components 载荷的消息工具。交互结果会作为普通入站消息路由回智能体，并遵循现有 Discord replyToMode 设置。

支持的块：

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

默认情况下，组件只能使用一次。设置 components.reusable=true 可允许按钮、选择和表单在过期前被多次使用。

要限制谁可以点击按钮，请在该按钮上设置 allowedUsers（Discord 用户 ID、标签或 *）。配置后，不匹配的用户会收到一条仅自己可见的拒绝消息。

/model 和 /models 斜杠命令会打开交互式模型选择器，其中包含提供商、模型和兼容运行时下拉菜单，以及一个提交步骤。/models add 已弃用，现在会返回弃用消息，而不是从聊天中注册模型。选择器回复仅自己可见，并且只有调用用户可以使用。Discord 选择菜单限制为 25 个选项，因此当你希望选择器只为所选提供商（例如 openai-codex 或 vllm）显示动态发现的模型时，请向 agents.defaults.models 添加 provider/* 条目。

文件附件：

• 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: "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[].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 应用中移除它们。
• 原生命令认证使用与普通消息处理相同的 Discord 允许列表/策略。
• 对未授权用户，命令可能仍会在 Discord UI 中可见；执行时仍会强制应用 OpenClaw 认证，并返回 “not authorized”。

请参阅斜杠命令，了解命令目录和行为。

默认斜杠命令设置：

• ephemeral: true

功能详情

{channels: {discord: {  streaming: {    mode: "progress",    progress: {      label: "auto",      maxLines: 8,      toolProgress: true,    },  },},},}

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

{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_...", // optional; needed for private systems  },},},}

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

工具和操作门控

Discord 消息操作包括消息、渠道管理、审核、在线状态和元数据操作。

核心示例：

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

event-create 操作接受可选的 image 参数（URL 或本地文件路径），用于设置定时事件封面图像。

操作门控位于 channels.discord.actions.* 下。

默认门控行为：

Components v2 UI

OpenClaw 将 Discord components v2 用于 exec 批准和跨上下文标记。Discord 消息操作也可以接受 components 来实现自定义 UI（高级；需要通过 discord 工具构造组件 payload），旧版 embeds 仍可使用，但不推荐。

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

示例：

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

语音

Discord 有两个不同的语音表面：实时语音频道（连续对话）和语音消息附件（波形预览格式）。Gateway 网关支持两者。

语音频道

设置检查清单：

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

使用 /vc join|leave|status 控制会话。该命令使用账户默认智能体，并遵循与其他 Discord 命令相同的允许列表和群组策略规则。

/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-codex/gpt-5.5",        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",          voice: "cedar",        },      },    },  },}

注意事项：

• voice.tts 仅会为 stt-tts 语音播放覆盖 messages.tts。实时模式使用 voice.realtime.voice。
• voice.mode 控制对话路径。默认值是 agent-proxy：实时语音前端负责轮次时序、中断和播放，通过 openclaw_agent_consult 将实质性工作委托给路由到的 OpenClaw 智能体，并像处理来自该说话者的已输入 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 智能体大脑。保持未设置时继承路由到的智能体模型。它与 voice.realtime.model 是分开的。
• agent-proxy 通过 discord-voice 路由语音，这会保留说话者和目标会话的正常所有者/工具授权，但会隐藏智能体 tts 工具，因为 Discord 语音拥有播放权。默认情况下，agent-proxy 会为所有者说话者提供等同所有者的完整工具访问权限（voice.realtime.toolPolicy: "owner"），并强烈倾向于在给出实质性回答前咨询 OpenClaw 智能体（voice.realtime.consultPolicy: "always"）。在默认的 always 模式中，实时层不会在咨询答案前自动说填充内容；它会捕获并转写语音，然后说出路由后的 OpenClaw 答案。如果 Discord 仍在播放第一个答案时有多个强制咨询答案完成，后续的精确语音答案会排队，直到播放空闲，而不是在句子中途替换语音。
• 在 stt-tts 模式中，STT 使用 tools.media.audio；voice.model 不影响转写。
• 在实时模式中，voice.realtime.provider、voice.realtime.model 和 voice.realtime.voice 配置实时音频会话。对于 OpenAI Realtime 2 加 Codex 大脑，使用 voice.realtime.model: "gpt-realtime-2" 和 voice.model: "openai-codex/gpt-5.5"。
• OpenAI 实时提供商接受当前的 Realtime 2 事件名称，以及用于输出音频和转写事件的旧版 Codex 兼容别名，因此兼容的提供商快照可以发生偏移而不会丢失助手音频。
• voice.realtime.bargeIn 控制 Discord 说话者开始事件是否中断活跃的实时播放。如果未设置，它会跟随实时提供商的输入音频中断设置。
• voice.realtime.minBargeInAudioEndMs 控制 OpenAI 实时打断截断音频前的最短助手播放时长。默认值：250。在低回声房间中设置为 0 可立即中断，或者在回声较重的扬声器设置中调高它。
• 对于 Discord 播放中的 OpenAI 语音，设置 voice.tts.provider: "openai"，并在 voice.tts.openai.voice 或 voice.tts.providers.openai.voice 下选择 Text-to-speech 语音。在当前 OpenAI TTS 模型上，cedar 是一个不错的偏男性声音选择。
• 每个频道的 Discord systemPrompt 覆盖会应用到该语音频道的语音转写轮次。
• 语音转写轮次会根据 Discord allowFrom（或 dm.allowFrom）推导所有者状态；非所有者说话者不能访问仅限所有者的工具（例如 gateway 和 cron）。
• Discord 语音对于纯文本配置是选择启用的；设置 channels.discord.voice.enabled=true（或保留现有 channels.discord.voice 块）以启用 /vc 命令、语音运行时以及 GuildVoiceStates Gateway 网关意图。
• channels.discord.intents.voiceStates 可以显式覆盖语音状态意图订阅。保持未设置时，该意图会跟随有效的语音启用状态。
• 如果 voice.autoJoin 对同一个服务器有多个条目，OpenClaw 会加入该服务器最后配置的频道。
• voice.allowedChannels 是可选的驻留允许列表。保持未设置时允许 /vc join 加入任何已授权的 Discord 语音频道。设置后，/vc join、启动时自动加入和机器人语音状态移动都将限制到列出的 { guildId, channelId } 条目。将它设置为空数组会拒绝所有 Discord 语音加入。如果 Discord 将机器人移到允许列表之外，OpenClaw 会离开该频道，并在有可用目标时重新加入配置的自动加入目标。
• voice.daveEncryption 和 voice.decryptionFailureTolerance 会透传给 @discordjs/voice 加入选项。
• 如果未设置，@discordjs/voice 默认值为 daveEncryption=true 和 decryptionFailureTolerance=24。
• OpenClaw 默认使用纯 JS 的 opusscript 解码器接收 Discord 语音。可选的原生 @discordjs/opus 包会被仓库 pnpm 安装策略忽略，因此普通安装、Docker 通道和无关测试不会编译原生插件。专用语音性能主机可以在安装原生插件后通过 OPENCLAW_DISCORD_OPUS_DECODER=native 选择启用。
• voice.connectTimeoutMs 控制 /vc join 和自动加入尝试的初始 @discordjs/voice Ready 等待。默认值：30000。
• voice.reconnectGraceMs 控制 OpenClaw 在销毁断开的语音会话前等待其开始重连的时长。默认值：15000。
• 在 stt-tts 模式中，语音播放不会仅仅因为另一个用户开始说话而停止。为避免反馈回路，OpenClaw 会在 TTS 播放期间忽略新的语音捕获；请在播放结束后再说下一轮。实时模式会将说话者开始转发为实时提供商的打断信号。
• 在实时模式中，扬声器回声进入打开的麦克风可能看起来像打断并中断播放。对于回声较重的 Discord 房间，设置 voice.realtime.providers.openai.interruptResponseOnInputAudio: false，防止 OpenAI 在输入音频上自动中断。如果你仍希望 Discord 说话者开始事件中断活跃播放，请添加 voice.realtime.bargeIn: true。OpenAI 实时桥会将短于 voice.realtime.minBargeInAudioEndMs 的播放截断视为可能的回声/噪声并忽略，将其记录为已跳过，而不是清除 Discord 播放。
• voice.captureSilenceGraceMs 控制 OpenClaw 在 Discord 报告说话者停止后等待多久才将该音频片段最终确定用于 STT。默认值：2500；如果 Discord 将正常停顿切分成零碎的部分转写，请调高此值。
• 当 ElevenLabs 是选定的 TTS 提供商时，Discord 语音播放会使用流式 TTS，并从提供商响应流开始。没有流式支持的提供商会回退到合成临时文件路径。
• OpenClaw 还会监视接收解密失败，并在短时间窗口内重复失败后通过离开/重新加入语音频道自动恢复。
• 如果更新后接收日志反复显示 DecryptionFailed(UnencryptedWhenPassthroughDisabled)，请收集依赖报告和日志。内置的 @discordjs/voice 版本线包含来自 discord.js PR #11449 的上游填充修复，该修复关闭了 discord.js issue #11419。
• 当 OpenClaw 最终确定捕获到的说话者片段时，The operation was aborted 接收事件是预期行为；它们是详细诊断，不是警告。
• 详细 Discord 语音日志会为每个接受的说话者片段包含一个有界的单行 STT 转写预览，因此调试时可以同时看到用户侧和智能体回复侧，而不会转储无界转写文本。
• 在 agent-proxy 模式中，强制咨询回退会跳过可能不完整的转写片段，例如以 ... 结尾的文本或像 and 这样的尾随连接词，以及明显不可操作的结束语，例如“be right back”或“bye”。当这避免了陈旧的排队答案时，日志会显示 forced agent consult skipped reason=...。

源码检出的原生 opus 设置：

pnpm installmise exec node@22 -- pnpm discord:opus:install

当你想要上游 macOS arm64 预构建原生插件时，请为 Gateway 网关使用 Node 22。如果你使用另一个 Node 运行时，选择启用的安装器可能需要本地 node-gyp 源码构建工具链。

安装原生插件后，使用以下命令启动 Gateway 网关：

OPENCLAW_DISCORD_OPUS_DECODER=native pnpm gateway:watch

详细语音日志应显示 discord voice: opus decoder: @discordjs/opus。如果没有选择启用环境变量，或者原生插件缺失或无法在主机上加载，OpenClaw 会记录 discord voice: opus decoder: opusscript，并通过纯 JS 回退继续接收语音。

STT 加 TTS 管道：

• Discord PCM 捕获会转换为 WAV 临时文件。
• tools.media.audio 处理 STT，例如 openai/gpt-4o-mini-transcribe。
• 转写会通过 Discord 入口和路由发送，同时响应 LLM 以语音输出策略运行，该策略会隐藏智能体 tts 工具并要求返回文本，因为 Discord 语音拥有最终 TTS 播放权。
• 设置 voice.model 时，它只会覆盖此语音频道轮次的响应 LLM。
• voice.tts 会合并并覆盖 messages.tts；支持流式传输的提供商会直接馈送播放器，否则会播放生成的音频文件到已加入的频道。

默认 agent-proxy 语音频道会话示例：

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai-codex/gpt-5.5",        realtime: {          provider: "openai",          model: "gpt-realtime-2",          voice: "cedar",        },      },    },  },}

没有 voice.agentSession 块时，每个语音频道都会获得自己的路由 OpenClaw 会话。例如，/vc join channel:234567890123456789 会与该 Discord 语音频道的会话对话。实时模型只是语音前端；实质性请求会交给配置的 OpenClaw 智能体。如果实时模型在未调用咨询工具的情况下生成最终转写，OpenClaw 会强制将咨询作为回退，因此默认行为仍像是在和智能体对话。

旧版 STT 加 TTS 示例：

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

实时 bidi 示例：

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai-codex/gpt-5.5",        realtime: {          provider: "openai",          model: "gpt-realtime-2",          voice: "cedar",          toolPolicy: "safe-read-only",          consultPolicy: "always",        },      },    },  },}

语音作为现有 Discord 频道会话的扩展：

{  channels: {    discord: {      voice: {        enabled: true,        mode: "agent-proxy",        model: "openai-codex/gpt-5.5",        agentSession: {          mode: "target",          target: "channel:123456789012345678",        },        realtime: {          provider: "openai",          model: "gpt-realtime-2",          voice: "cedar",        },      },    },  },}

在 agent-proxy 模式中，机器人会加入配置的语音频道，但 OpenClaw 智能体轮次使用目标频道的正常路由会话和智能体。实时语音会话会将返回结果说回语音频道。监督智能体仍然可以根据其工具策略使用正常消息工具，包括在合适时发送单独的 Discord 消息。

有用的目标形式：

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

回声较重的 OpenAI Realtime 示例：

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

当模型通过打开的麦克风听到自己的 Discord 播放声音，但你仍希望通过说话打断它时，请使用此配置。OpenClaw 会阻止 OpenAI 根据原始输入音频自动打断，而 bargeIn: true 允许 Discord 说话者开始事件和已活跃的说话者音频，在下一个捕获的轮次到达 OpenAI 之前取消活跃的实时响应。audioEndMs 低于 minBargeInAudioEndMs 的很早期抢话信号会被视为可能的回声/噪声并忽略，因此模型不会在第一个播放帧处被截断。

预期语音日志：

• 加入时：discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• 实时启动时：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 ...
• 实时响应完成时：discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• 播放停止/重置时：discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• 实时咨询时：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 ...
• 检测到抢话时：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=...
• 实时中断时：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
• 禁用抢话时：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 已开始播放助手音频。网桥会从此时开始统计助手输出分块、Discord PCM 字节、提供商实时字节，以及合成音频时长。
2. realtime speaker turn opened 标记某个 Discord 说话者变为活跃。如果播放已处于活跃状态且 bargeIn 已启用，后面可能会出现 barge-in detected source=speaker-start。
3. realtime input audio started 标记该说话者轮次收到的第一个实际音频帧。这里的 outputActive=true 或非零 outputAudioMs 表示麦克风在助手播放仍处于活跃状态时发送输入。
4. barge-in detected source=active-speaker-audio 表示 OpenClaw 在助手播放处于活跃状态时看到了实时说话者音频。这有助于区分真实打断和没有有效音频的 Discord 说话者开始事件。
5. barge-in requested reason=... 表示 OpenClaw 已要求实时提供商取消或截断活跃响应。它包含 outputAudioMs、outputActive 和 playbackChunks，因此你可以看到中断前实际播放了多少助手音频。
6. realtime audio playback stopped reason=... 是本地 Discord 播放重置点。原因会说明是谁停止了播放：barge-in、player-idle、provider-clear-audio、forced-agent-consult、stream-close 或 session-close。
7. realtime speaker turn closed 汇总捕获的输入轮次。chunks=0 或 hasAudio=false 表示说话者轮次已打开，但没有可用音频到达实时网桥。interruptedPlayback=true 表示该输入轮次与助手输出重叠，并触发了抢话逻辑。

有用字段：

• outputAudioMs：日志行之前由实时提供商生成的助手音频时长。
• audioMs：OpenClaw 在播放停止前统计的助手音频时长。
• elapsedMs：打开和关闭播放流或说话者轮次之间的挂钟时间。
• discordBytes：发送到 Discord 语音或从 Discord 语音接收的 48 kHz 立体声 PCM 字节。
• realtimeBytes：发送到实时提供商或从实时提供商接收的提供商格式 PCM 字节。
• playbackChunks：为活跃响应转发到 Discord 的助手音频分块。
• 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 语音事件、噪声门行为，或客户端短暂按下麦克风。
• 如果 audio playback stopped reason=stream-close 附近没有抢话或 provider-clear-audio，表示本地 Discord 播放流意外结束。检查前面的提供商和 Discord 播放器日志。
• capture ignored during playback (barge-in disabled) 表示 OpenClaw 在助手音频处于活跃状态时有意丢弃了输入。如果你希望语音打断播放，请启用 voice.realtime.bargeIn。
• barge-in ignored ... outputActive=false 表示 Discord 或提供商 VAD 报告了语音，但 OpenClaw 没有活跃播放可供打断。这不应截断音频。

凭证按组件解析：voice.model 使用 LLM 路由凭证，tools.media.audio 使用 STT 凭证，messages.tts/voice.tts 使用 TTS 凭证，voice.realtime.providers 或提供商的常规认证配置使用实时提供商凭证。

语音消息

Discord 语音消息会显示波形预览，并要求使用 OGG/Opus 音频。OpenClaw 会自动生成波形，但需要 Gateway 网关主机上有 ffmpeg 和 ffprobe 来检查并转换。

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

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

故障排除

openclaw doctoropenclaw channels status --probeopenclaw logs --follow

{channels: {discord: {  accounts: {    default: {      eventQueue: {        listenerTimeout: 120000,      },    },  },},},}

{channels: {discord: {  accounts: {    mantis: {      // Mantis listens to other bots only when they mention her.      allowBots: "mentions",    },    molty: {      // Molty listens to all bot-authored Discord messages.      allowBots: true,      mentionAliases: {        // Lets Molty write "@Mantis" and send a real Discord mention.        Mantis: "MANTIS_DISCORD_USER_ID",      },    },  },},},}

配置参考

主要参考：Configuration reference - Discord。

安全和运维

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

相关