跳转至

频道故障排查

当渠道连接成功但行为异常时，请使用此页面。

命令阶梯

请先按顺序运行以下命令：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

健康基线：

  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only、write-capable 或 admin-capable
  • 渠道探测显示传输已连接，并且在支持的情况下显示 works 或 audit ok

更新之后

当 Telegram、iMessage、BlueBubbles 时代的配置或其他插件渠道在更新后消失时，请使用此方法。

openclaw status --all
openclaw doctor --fix
openclaw gateway restart
openclaw status --all

在 openclaw status --all 中查找 plugin load failed: dependency tree corrupted; run openclaw doctor --fix。这表示渠道已配置，但插件设置/加载遇到了损坏的依赖树，而不是注册该渠道。openclaw doctor --fix 会清除过期的插件运行时依赖符号链接和过期的认证影子，然后 openclaw gateway restart 会重新加载干净状态。

WhatsApp

WhatsApp 故障特征

症状 最快检查 修复
已连接但无法收到私信回复 openclaw pairing list whatsapp 批准发送者，或切换私信策略/允许列表。
群组消息被忽略 检查配置中的 requireMention 和提及模式 提及机器人，或放宽该群组的提及策略。
QR 登录超时并返回 408 检查网关的 HTTPS_PROXY / HTTP_PROXY 环境变量 设置可达的代理；仅在绕过时使用 NO_PROXY。
随机断开/重新登录循环 openclaw channels status --probe 及日志 即使当前已连接，近期的重新连接也会被标记；查看日志、重启网关，如果抖动持续存在则重新关联。
status=408 Request Time-out 循环 先探测、查看日志、运行 doctor，然后检查网关状态 先修复主机连接/时序问题；如果循环持续存在，请备份认证并重新关联账户。
回复延迟数秒/数分钟到达 openclaw doctor --fix 当已确认过时的本地 TUI 客户端拖慢网关事件循环时，Doctor 会将其停止。

完整故障排查：WhatsApp 故障排查

Telegram

Telegram 故障特征

症状 最快检查 修复
/start 但没有可用的回复流程 openclaw pairing list telegram 批准配对或更改私信策略。
机器人在线但群组保持静默 验证提及要求和机器人隐私模式 禁用隐私模式以获取群组可见性，或提及机器人。
发送失败并出现网络错误 检查日志中的 Telegram API 调用失败 修复到 api.telegram.org 的 DNS/IPv6/代理路由。
启动时显示 getMe returned 401 检查已配置的令牌来源 重新复制或重新生成 BotFather 令牌，并更新 botToken、tokenFile 或默认账户的 TELEGRAM_BOT_TOKEN。
轮询停滞或重新连接缓慢 使用 openclaw logs --follow 进行轮询诊断 升级；持续停滞通常指向代理/DNS/IPv6。
setMyCommands 在启动时被拒绝 检查日志中是否有 BOT_COMMANDS_TOO_MUCH 减少插件/技能/自定义 Telegram 命令，或禁用原生菜单。
升级后你被允许列表阻止 运行 openclaw security audit 并检查配置允许列表 运行 openclaw doctor --fix，或将 @username 替换为数字发送者 ID。

完整故障排查：Telegram 故障排查

Discord

Discord 故障特征

症状 最快检查 修复
症状 最快检查 修复
机器人在线但服务器没有回复 openclaw channels status --probe 允许服务器/频道并验证消息内容意图。
群消息被忽略 检查日志中的提及门控丢弃记录 提及机器人或将服务器/频道设置为 requireMention: false。
有输入/token 使用但没有 Discord 消息 检查这是否是环境房间事件，或是一个已选择加入的 message_tool 房间，其中模型遗漏了 message(action=send) 检查网关详细日志中被抑制的最终负载元数据，验证 messages.groupChat.unmentionedInbound，阅读环境房间事件，或对普通群请求保持 messages.groupChat.visibleReplies: "automatic"。
缺少私信回复 openclaw pairing list discord 批准私信配对或调整私信策略。
机器人在原本正常的频道中保持沉默 检查服务器条目是否新增了 channels 映射 频道映射是允许列表：未列出的频道会被拒绝。添加一个 "*" 通配符条目。参见服务器频道映射是允许列表。
代理无法看到房间历史或其他机器人的附件 检查房间的 requireMention 和账户的 allowBots requireMention: true 会在消息成为房间事件之前丢弃未提及的消息，因此没有积压。机器人创建的消息及其附件需要 allowBots（"mentions" 是更安全的设置）。参见环境房间事件。
代理监视环境房间但从不发布 检查代理的工具配置中是否有 message 工具 房间事件需要 message(action=send)，而 minimal 和 coding 配置会省略它。为该代理授予 tools.alsoAllow: ["message"]。

