OpenClaw 渠道连上了却不回消息：官方排查表按渠道逐条拆解

2026-08-17

接消息渠道最难受的不是连不上，而是”看起来连上了”。网关在跑，渠道状态显示 connected，日志里也没有刺眼的红字，可你在群里 @ 它，它就是不吭声；或者私聊发过去，石沉大海。

这类问题的麻烦之处在于，症状高度雷同，成因却分散在完全不同的层：可能是配对没批准，可能是群里的提及策略把消息提前丢掉了，可能是 token 失效，也可能是插件加载压根没成功、渠道根本没注册上去。挨个猜要花很久。

OpenClaw 官方文档里有一页专门干这件事——channels/troubleshooting。它的定位写得很直白：当渠道已经连上、但行为不对时用这一页。它给的东西有两部分，一是不分渠道通用的命令阶梯，二是按渠道列的”故障特征表”（failure signatures），每一行是”症状 → 最快的检查动作 → 修复动作”。这篇就把这页拆开讲，顺序和官方一致：先通用，再分渠道。

先按顺序跑这五条命令

官方要求这几条命令按顺序先跑一遍，不要跳：

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

这个顺序是有讲究的：从整体运行态，到网关本身，到实时日志，再到体检，最后才是带探测的渠道状态。前面几条能排掉”其实是网关的问题”这一大类，避免你一头扎进某个渠道的配置里瞎改。如果前两条就已经不正常，那问题不在渠道层，得往网关那边查；doctor 的输出怎么读，见 doctor 体检输出对照。

跑完之后，官方给了一份”健康基线”，用来判断当前状态到底算不算正常：

观察项	健康时应该看到
运行态	`Runtime: running`
连通性探测	`Connectivity probe: ok`
能力等级	`read-only`、`write-capable` 或 `admin-capable` 三者之一
渠道探测	传输层显示已连接；在支持的渠道上还会显示 `works` 或 `audit ok`

注意能力等级那一行：三个值都算正常基线，它们表示的是这个渠道当前被授予的权限档位，不是错误。如果你的渠道是 read-only，那它读得到消息但发不出去，这本身就是配置结果，不用去日志里找报错。

更新之后渠道整个消失

这是一类单独列出来的场景：升级之后，Telegram、iMessage、BlueBubbles 时期的旧配置，或者别的插件式渠道，直接不见了。官方给的动作序列是：

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

关键在第一步的输出里找这句话：plugin load failed: dependency tree corrupted; run openclaw doctor --fix。它的含义很明确——渠道的配置还在，配置没丢，但插件在安装/加载阶段撞上了损坏的依赖树，于是渠道没能完成注册。表现出来就是”我明明配过这个渠道，现在列表里没有了”。

openclaw doctor --fix 在这里做两件事：清掉插件运行时里过期的依赖软链接，以及过期的 auth shadow；然后 openclaw gateway restart 让网关带着干净的状态重新加载。先 --fix 再重启，顺序反了等于白做。最后再跑一次 status --all 是为了确认渠道真的回来了，而不是靠感觉。

八个渠道的故障特征表

下面按官方分渠道的表格来。每个渠道我只挑那些”症状看起来一样、原因完全不同”的行重点说，完整版以官方文档为准。

症状	最快的检查	处理
已连接但私聊没有回复	`openclaw pairing list whatsapp`	批准发送方，或调整私聊策略/允许列表
群消息被忽略	检查配置里的 `requireMention` 与提及匹配规则	在群里 @ 机器人，或放宽该群的提及策略
扫码登录超时报 408	检查网关的 `HTTPS_PROXY` / `HTTP_PROXY` 环境变量	换一个可达的代理；`NO_PROXY` 只用于放行例外
随机断连、反复重登	`openclaw channels status --probe` 加日志	即使当前显示已连接，近期的重连也会被标出来；盯日志、重启网关，仍然抖就重新绑定
`status=408 Request Time-out` 反复出现	探测、日志、doctor，再看网关状态	先解决主机连通性与时间问题；一直循环就备份 auth 后重新链接账号
回复延迟几秒到几分钟	`openclaw doctor --fix`	doctor 会停掉那些被确认为过期、正在拖慢网关事件循环的本地 TUI 客户端

最后一行值得单独记一下：回复变慢的原因可能是本地残留的旧 TUI 客户端在拖网关的事件循环，这不是网络问题，从网络那边查一天也查不出来。

