Discord

OpenClaw 通过官方 Discord Gateway 网关以机器人的身份连接到 Discord。支持私信和服务器频道。

快速设置

创建一个带机器人的 Discord 应用，将机器人添加到你的服务器，然后将其与 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>

推荐：设置服务器工作区

私信正常工作后，你可以将服务器转变为完整的工作区，其中每个频道都有一个具备独立上下文的智能体会话。推荐用于只有你和机器人的私人服务器。

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

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

现在创建频道并开始聊天。智能体可以看到频道名称，并且每个频道都是独立会话——你可以设置 #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 传递给路由后的对话会话。
• 仅含文本的定时任务/Heartbeat 公告投递到 Discord 时，会合并为智能体最终可见的回答，并且只发送一次。当智能体生成多个可投递载荷时，媒体和结构化组件载荷仍会以多条消息发送。

论坛频道

Discord 论坛和媒体频道仅接受主题帖。OpenClaw 支持通过两种方式创建主题帖：

• 向论坛父频道（channel:<forumId>）发送消息以自动创建主题帖。主题帖标题取自消息的第一个非空行（截断至 Discord 的 100 字符主题帖名称限制）。
• 使用 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 components v2 容器。请通过消息工具传入 components 载荷。交互结果会作为普通入站消息路由回智能体，并遵循现有的 Discord replyToMode 设置。

支持的块：

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

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

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

组件回调默认在 30 分钟后过期。设置 channels.discord.agentComponents.ttlMs 可更改默认账户的回调注册表生存期，也可使用 channels.discord.accounts.<accountId>.agentComponents.ttlMs 为每个账户单独设置。该值以毫秒为单位，必须为正整数，上限为 86400000（24 小时）。较长的 TTL 适用于需要让按钮持续可用的审查或审批工作流，但也会延长旧 Discord 消息仍能触发操作的时间窗口。应优先使用满足需求的最短 TTL；如果过期回调可能导致意外行为，请保留默认值。

