系列：小文AI踩坑记

从一头雾水到破案高手

刚开始接触 OpenClaw 的日志时，我完全是一脸懵。

logs/ 目录下好几种文件，内容里一大串 JSON，看着就头大。

但经历了前面几篇说的故障之后，我发现自己不得不学会看日志——因为不看出问题的速度远比你想象的快。

学会读日志之后，很多原来觉得”好可怕、不知道怎么办”的问题，一下就变得清晰了。

OpenClaw 日志全家桶

先搞清楚你家有哪些”档案”，以及它们各自负责什么：

### ① logs/gateway-restart.log

网关启动和重启的记录。故障排查第一站。

[周二 2026/06/09 12:21:56] openclaw restart attempt
[周一 2026/06/15 08:47:37] openclaw restart finished

如果发现重启记录对应的时段你正好没法用，那大概率就是这里的问题。

### ② logs/stability/ 目录

稳定性日志的档案馆。 每次出现异常，系统都会在这里生成报告：

openclaw-stability-2026-05-22T...-uncaught_exception.json
openclaw-stability-2026-06-15T...-gateway.startup_failed.json

文件名本身就说明了问题类型和发生时间。

### ③ logs/config-audit.jsonl

配置文件变更审计日志。 谁、什么时候、改了配置文件的什么内容，全都记着。特别适合排查”到底是谁把我的配置搞坏了”这种问题。

### ④ logs/config-health.json

当前配置健康状况。 看一眼就知道你的配置是否正常，有没有被篡改或损坏。

稳定性日志怎么读？

这是最有价值的日志，但也是最容易被忽略的。

它是一个 JSON 文件，核心结构如下：

{
  "reason": "gateway.startup_failed",    // ← 问题类型
  "error": {
    "name": "Error",
    "message": "Invalid config at ..."   // ← 错误详情
  },
  "snapshot": {
    "summary": {
      "byType": {
        "diagnostic.liveness.warning": 111,  // ← 延迟警告次数
        "diagnostic.memory.sample": 436      // ← 内存采样次数
      }
    }
  }
}

关键看三个地方：

• reason：问题类型——启动失败？崩溃？还是别的？

• error.message：具体错误信息——为什么出问题？

• snapshot.summary.byType：崩溃前的异常统计——看到 liveness.warning 频繁出现，说明有预兆

常用诊断命令速查

我把最常用的几条命令做成了速查表：

场景命令

网关还活着吗？`openclaw status`

配置文件有问题吗？`openclaw doctor`

看最后一次启动记录`cat logs/gateway-restart.log`

看当天稳定性事件`dir logs/stability/`

看配置变更历史`cat logs/config-audit.jsonl`

一个完整的故障排查流程

结合前几篇的经验，我现在排查问题的标准流程是这样的：

第一步：确认状态

→ openclaw status

第二步：如果是网关问题

→ 看 gateway-restart.log

→ 看 stability/ 目录

第三步：如果是配置问题

→ openclaw doctor 诊断

→ 看 config-audit.jsonl 找变更记录

第四步：如果是性能问题

→ 看稳定性日志里的 event_loop_delay 数据

→ 看内存使用趋势

全程不超过5分钟。

踩坑总结

日志是好朋友，不是天书——结构化的JSON其实比一堆乱码好懂多了

先看reason，再看detail——不要一头扎进上万行的事件记录里

文件名本身就带着时间戳——按时间排序，看最新的那个

把诊断命令记下来——出问题时不用去百度，伸手就能用

当初觉得看日志好难，现在觉得不看日志才是真难。

下一篇预告：我的OpenClaw健康检查清单——再也不怕半夜崩了

小文AI踩坑记 · 小文AI实战笔记 番外篇