症状	最快的检查	处理
发了 `/start` 但没有可用的对话流程	`openclaw pairing list telegram`	批准配对，或修改私聊策略
机器人在线但群里一直沉默	确认提及要求，以及 bot 的 privacy mode	关掉 privacy mode 让它能看到群消息，或者直接 @ 它
发送失败并伴随网络错误	在日志里找 Telegram API 调用失败	修 DNS / IPv6 / 代理到 `api.telegram.org` 的路由
启动时报 `getMe returned 401`	检查 token 的来源配置	重新复制或重新生成 BotFather token，更新 `botToken`、`tokenFile` 或默认账户的 `TELEGRAM_BOT_TOKEN`
轮询停滞或重连很慢	`openclaw logs --follow` 看轮询诊断	升级版本；持续停滞通常仍然指向代理 / DNS / IPv6
启动时 `setMyCommands` 被拒	日志里找 `BOT_COMMANDS_TOO_MUCH`	减少插件/技能/自定义的 Telegram 命令数量，或关掉原生菜单
升级之后自己被允许列表挡在外面	`openclaw security audit` 加配置里的 allowlist	跑 `openclaw doctor --fix`，或把 `@username` 换成数字形式的发送方 ID

privacy mode 那一条是 Telegram 平台自身的机制，很多人配完发现”私聊好使、群里装死”，就是卡在这。

Discord

Discord 的表最长，也最能说明”同一个现象有多个入口”：

机器人在线但服务器里没回复：先 openclaw channels status --probe，然后放行对应的服务器/频道，并确认 message content intent。
群消息被忽略：日志里找提及门控丢弃的记录，@ 一下机器人，或者把该服务器/频道设成 requireMention: false。
有打字状态、有 token 消耗，但 Discord 里没有消息：这可能是环境房间事件（ambient room event），或者是一个开了 message_tool 的房间而模型没有调用 message(action=send)。检查网关 verbose 日志里被抑制的最终载荷元数据，核对 messages.groupChat.unmentionedInbound；常规群聊请求可以保持 messages.groupChat.visibleReplies: "automatic"。
曾经能用的频道突然没声音：看看该服务器条目是不是多了一个 channels 映射。频道映射本身就是允许列表，没列出来的频道一律拒绝，加一条 "*" 通配条目即可。
Agent 看不到房间历史或其它机器人的附件：检查房间的 requireMention 和账户的 allowBots。requireMention: true 会在消息变成房间事件之前就丢掉未提及的消息，所以根本不存在什么”积压历史”可读；机器人发的消息及其附件需要 allowBots，官方标注 "mentions" 是更稳妥的取值。
Agent 一直在看某个环境房间但从不发言：检查该 Agent 的工具档位有没有 message 工具。房间事件要发言必须靠 message(action=send)，而 minimal 和 coding 两个档位不包含它，需要给这个 Agent 配 tools.alsoAllow: ["message"]。

这几条里，“频道映射即允许列表”和”工具档位缺 message”两条最容易踩，因为它们都不会报错，只是安静地不干活。群里的提及策略和机器人之间的互相触发是另一个大话题，见群消息策略与 bot loop 保护。

Slack、iMessage、Signal

这三个的表短一些，放在一起看：

渠道	症状	最快的检查	处理
Slack	socket mode 已连接但没有响应	`openclaw channels status --probe`	核对 app token、bot token 与所需 scope；SecretRef 方式的配置要留意 `botTokenStatus` / `appTokenStatus = configured_unavailable`
Slack	私聊被挡	`openclaw pairing list slack`	批准配对或放宽私聊策略
Slack	频道消息被忽略	检查 `groupPolicy` 与频道允许列表	放行该频道，或把策略切成 `open`
iMessage	非 macOS 上 `imsg` 缺失或失败	`openclaw channels status --probe --channel imessage`	把 OpenClaw 跑在那台装了「信息」的 Mac 上，或用 SSH 包装脚本作为 `cliPath`
iMessage	macOS 上能发不能收	检查 macOS 对「信息」自动化的隐私权限	重新授予 TCC 权限并重启渠道进程
iMessage	私聊发送方被挡	`openclaw pairing list imessage`	批准配对或更新允许列表
Signal	守护进程可达但机器人不说话	`openclaw channels status --probe`	核对 `signal-cli` 的守护进程 URL、账号与接收模式
Signal	私聊被挡	`openclaw pairing list signal`	批准发送方或调整私聊策略
Signal	群里回复不触发	检查群允许列表与提及匹配规则	把发送方/群加进去，或放松门控