/model 和 /models 斜杠命令会打开交互式模型选择器，其中包含提供商、模型和兼容运行时的下拉菜单，以及一个提交步骤。/models add 已弃用，它不会再从聊天中注册模型，而是返回弃用消息。选择器回复仅调用者可见，也只能由调用者使用。Discord 选择菜单最多包含 25 个选项，因此，如果希望选择器仅为 openai 或 vllm 等指定提供商显示动态发现的模型，请向 agents.defaults.modelPolicy.allow 添加 provider/* 条目。

文件附件：

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

访问控制和路由

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

基于角色的智能体路由

使用 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 身份验证，并回复“未授权”。
• 默认斜杠命令设置：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",},},}

{channels: {discord: {  subagentProgress: true,},},}

{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: "专注时间",  activityType: 4,},},}

{channels: {discord: {  activity: "实时编码",  activityType: 1,  activityUrl: "https://twitch.tv/openclaw",},},}

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

工具和操作门控

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 工具构造组件负载），旧版 embeds 仍然可用，但不建议使用。

• channels.discord.ui.components.accentColor 设置 Discord 组件容器使用的强调色（十六进制）。每个账户：channels.discord.accounts.<id>.ui.components.accentColor。
• channels.discord.agentComponents.ttlMs 控制已发送的 Discord 组件回调保持注册的时长（默认 1800000，最长 86400000）。每个账户：channels.discord.accounts.<id>.agentComponents.ttlMs。
• 存在 components v2 时，embeds 会被忽略。
• 默认禁止普通 URL 预览。当单个出站链接需要展开时，请在消息操作上设置 suppressEmbeds: false。

示例：

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

语音

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

语音频道

设置检查清单：

1. 在 Discord Developer Portal 中启用 Message Content Intent。
2. 使用角色/用户允许列表时，启用 Server Members Intent。
3. 使用 bot 和 applications.commands 权限范围邀请 Bot。
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

要在加入前检查 Bot 的有效权限：

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 语音功能是选择启用的；设置 channels.discord.voice.enabled=true（或保留现有的 channels.discord.voice 块）即可启用 /vc 命令、语音运行时和 GuildVoiceStates Gateway 网关意图。channels.discord.intents.voiceStates 可显式覆盖意图订阅；不设置则遵循实际的语音启用状态。
• 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 相互独立。
• voice.followUsers 允许 Bot 跟随选定用户加入、切换和离开 Discord 语音频道。参阅在语音频道中跟随用户。
• 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.speakerVoice 用于配置实时音频会话。要将 OpenAI Realtime 2.1 与 Codex 大脑搭配使用，请使用 voice.realtime.model: "gpt-realtime-2.1" 和 voice.model: "openai/gpt-5.6-sol"。
• 默认情况下，实时语音模式会在实时提供商指令中包含较小的 IDENTITY.md、USER.md 和 SOUL.md 配置文件，使快速直接轮次与路由到的 OpenClaw 智能体保持相同的身份、用户背景和角色设定。将 voice.realtime.bootstrapContextFiles 设置为一个子集可自定义此行为，或设置 [] 将其禁用。仅支持这些配置文件；AGENTS.md 仍保留在常规智能体上下文中。注入的配置文件上下文不能取代 openclaw_agent_consult，后者仍用于工作区工作、当前事实、记忆查询或工具支持的操作。
• 在 OpenAI agent-proxy 实时模式下，唤醒名称门控默认会根据房间情况调整：只有一名用户时，无需唤醒名称即可自然交谈；有两名或更多用户时，每个轮次的开头或结尾必须包含唤醒名称。其他 Bot 不计入人数。设置 voice.realtime.requireWakeName: true 可始终要求唤醒名称，设置 false 则从不要求。配置的唤醒名称必须由一到两个单词组成。如果未设置 voice.realtime.wakeNames，OpenClaw 会使用路由到的智能体 name 加 OpenClaw，并在无法使用时回退到智能体 ID 加 OpenClaw。启用唤醒名称门控后，实时提供商的自动响应会被禁用，已接受的轮次将通过 OpenClaw 智能体咨询路径进行路由；如果在最终转录到达前，从部分转录中识别出位于开头的唤醒名称，还会给出简短的语音确认。该策略会实时跟随用户的加入和离开，无需重新连接语音。
• OpenAI 实时提供商接受当前的 Realtime 2 事件名称，以及用于输出音频和转录事件的旧版 Codex 兼容别名，因此兼容的提供商快照即使出现差异，也不会丢失助手音频。
• voice.realtime.bargeIn 控制 Discord 的说话开始事件是否中断正在进行的实时播放。如果未设置，则遵循实时提供商的输入音频中断设置。
• voice.realtime.minBargeInAudioEndMs 控制 OpenAI 实时插话截断音频前，助手至少需要播放多长时间。默认值：250。在低回声房间中，可设置 0 以立即中断；对于回声较大的扬声器设置，则可提高该值。
• voice.tts 仅覆盖 stt-tts 语音播放的 tts；实时模式改用 voice.realtime.speakerVoice。要在 Discord 播放中使用 OpenAI 语音，请设置 voice.tts.provider: "openai"，并在 voice.tts.providers.openai.speakerVoice 下选择一种文本转语音音色。在当前 OpenAI TTS 模型中，cedar 是一个不错的男性音色选项。
• 每频道的 Discord systemPrompt 覆盖设置会应用于该语音频道的语音转录轮次。
• 当 OpenClaw 加入语音频道时，路由到的智能体会话会收到一条包含当前参与者名单的静默系统事件。之后参与者的加入和离开会更新该会话，但不会触发未经请求的语音回复；Discord 显示名称会被视为不可信标签。已授权的语音轮次也会收到最新的参与者名单快照。
• 语音转录轮次和 /vc 命令使用 commands.ownerAllowFrom 中的 Discord 条目确定所有者状态。如果未配置 Discord 命令所有者，所选 Discord 账号的 allowFrom（或旧版 dm.allowFrom）仍可授权语音访问，但不会授予所有者状态。智能体工具的可见性遵循路由会话所配置的工具策略。
• 如果 voice.autoJoin 中同一服务器有多个条目，OpenClaw 会加入该服务器最后配置的频道。
• voice.allowedChannels 是可选的驻留允许列表。不设置时，允许 /vc join 进入任何已授权的 Discord 语音频道。设置后，/vc join、启动时自动加入和 Bot 语音状态切换仅限于列出的 { guildId, channelId } 条目。将其设置为空数组可拒绝加入所有 Discord 语音频道。如果 Discord 将 Bot 移至允许列表之外，OpenClaw 会离开该频道，并在存在已配置的自动加入目标时重新加入该目标。
• voice.daveEncryption 和 voice.decryptionFailureTolerance 会原样传递给 @discordjs/voice 加入选项；上游默认值为 daveEncryption=true 和 decryptionFailureTolerance=24。
• OpenClaw 使用内置的 libopus-wasm 编解码器接收 Discord 语音并实时播放原始 PCM。它随附固定版本的 libopus WebAssembly 构建，无需原生 opus 插件。
• 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 控制 Discord 报告说话者停止说话后，OpenClaw 等待多长时间再最终确定该音频片段并交给 STT。默认值：2000；如果 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=...。

在语音频道中跟随用户

如果希望 Discord 语音 Bot 跟随一个或多个已知 Discord 用户，而不是在启动时加入固定频道或等待 /vc join，请使用 voice.followUsers。

{  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 接收恢复可能会在重复解密失败后离开并重新加入同一频道。由跟随功能所有的会话会在该恢复路径中保留跟随所有权，因此被跟随用户之后断开连接时，机器人仍会离开频道。

在以下加入模式中选择：

• 对于个人或操作员设置，如果希望你进入语音时机器人也自动进入，请使用 followUsers。
• 对于即使没有受跟踪用户进入语音也应保持在线的固定房间机器人，请使用 autoJoin。
• 对于一次性加入或不应自动保持语音在线状态的房间，请使用 /vc join。

Discord 语音编解码器：

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

STT 加 TTS 流水线：

• Discord PCM 捕获内容会转换为临时 WAV 文件。
• tools.media.audio 处理 STT，例如 openai/gpt-4o-mini-transcribe。
• 转录文本会经由 Discord 入口和路由发送；与此同时，响应 LLM 会按照一项语音输出策略运行，该策略会隐藏智能体的 tts 工具并要求返回文本，因为最终的 TTS 播放由 Discord 语音负责。
• 设置 voice.model 后，它仅覆盖此语音频道轮次使用的响应 LLM。
• voice.tts 会合并并覆盖 tts；支持流式传输的提供商会直接向播放器馈送内容，否则会在已加入的频道中播放生成的音频文件。

默认的智能体代理语音频道会话示例：

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

如果没有 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",          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",        },      },    },  },}

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

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

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

当委派的 OpenClaw 运行处于活动状态时，新的 Discord 语音转录文本会在启动另一个智能体轮次前被视为实时运行控制输入。“状态”“取消那个操作”“使用更小的修复方案”或“完成后也检查测试”等短语会被分类为当前会话的状态、取消、Steering queue 或后续输入。状态、取消、已接受的 Steering queue 和后续结果会在语音频道中朗读出来，使调用者知道 OpenClaw 是否已处理该请求。

可用的目标形式：

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

回声较严重时的 OpenAI Realtime 示例：

{  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 中播放的声音，但你仍希望通过说话打断它时，请使用此配置。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=...
• 智能体回答时：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 语音或从中接收的 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 身份验证，tts/voice.tts 使用 TTS 身份验证，而 voice.realtime.providers 使用实时提供商身份验证或该提供商的常规身份验证配置。

语音消息

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

• 提供一个本地文件路径（不接受 URL）。
• 省略文本内容（Discord 不接受在同一有效载荷中同时包含文本和语音消息）。
• 接受任何音频格式；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: {defaults: {  botLoopProtection: {    maxEventsPerWindow: 20,    windowSeconds: 60,    cooldownSeconds: 60,  },},discord: {  // 可选的 Discord 全局覆盖。账户块会覆盖各个  // 字段，并从此处继承省略的字段。  botLoopProtection: {    maxEventsPerWindow: 4,  },  accounts: {    alpha: {      // Alpha 仅在其他 Bot 提及它时才监听其消息。      allowBots: "mentions",    },    bravo: {      // Bravo 监听 Discord 中由 Bot 发出的所有消息。      allowBots: true,      mentionAliases: {        // 允许 Bravo 使用配置的用户 ID 写入对 Alpha 的 Discord 提及。        Alpha: "ALPHA_DISCORD_USER_ID",      },      botLoopProtection: {        // 每分钟最多允许五条消息，之后抑制这对 Bot。        maxEventsPerWindow: 5,        windowSeconds: 60,        cooldownSeconds: 90,      },    },  },},},}

配置参考

主要参考：配置参考 - Discord。

Discord Activities

设置 channels.discord.activities，允许智能体发布可在 Discord 内打开的独立 HTML 小组件。此配置块为可选启用；若不存在，OpenClaw 不会注册任何 Activity 路由、工具或交互处理程序。有关 Developer Portal、隧道、安全和故障排查设置，请参阅 Discord Activities。

• activities.clientSecret：Discord 应用程序的 OAuth2 客户端密钥；回退到 DISCORD_CLIENT_SECRET
• activities.applicationId：可选的 Activity 应用程序 ID；默认使用 Gateway 网关启动时获取的 Bot 应用程序 ID

安全与运维

• 将 Bot 令牌视为机密信息（在受监管环境中建议使用 DISCORD_BOT_TOKEN）。
• 授予最小权限的 Discord 权限。
• 如果命令部署/状态已过期，请重启 Gateway 网关，并使用 openclaw channels status --probe 重新检查。

相关内容