频道故障排除
当频道已连接但行为异常时,请使用本页。
命令阶梯¶
请首先按以下顺序运行:
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 中查找 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