配置

渠道故障排查

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

命令排查顺序

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

bash

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

正常基准：

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

更新后

更新后，如果 Telegram、iMessage、BlueBubbles 时代的配置或其他插件渠道消失，请执行以下操作。

bash

openclaw status --allopenclaw doctor --fixopenclaw gateway restartopenclaw status --all

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

WhatsApp 故障特征

症状	最快检查方法	修复方法
已连接但不回复私信	`openclaw pairing list whatsapp`	批准发送者，或更改私信策略/允许列表。
忽略群组消息	检查配置中的 `requireMention` 和提及模式	提及机器人，或放宽该群组的提及策略。
二维码登录因 408 超时	检查 Gateway 网关的 `HTTPS_PROXY` / `HTTP_PROXY` 环境变量	设置可访问的代理；仅将 `NO_PROXY` 用于绕过代理。
随机断开连接/反复重新登录	`openclaw channels status --probe` 和日志	即使当前已连接，近期的重新连接也会被标记；观察日志、重启 Gateway 网关，如果连接仍反复波动，则重新关联。
反复出现 `status=408 Request Time-out`	依次执行探测、查看日志、运行 Doctor，然后检查 Gateway 网关状态	先修复主机连接或时序问题；如果循环仍然存在，请备份身份验证数据并重新关联账号。
回复延迟数秒或数分钟	`openclaw doctor --fix`	当确认过期的本地 TUI 客户端正在降低 Gateway 网关事件循环的性能时，Doctor 会将其停止。

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

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` 查看轮询诊断信息	升级；如果重启属于误报，请调整 `pollingStallThresholdMs`。持续停滞仍表明代理、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`。
有正在输入状态/令牌用量，但没有 Discord 消息	检查这是否为环境房间事件，或已选择启用 `message_tool` 但模型未调用 `message(action=send)` 的房间	检查 Gateway 网关详细日志中的最终负载抑制元数据，验证 `messages.groupChat.unmentionedInbound`，阅读环境房间事件，或为普通群组请求保留 `messages.groupChat.visibleReplies: "automatic"`。
缺少私信回复	`openclaw pairing list discord`	批准私信配对或调整私信策略。

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

Slack

Slack 故障特征

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

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

iMessage

iMessage 故障特征

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

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

Signal

Signal 故障特征

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

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

QQ Bot

QQ Bot 故障特征

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

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

Matrix

Matrix 故障特征

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

完整设置和配置：Matrix