故障排除
针对行为异常的 Discord 账号的症状优先检查。
故障排查¶
使用了不允许的 intents,或机器人看不到服务器消息
- 启用 Message Content Intent
- 当依赖用户/成员解析时,启用 Server Members Intent
- 更改 intents 后重启网关
服务器消息被意外阻止
- 检查 `groupPolicy`
- 检查 `channels.discord.guilds` 下的服务器允许列表
- 如果存在某个服务器的 `channels` 映射,则只允许列出的频道
- 检查 `requireMention` 行为和提及模式
当有效策略为 `allowlist` 但未配置任何服务器时,Control UI 的频道详情和 `openclaw channels status` 会发出警告。请将你的服务器添加到 `channels.discord.guilds` 下;如果已覆盖,则添加到账号的 `guilds` 映射中。
显式的 `channels.discord.accounts.default.guilds` 映射也会覆盖顶层映射,即使账号映射为空。
如果状态报告了延迟的配置重新加载,请等待当前活动完成并刷新。成功停止/启动频道不会应用未发布的配置。该警告区分“等待发布配置”和“发布后延迟的频道工作”;仅凭连接健康状态无法确认策略变更已生效。
有用的检查:
requireMention 为 false 但仍被阻止
常见原因:
groupPolicy="allowlist"但没有匹配的服务器/频道允许列表requireMention配置位置错误(必须位于channels.discord.guilds或某个频道条目下)- 发送者被服务器/频道
users允许列表阻止
Discord 轮次长时间运行或重复回复
典型日志:
Slow listener detected ...stuck session: sessionKey=agent:...:discord:... state=processing ...
Discord 不会为排队中的 agent 轮次应用频道拥有的超时。消息监听器会立即移交,排队的 Discord 运行会保持按会话的顺序,直到会话/工具/运行时生命周期完成或中止工作。
网关元数据查找超时警告
OpenClaw 会在连接前获取 Discord 的 /gateway/bot 元数据。瞬时故障会回退到 Discord 的默认网关 URL,并在日志中限流。
元数据超时默认为 30 秒。OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS 可在特殊主机环境中覆盖它。
网关 READY 超时重启
OpenClaw 会在启动期间以及运行时重连后等待 Discord 网关的 READY 事件。具有启动错峰的多个账号设置可能需要比默认更长的启动 READY 窗口。
启动等待 15 秒,运行时重连等待 30 秒。OPENCLAW_DISCORD_READY_TIMEOUT_MS 和 OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS 仍可用于特殊主机环境。
权限审计不匹配
channels status --probe 的权限检查仅对数字频道 ID 有效。
如果你使用 slug 键,运行时匹配仍可能有效,但检查无法完全验证权限。
DM 和配对问题
- DM 已禁用:
channels.discord.dm.enabled=false - DM 策略已禁用:
channels.discord.dmPolicy="disabled"(旧版:channels.discord.dm.policy) - 在
pairing模式下等待配对批准
机器人到机器人循环
机器人发送的消息默认在正常的提及和访问规则下被接受。
请保持提及和允许列表规则适合该房间。设置 `channels.discord.allowBots=false` 以禁用由机器人触发的轮次,或设置 `channels.discord.allowBots="mentions"` 以仅接受提及该机器人的机器人消息。这些设置不会隐藏可访问的机器人发送历史或人工选择的回复上下文。
在 `"mentions"` 模式下,仅回复 ping 元数据不算数。机器人回复需要一个有效的原生提及,或 Markdown 代码之外的已配置文本/转录提及。
OpenClaw 还附带共享的[机器人循环保护](../bot-loop-protection.md)。每当 `allowBots` 允许机器人发送的消息到达分发时,Discord 会将入站事件映射为 `(account, channel, bot pair)` 事实,通用配对守卫会在其超过配置的事件预算后抑制该配对。该守卫限制快速的两个机器人循环;低于预算的交互可以继续。它不影响人类消息或保持在预算内的一次性机器人回复。
默认设置(只要机器人发送的消息被接受即生效):
- `maxEventsPerWindow: 20` -- 机器人配对可以在滑动窗口内交换 20 条消息
- `windowSeconds: 60` -- 滑动窗口长度
- `cooldownSeconds: 60` -- 一旦触发预算,之后任意方向的额外机器人到机器人消息都会被丢弃一分钟
在 `channels.defaults.botLoopProtection` 下一次性配置共享默认值,然后当合法工作流需要更多余量时覆盖 Discord。优先级为:
- `channels.discord.accounts.<account>.botLoopProtection`
- `channels.discord.botLoopProtection`
- `channels.defaults.botLoopProtection`
- 内置默认值
Discord 使用通用的 `maxEventsPerWindow`、`windowSeconds` 和 `cooldownSeconds` 键。
{
channels: {
defaults: {
botLoopProtection: {
maxEventsPerWindow: 20,
windowSeconds: 60,
cooldownSeconds: 60,
},
},
discord: {
// Optional Discord-wide override. Account blocks override individual
// fields and inherit omitted fields from here.
botLoopProtection: {
maxEventsPerWindow: 4,
},
accounts: {
alpha: {
// Alpha listens to other bots only when they mention it.
allowBots: "mentions",
},
bravo: {
// Bravo listens to all bot-authored Discord messages.
allowBots: true,
mentionAliases: {
// Lets Bravo write an Alpha Discord mention with the configured user id.
Alpha: "ALPHA_DISCORD_USER_ID",
},
botLoopProtection: {
// Allow up to five messages per minute before suppressing the pair.
maxEventsPerWindow: 5,
windowSeconds: 60,
cooldownSeconds: 90,
},
},
},
},
},
}
语音 STT 因 DecryptionFailed(...) 中断
- 运行 OpenClaw 2026.2.24 或更高版本(
openclaw update),该版本新增了 Discord 语音接收恢复逻辑(#25861) - 确认
channels.discord.voice.daveEncryption=true(默认值) - 从
channels.discord.voice.decryptionFailureTolerance=24(上游默认值)开始,仅在必要时调整 - 关注以下日志:
discord voice: DAVE decrypt failures detecteddiscord voice: repeated decrypt failures; attempting rejoin- 如果自动重新加入后故障仍然存在,请收集日志,并与 discord.js #11419 和 discord.js #11449 中的上游 DAVE 接收历史记录进行对比
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw