启动失败排查

适合谁

适合已经完成过安装,但当前实例无法稳定启动的人。

你会学到什么

  • • 知道启动失败和安装失败的边界
  • • 能用状态和日志判断程序卡在哪一层
  • • 知道什么时候该回配置页,什么时候该考虑清理旧残留

为什么现在读

启动失败通常意味着问题已经从安装前提转到运行状态层。

建议阅读:8-10 分钟

写在前面

如果 OpenClaw 已经安装过,但现在一启动就退出、卡住或状态异常,这已经不是纯安装问题。

你现在要做的不是立刻重装,而是先回答三个问题:

  • 程序有没有真正进入运行态;
  • 它是在启动时退出,还是运行后变得异常;
  • 日志里最后一个明确错误是什么。

第一步:先确认程序有没有真正起来

先执行:

openclaw status
openclaw gateway status

你要区分这几种情况:

  • 根本没起来;
  • 起来后立刻退出;
  • 看似运行,但状态不稳定;
  • 程序在运行,只是后续某层行为异常。

如果这一步都还分不清,就先不要去改平台或业务配置。

第二步:看日志里最后一个稳定信号

执行:

openclaw logs --follow

日志不用一次看全,你现在只需要先抓住三件事:

  • 最后一条明确错误是什么;
  • 有没有持续重复的阻塞报错;
  • 是启动即退,还是运行到某一步才卡住。

如果你最近刚改过配置、路径或服务方式,日志里最后一个异常通常和最近改动强相关。

第三步:补一轮最小诊断

如果状态和日志还不够清楚,再补一轮:

openclaw doctor

这一步适合确认配置、服务或环境里有没有明显阻塞问题。

但顺序不要反过来。先看状态和日志,再看 doctor,通常更容易判断问题层级。

第四步:把最近一次改动单独拎出来看

启动失败时,最近一次改动往往比更早的旧问题更有解释力。

优先回想你最近是否做过这些动作:

  • 改过配置;
  • 切过安装路径;
  • 改过服务方式;
  • 调过平台或访问边界。

如果答案是“有”,先不要继续扩大改动面,先验证这一次改动有没有闭环。

一个够用的最小排查阶梯

大多数启动问题,按这个顺序查就够了:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor

判断标准:

  • 状态能不能稳定读到;
  • 日志有没有给出明确停止点;
  • doctor 有没有补充指出配置、服务或环境问题。

什么时候别急着重装

启动失败并不自动等于环境坏了。

尤其当你刚做过配置修改、切换安装路径或调整服务方式时,更应该先停下来确认最近一次改动,而不是马上彻底清理。

很多启动问题,根因只是最近一次改动没有验证闭环。

常见错误或风险

  • 一启动失败就马上彻底清理;
  • 只看平台表现,不看主进程状态;
  • 忽略最近一次改动,继续扩大改动面;
  • 还没确认状态,就误判成必须重装。

下一步

如果启动失败明显来自配置变更,继续看 配置错误排查

如果你已经确认旧残留、服务项或安装路径混乱在持续干扰,继续看 禁用、卸载和彻底清理有什么区别