# Lesson 03｜稳定性工程：Gateway 抖动、日志膨胀、故障回归验证

# 核心问题

当 OpenClaw 进入“长期运行 + 多 cron + 多来源抓取”的阶段，系统问题会从“功能不对”转变为“稳定性不够”：

• 网关偶发 timeout，导致排障命令也跑不动；
• 诊断日志无限增长，悄悄把磁盘打满；
• 修完问题但没回归验证，过两天又复现。

这一课讲稳定性工程的三件套：止损、抗抖、回归。

# 案例（真实）

# 案例 A：30G 诊断日志膨胀的止损修复（清理 + 关开关 + 验证）

这次事故的亮点不是“删了文件”，而是有完整闭环：量化→清理→关闭增量→验证网关运行与配置生效。

• 证据1：sessionKey=agent:main:telegram:group:-1003807921933:topic:524｜2026-03-03T12:59:28.210Z｜quote 摘要："~/.openclaw/logs/cache-trace.jsonl 达到 30G"
• 证据2：同 sessionKey｜2026-03-03T13:22:16.003Z｜quote 摘要："cacheTrace.enabled = False ..."
• 证据3：同 sessionKey｜2026-03-03T13:22:20.899Z｜quote 摘要："Gateway 在运行：running ... 配置已生效..."

# 案例 B：Gateway 超时抖动下，用“可用读操作”维持诊断闭环

同一排障窗口里多次出现 gateway timeout，但通过交替收集可返回的 status/list 输出，避免诊断完全阻塞。

• 证据1：sessionKey=agent:main:telegram:group:-1003807921933:topic:2319｜2026-03-02T00:29:36.229Z｜quote 摘要："Error: gateway timeout after 30000ms ..."
• 证据2：同 sessionKey｜2026-03-02T00:32:02.306Z｜quote 摘要："Error: gateway timeout after 120000ms ..."
• 证据3：同 sessionKey｜2026-03-02T00:32:09.675Z｜quote 摘要："... cron 列表里多个任务 status ok ..."

# 失败点（稳定性上最容易踩的坑）

1. 没有止损意识：日志膨胀是“慢性事故”，等磁盘满了才处理就晚了。
2. 把 timeout 当“再试一次”：单点命令重试会浪费窗口期；更糟的是你会误以为“系统全挂了”。
3. 修完不验证：关了开关但没确认生效；删了文件但网关没起来；最后变成“感觉修好了”。

# 关键转折：从“修问题”升级到“做机制”

稳定性工程的本质是机制：

• 让事故发生时可止损（磁盘/刷屏/资源占用）
• 让抖动时可继续推进（多探针、读操作兜底）
• 让修复可被证明（回归验证 + 可回滚点）

案例 A 给了一个很标准的机制闭环；案例 B 提醒我们：排障工具也会失效，所以诊断策略必须容错。

# 可复用 SOP：稳定性三件套（止损/抗抖/回归）

# 1) 止损（Damage Control）

• 量化：先确认体积/频率（例如“30G”这种量化证据）。
• 清理存量：删除/归档大文件（注意生产环境要可回滚，Unknown 的部分就标 Unknown）。
• 关闭增量源头：找到开关并关闭（证据：cacheTrace.enabled=false）。

# 2) 抗抖（Resilience under Jitter）

• 不依赖单一命令：当某条命令 timeout 时，换“读操作探针”继续收集状态（status/list）。
• 记录每次 timeout 的参数与时间（30s/120s 是重要线索）。
• Unknown：根因可能是资源占用/网络层/进程状态，但在证据片段里未给出结论，因此这里标 Unknown，不做推断。

# 3) 回归验证（Verification）

• 修复后必须做两类验证：
  1. 配置态验证：开关值是否如预期（证据：enabled=false）。
  2. 运行态验证：Gateway 是否 running、关键任务是否仍 ok（证据已给出）。
• 最好再补一条“后续巡检”来防回归（本案例 unknowns 里提到未见自动巡检证据，所以这里也是 Unknown）。

# 课后作业

1. 画出你当前系统的“稳定性三件套清单”：
   • 止损点：有哪些日志/缓存/输出可能无限增长？
   • 抗抖点：哪些关键命令可能 timeout？有什么替代读操作？
   • 回归点：你如何证明修复已生效？
2. 把一个你团队最近遇到的“慢性事故”（例如磁盘、重复通知、缓存膨胀）写成 10 行 Runbook：触发信号、止损动作、验证动作。
3. 加一条“Unknown 边界”训练：当你没有证据时，必须写 Unknown，并列出你要补的观测点（例如：资源占用、网关进程状态、日志增长速率）。