跳转至

频道故障排除

当频道已连接但行为异常时,请使用本页。

命令阶梯

请首先按以下顺序运行:

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

健康基线:

  • Runtime: running
  • 一次成功的连接检查
  • 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 会清理过期的 plugin-runtime 依赖符号链接和过期的 auth shadows,然后 openclaw gateway restart 重新加载干净状态。

WhatsApp

WhatsApp 故障特征

症状 最快检查 修复
已连接但没有 DM 回复 openclaw pairing list whatsapp 批准发送者,或切换 DM 策略/允许列表。
群消息被忽略 检查配置中的 requireMention + 提及模式 提及机器人,或放宽该群的提及策略。
QR 登录超时并返回 408 检查 gateway 的 HTTPS_PROXY / HTTP_PROXY 环境变量 设置一个可达的代理;仅将 NO_PROXY 用于绕过。
随机断开/重新登录循环 openclaw channels status --probe + 日志 即使当前已连接,最近的重连也会被标记;观察日志,重启 gateway,如果抖动持续则重新关联。
status=408 Request Time-out 循环 检查、日志、doctor,然后 gateway status 先修复主机连接/时序;如果循环持续,请备份 auth 并重新关联账户。
回复延迟数秒/数分钟 openclaw doctor --fix 当已验证的过期本地 TUI 客户端正在降低 Gateway 事件循环性能时,Doctor 会停止这些客户端。

完整故障排查:WhatsApp 故障排查

Telegram

Telegram 故障特征

症状 最快检查 修复
/start 但没有可用的回复流程 openclaw pairing list telegram 批准配对或更改 DM 策略。
机器人在线但群保持沉默 验证提及要求和机器人隐私模式 禁用隐私模式以获得群可见性,或提及机器人。
发送失败并出现网络错误 检查日志中的 Telegram API 调用失败 修复到 api.telegram.org 的 DNS/IPv6/代理路由。
启动时报告 getMe returned 401 检查已配置的 token 来源 重新复制或重新生成 BotFather token,并更新 botToken、tokenFile 或默认账户的 TELEGRAM_BOT_TOKEN。
轮询停滞或重连缓慢 openclaw logs --follow 用于轮询诊断 升级;持续停滞通常指向 proxy/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 验证 app token + bot 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