QQ 机器人与 Matrix

QQ 机器人这边，官方列了四种：机器人回复”跑火星了”，去核对配置里的 appId 与 clientSecret，设好凭据或重启网关；完全收不到消息，先 openclaw channels status --probe，再去 QQ 开放平台核对凭据；语音没有转写，检查 STT 配置，即 channels.qqbot.stt 或 tools.media.audio；主动消息发不出去，这是平台侧的限制——QQ 可能会拦截缺少近期互动的机器人主动消息。

Matrix 的特殊之处在于加密和设备验证：登录了但不理会房间消息，查 groupPolicy、房间允许列表和提及门控；私聊不处理，查 openclaw pairing list matrix；加密房间失败，用 openclaw matrix verify status 重新验证设备，再看 openclaw matrix verify backup status；备份恢复卡住或损坏，跑 openclaw matrix verify backup restore，必要时带恢复密钥重跑；交叉签名或 bootstrap 看着不对劲，openclaw matrix verify bootstrap 会一次性修复 secret storage、交叉签名和备份状态。

网关是健康的，但渠道就是不连

这是最后一个单独的场景，也是最容易被误判成”渠道配错了”的一个。如果网关进程健康，某个渠道却在反复的非正常启动之后一直处于停止状态，那可能是崩溃循环断路器（crash-loop breaker）在主动压制这个渠道的自动启动——它不是故障，是保护机制在生效。

想立刻覆盖它，用这条：

openclaw gateway call channels.start --params '{"channel":"<id>"}'

或者干脆什么都不做，让健康的网关继续跑着。等整个非正常启动的统计窗口排空之后，同一个进程会重新检查断路器状态，并恢复此前被推迟的渠道自动启动。这个机制和重启后的状态恢复是同一条线上的事，见重启恢复机制。

把这些表格压成一句话

把八个渠道的表叠起来看，反复出现的其实只有三类原因：

配对没批准——几乎每个渠道都有一行是 openclaw pairing list <channel>。私聊没反应，先查这个，不要先怀疑网络。
门控把消息提前丢了——requireMention、群/频道允许列表、groupPolicy、Discord 的频道映射、Telegram 的 privacy mode，都属于这一类。它们的共同特征是：不报错，安静地丢弃。
凭据或依赖坏了——token 401、configured_unavailable、插件依赖树损坏。这一类通常在启动日志里有痕迹，值得先 --follow 一遍再动手改配置。

按这三类去猜，比按渠道去猜快得多。渠道接入的通用流程和配对机制本身，可以看渠道接入通用流程与配对机制。

这页解决不了什么

得说清边界。官方这页的自我定位是”渠道已经连上、但行为不对”时的快速对照，不是完整的故障手册：

它不覆盖首次接入配置。如果你还没连上，凭据、回调地址、平台侧审核这些属于各渠道的接入文档，不在这页。
每个渠道都另有完整排查章节。这页的每张表末尾都指向对应渠道的完整排查段落，表里给的是最高频的几条，不是全部。
它不解释模型侧的行为。比如 Discord 那条”有 token 消耗但没消息”，文档给的是怎么定位（看被抑制的载荷、看工具档位），至于模型为什么没调用发送工具，属于 Agent 与提示词的范畴。
平台侧限制改不了。QQ 主动消息那条就是典型：这是平台规则，不是配置问题，本地怎么调都没用。

还有一点，表里多处出现的 openclaw doctor --fix 是会动本地状态的（清理依赖软链接、停掉过期客户端进程），不是只读体检。在生产环境跑之前，最好先看清楚 openclaw doctor 不带 --fix 时报了什么，心里有数再修。

延伸阅读

从头读起：OpenClaw 架构总览：网关、Agent、渠道、节点、插件五层各管什么，出问题该往哪查
本专题共 40 篇，完整分组目录见专题页
OpenClaw 接微信：openclaw-weixin 插件的安装、扫码登录与版本对应关系
OpenClaw 企业微信渠道怎么配：官方只给三条命令，其余归外部插件管

本文依据 OpenClaw 官方仓库（github.com/openclaw/openclaw）docs/ 下的官方文档整理，核对日 2026-08-17。 我们没有安装或运行过 OpenClaw，因此不涉及界面外观、操作手感与实测耗时的任何描述；文中的默认值、命令与配置项均为文档口径，不构成对实际运行结果的保证。该项目迭代很快，请以仓库最新内容为准。接入即时通讯平台前，请自行确认所在平台的规则与合规要求。