本文依据2026-11-11核对的官方文档整理,未做本地安装实测;命令与界面以对应版本为准。
先定位链路
机器人不回复,先判断卡在哪一段:消息是否进入网关(接收),进入后是否走到可用模型与路由(路由/模型),以及回复是否成功发出(发送)。按下面的命令梯度收集证据,再决定修哪一段,避免一上来重装或同时改多处配置。
命令梯度:按顺序执行
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
建议把 openclaw logs --follow 放在单独终端持续观察,其他命令在另一终端执行,便于对照检查期间的新动静。
观察点:
openclaw gateway status:出现Runtime: running、连通性检查成功,以及Capability: ...行。openclaw doctor:不报告阻塞性的配置或服务问题。openclaw channels status --probe:显示各账户实时传输状态;在支持的情况下显示works或audit ok。openclaw status:作为总览,与后面几项对照。 若 Gateway 检查提示运行或连接异常,先处理相应问题;其他状态字段需要结合该渠道支持情况与日志判断,不能仅因缺少某个字段就确定故障原因。
接收段:消息有没有进来
先看 openclaw channels status --probe 的逐账户结果;支持该能力的渠道可用 works 或 audit ok 作为传输可用的信号。若没有预期状态,检查该渠道账户配置与连接方式,再回到 logs --follow 观察后续事件是否进入。其他渠道的现象不能替代当前渠道的证据;飞书的专属条件只在飞书一节使用。
路由与模型段:模型认证是否可用
消息已经进入但仍没有回复时,继续核对模型服务商认证。先在运行 Gateway 的主机上检查:
openclaw models status
openclaw doctor
官方认证文档说明,模型 API Key 应配置在 Gateway 主机上。若 Gateway 由 systemd 或 launchd 托管,不能仅凭当前终端存在环境变量就认定后台也已读取;应核对实际凭证来源。官方列出的保存方式包括 ~/.openclaw/.env,交互式 openclaw onboard 也可以处理相应保存步骤。
不要把教程中的占位符当成真实凭证,也不要将模型密钥与 Gateway 连接令牌混用。修改凭证后,按官方说明重启对应进程,再检查模型状态和实际消息结果。公开日志中的密钥与私人消息需要脱敏。
发送段:回复有没有发出去
接收与模型认证都正常后,再看发送。openclaw channels status --probe 的逐账户实时状态仍是主要观察点;支持时出现 works 或 audit ok,表示该账户传输检查通过。若某账户未通过,先修该账户,再保持 openclaw logs --follow 观察后续消息处理。仅凭“机器人没说话”不能判定为发送失败,也可能是消息没进入或模型认证失败。
飞书:群内不回复
以下条件只适用于飞书,不要套用到其他渠道。
- 确认机器人已加入该群。
- 检查当前群的提及规则;需要 @ 时,带上对机器人的 @ 再测试。
- 核对群聊访问策略;除了确认没有禁用群聊,还要检查当前群是否在配置允许的范围内。使用 allowlist 时,仅检查不是 disabled 并不够。
- 持续查看日志:
openclaw logs --follow
若私聊正常、群聊不回复,优先核对以上四点。是否必须 @ 应按当前群实际的 requireMention 设置及访问策略判断,不能将某一种配置的默认行为套到所有群。
飞书:完全收不到消息
逐条核对:
- 应用已在飞书开放平台 / Lark Developer 发布并通过审批。
- 事件订阅包含
im.message.receive_v1。 - 连接方式选择持久连接(WebSocket)。
- 授予所需权限范围。
- 确认网关在运行:
openclaw gateway status
- 查看日志:
openclaw logs --follow
常见漏项是应用未发布/未审批、事件订阅缺 im.message.receive_v1,或连接方式不是 WebSocket。这类问题表现为飞书侧没有消息进入,不是模型回复失败;只修模型配置不会解决。
失败场景与修复后检查
场景示例:飞书群内 @ 机器人后完全没有回复,私聊也不回复。按链路排查后,假设发现应用未完成发布审批、事件订阅缺少 im.message.receive_v1、连接方式不是持久连接 WebSocket。这不是实测日志,只说明修复顺序。
修复顺序:
- 在飞书开放平台 / Lark Developer 完成发布与审批。
- 事件订阅补上
im.message.receive_v1。 - 连接方式改为持久连接(WebSocket)。
- 补齐所需权限范围。
- 回到网关主机确认服务在跑:
openclaw gateway status
- 修复后复查:
openclaw doctor
openclaw channels status --probe
openclaw logs --follow
预期结果(非实测输出):
openclaw gateway status显示Runtime: running、连通性检查成功和Capability: ...行。openclaw doctor不报告阻塞性配置或服务问题。openclaw channels status --probe显示逐账户实时传输状态,并在支持时显示works或audit ok。openclaw logs --follow可持续观察修复后是否有新事件进入;不要凭一条日志断定成功,应结合前三项判断。 若复查仍不满足,保留结果,按“接收→路由/模型→发送”重新定位。
继续阅读
参考资料与核对日期
资料核对:2026-11-11。以下为对应的官方文档入口;本文为文档整理,未作本地安装实测。