完整故障排查：Discord 故障排查

Slack

Slack 故障特征

症状 最快检查 修复
Socket 模式已连接但没有响应 openclaw channels status --probe 验证应用 token + 机器人 token 和所需权限范围；在基于 SecretRef 的配置中留意 botTokenStatus / appTokenStatus = configured_unavailable。
私信被阻止 openclaw pairing list slack 批准配对或放宽私信策略。
频道消息被忽略 检查 groupPolicy 和频道允许列表 允许该频道或将策略切换为 open。

完整故障排查：Slack 故障排查

iMessage

iMessage 故障特征

症状 最快检查 修复
imsg 缺失或在非 macOS 上失败 openclaw channels status --probe --channel imessage 在 Messages Mac 上运行 OpenClaw，或为 cliPath 使用 SSH 包装器。
症状 最快检查 修复
macOS 上可发送但无法接收 检查 macOS 隐私权限中的 Messages 自动化权限 重新授予 TCC 权限并重启通道进程。
DM 发送者被阻止 openclaw pairing list imessage 批准配对或更新允许列表。

完整故障排查：iMessage 故障排查

Signal

Signal 故障特征

症状 最快检查 修复
守护进程可达但机器人无响应 openclaw channels status --probe 验证 signal-cli 守护进程 URL/账户和接收模式。
DM 被阻止 openclaw pairing list signal 批准发送者或调整 DM 策略。
群组回复未触发 检查群组允许列表和提及模式 添加发送者/群组或放宽门控。

完整故障排查：Signal 故障排查

QQ Bot

QQ Bot 故障特征

症状 最快检查 修复
机器人回复“去了火星” 在配置中验证 appId 和 clientSecret 更正凭据，然后在 热重载 后检查 openclaw channels status --probe。
没有入站消息 openclaw channels status --probe 在 QQ 开放平台上验证凭据。
语音未转写 检查 STT 提供商配置 配置 channels.qqbot.stt 或 tools.media.audio。
主动消息未送达 检查 QQ 平台交互要求 如果没有近期交互，QQ 可能会阻止机器人发起的消息。

完整故障排查：QQ Bot 故障排查

Matrix

Matrix 故障特征

症状 最快检查 修复
已登录但忽略房间消息 openclaw channels status --probe 检查 groupPolicy、房间允许列表和提及门控。
DM 未处理 openclaw pairing list matrix 批准发送者或调整 DM 策略。
加密房间失败 openclaw matrix verify status 重新验证设备，然后检查 openclaw matrix verify backup status。
备份恢复处于待处理/损坏状态 openclaw matrix verify backup status 运行 openclaw matrix verify backup restore，或使用恢复密钥重新运行。
交叉签名/引导看起来不正确 openclaw matrix verify bootstrap 一次性修复密钥存储、交叉签名和备份状态。

完整设置和配置：Matrix

网关已启动但通道始终无法连接

如果网关进程健康，但通道在多次非正常启动后仍保持停止状态，崩溃循环断路器 可能正在抑制通道自动启动。使用 openclaw gateway call channels.start --params '{"channel":"<id>"}' 可立即覆盖，或保持健康的网关继续运行。在完整的非正常启动窗口耗尽后，同一进程会重新检查断路器，并恢复延迟的通道自动启动。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw