写在前面
这一页不做杂乱 FAQ。它只负责两件事：先帮你把问题归类，再给你一套能立刻上手的最小排查动作。
如果你现在遇到的是“装不上”“启动就退”“改了没反应”或“平台不回复”，先不要继续扩大改动面，先用这一页把问题压缩到一层。
适合谁
- 安装或首次运行阶段已经遇到阻塞性错误的人；
- 改完配置后没有生效，不知道是字段问题还是运行状态问题的人；
- 渠道看起来连接正常，但消息链路没有闭环的人；
- 准备排查，但不想靠反复重装碰运气的人。
你会完成什么
- 知道先按安装失败、启动失败、配置错误、平台接入失败做问题分类；
- 知道排查第一轮该固定看哪些命令和信号；
- 知道状态、日志、doctor 和通道 probe 各自负责回答什么问题；
- 知道什么时候该停止扩散排查，回到更具体的任务页继续处理。
第一步：先跑一轮最小排查命令
如果你现在还不知道问题属于哪一类，先固定跑这一组：
openclaw status
openclaw gateway status
openclaw status --deep
openclaw doctor
openclaw logs --limit 100如果问题和平台接入有关，再补一组：
openclaw channels status
openclaw channels status --probe
openclaw channels logs --channel telegram --limit 200如果你接的不是 Telegram，就把 telegram 换成你当前的平台。
这两组命令分别回答的是：
- 程序有没有起来；
- Gateway 状态是否正常；
- 深层检查有没有指出模型、API 或运行异常；
- doctor 有没有发现环境、配置或服务问题；
- 最近日志里有没有明确报错；
- 渠道到底有没有连上，消息有没有卡在平台层。
推荐步骤
1. 先把问题压缩成一个分类
最先判断的是：你卡在安装、启动、配置还是平台接入。
这个分类比任何单个报错都更重要，因为它决定你下一步应该看哪一类教程。
2. 固定跑一轮基础检查
第一轮优先看这些信号：
- 状态；
- 网关状态；
- 最近日志；
- doctor；
- 通道状态。
这几类信息足够覆盖绝大多数一线问题。
3. 只保留一个最小可验证路径
排查时不要继续改更多配置。
优先保留一个最小成功链路，例如：
- 只验证 CLI 启动；
- 只验证一个私聊通道；
- 只验证一个字段修改是否生效。
三个高频真实场景
场景 1：程序装过了，但 openclaw status 一直异常
常见表现：
openclaw --version能返回；openclaw status没有正常结果，或者状态不稳定；- 你不确定问题还算安装失败，还是已经变成启动失败。
先做这几步：
openclaw status
openclaw gateway status
openclaw logs --follow判断方式：
- 如果状态完全不可读，先按启动层处理；
- 如果状态偶尔正常，但日志一直重复阻塞错误，问题更像运行态不稳；
- 如果你最近刚改过配置、服务或安装路径，优先回看最近一次改动，而不是立刻重装。
下一步去向：
场景 2：配置改了，但行为完全没变
常见表现：
- 你已经执行过
openclaw config set ...或改过配置文件； - 目标行为没有变化；
- 你开始怀疑是字段写错，或版本差异导致配置无效。
先做这几步：
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw config validate判断方式：
- 如果主进程本身都不稳定，先别继续猜字段；
- 如果配置校验已经失败，先修配置结构；
- 如果日志里根本看不到改动影响，先确认你改的是不是当前实例真正读取的那一层。
下一步去向：
场景 3：平台显示 connected，但机器人就是不回复
常见表现：
openclaw channels status看起来正常；- 平台里能看到 Bot 在线或渠道已连接；
- 你发了消息，但没有闭环回复。
先做这几步：
openclaw channels status --probe
openclaw logs --follow
openclaw pairing list如果要补看最近的渠道日志，再执行：
openclaw channels logs --channel telegram --limit 200判断方式：
- 如果
--probe直接报认证问题，先回平台配置； - 如果日志里完全没有消息进入，优先查平台事件、回调或入口；
- 如果日志里能看到消息，但系统不继续响应，重点查 pairing、allowlist、DM 策略或 mention 门控。
例如，常见 DM 策略里：
pairing：未知发送者会收到一次性配对码，未批准前不会真正放行；allowlist：只有明确允许的发送者才能通过；open：允许所有入站 DM；disabled：直接忽略所有 DM。
下一步去向：
关键判断点
连版本、向导或最小启动都没过
优先归为安装或环境问题，而不是配置问题。继续改字段没有意义。
网关能启动，但配置改了没反应
这更像配置层问题。先看加载顺序、字段位置、是否需要重启，以及验证动作是否做对。
平台显示 connected，但私聊或群组没回复
大概率是 pairing、allowlist、mention 或平台权限问题，优先回平台接入页，而不是继续怀疑安装。
故障速查表
| 现象 | 先跑什么 | 先判断什么 | 下一步 |
|---|---|---|---|
| 网关无法启动 | openclaw doctor | 环境、服务或配置是否阻塞 | 启动失败排查 |
status 可执行但状态异常 | openclaw status + openclaw logs --follow | 已安装但运行不稳，还是启动即退 | 启动失败排查 |
| 配置改了没反应 | openclaw config validate + openclaw logs --follow | 改动是否真的被读取 | 配置错误排查 |
| 渠道连接失败 | openclaw channels status --probe | 认证、配置还是平台入口问题 | 平台接入失败排查 |
| 平台 connected 但不回复 | openclaw pairing list + openclaw logs --follow | pairing、allowlist、mention 或权限问题 | 接入失败时怎么分类 |
| 日志很多但看不出结论 | openclaw logs --limit 100 | 最后一个明确错误和最近改动是什么 | 日志与环境检查方法 |
常见错误或风险
- 一边排查一边继续改多个变量；
- 长期开过深调试日志却没有结论；
- 把“看到了很多日志”误当成“已经定位了问题”；
- 明明还没分类清楚，就急着重装。
下一步
如果问题仍然停留在安装阶段，先看 安装失败排查。
如果程序已经装过，但一启动就退出或状态异常，继续看 启动失败排查。
如果配置改了没反应，继续看 配置错误排查。
如果平台看起来已连接，但消息没有闭环，继续看 平台接入失败排查。
FAQ
排查第一轮最值得看哪几个命令？
先固定成五类：状态、网关状态、日志、doctor、通道状态。它们分别回答运行状态、网关状态、最近发生了什么、环境与配置诊断，以及通道链路问题。
什么时候应该优先看日志，什么时候优先看 doctor？
当你要知道“刚才发生了什么”，先看日志；当你怀疑配置、服务、版本或环境本身有阻塞问题时，再看 doctor。
排查多久还没结果，才值得重装？
只有在你已经确认安装来源混用、状态目录残留、profile 混乱或服务清理不完整时，重装才更有意义。