04-运维 · 00 健康检查

预计阅读：16 分钟适用版本：公开稳定包 OpenClaw 2026.5.2；作者端已验证 2026.5.7 · 最后审核：2026-05-09 前置：已完成 01-入门，有一个能跑的 OpenClaw 目标：建立日 / 周 / 月三个节律的主动健康检查

为什么需要主动检查

被动反应（“agent 不回了才想起看日志”）在 OpenClaw 这种长期运行系统里不够用。原因：

某些故障回应滞后 —— LanceDB fragments 涨到 700+ 才开始慢，此时已过去几周
某些 cron 任务静默失败 —— 维护脚本挂了，但你每天都在用 agent，不会发现
升级引入的兼容问题往往先出现在次要功能 —— 卡片 footer、心跳日志

主动检查 = 给系统装仪表盘。不出问题时无感，出问题时能在扩大之前发现。

三个节律

节律	做什么	怎么做
每日	基础连通 + 错误日志 + 关键 cron 是否在跑	`daily-digest.sh` 生成卡片推你飞书
每周	记忆压缩 + 日志轮转 + 任务清理	`run-weekly-maintenance.py`
每月	备份 + 记忆审阅 + 配置快照	手动 + 打包备份

本章先讲”每日” —— 这是作者 20+ 天运维里最高 ROI 的一环。

每日健康检查（daily-digest）

期望效果：每天早上 9:00，飞书收到一张卡片，一眼看出昨天 24 小时系统状态。

一张典型 digest 卡片的结构

📅 2026-04-17 · 周五 · 智能管家日报
───────────────
Gateway         ✅ 正常（128 MB · 18h 12m）
Cron 服务       ✅ 正常（5/5 已加载）
Memory          ⚠️ fragments 412（建议压缩）
Taskflow        ✅ 0 Blocked / 2 Doing / 1 Pending
昨日 ERROR      ✅ 0 条
昨日对话        💬 47 条（main 32 · planner 8 · minsu 7）
磁盘占用        📦 ~/.openclaw = 2.3 GB（+48 MB）
───────────────
💡 今日提示：memory fragments 已达 412，建议周末跑 weekly-maintenance

每个字段怎么来（简版）

字段	来源
Gateway 状态	`openclaw gateway health` 或 `curl http://127.0.0.1:18789/health`
Cron 服务	`launchctl list \| grep -E "openclaw\|claw"` 比对关键 plist 清单
Memory fragments	`ls ~/.openclaw/memory/lancedb-pro/memories.lance/data/ \| wc -l`（data/ 不是 _versions/）
Memory versions	`ls ~/.openclaw/memory/lancedb-pro/memories.lance/_versions/ \| wc -l`
Taskflow 状态	读 `~/.openclaw/taskflow/tasks.json`，按 status 分组计数
ERROR 日志	`grep -c 'ERROR' ~/.openclaw/logs/gateway.err.log` 昨日增量
对话数	读各 agent 的 sessions 目录，统计 messages.jsonl 行数
磁盘占用	`du -sh ~/.openclaw` + 对比昨日快照

阈值（作者 daily-digest.py 里硬编码）：

fragments > 500 → ⚠️ 黄灯（建议周末 compact）
fragments > 1000 → 🚨 红灯（立即跑 weekly-maintenance）

实现路径

作者的实现在 ~/.openclaw/scripts/daily-digest.sh（bash 版）+ daily-digest.py（Python 版，复杂度高用这个）。

核心思想：

每个字段是独立函数，失败不影响其他字段
输出是飞书卡片 JSON，通过 gateway API 发送
失败的字段显示 ❓ 并附简短原因，绝不静默隐藏

定时触发

用 launchd（macOS）。~/Library/LaunchAgents/com.openclaw.daily-digest.plist 示例骨架（注意：launchd 不展开 ~，所有路径必须用绝对形式，把下面的 /Users/你的用户名/ 替换成 echo $HOME 的真实输出）：

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.openclaw.daily-digest</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>-lc</string>
    <string>/Users/你的用户名/.openclaw/scripts/daily-digest.sh</string>
  </array>
  <key>StartCalendarInterval</key>
  <dict>
    <key>Hour</key><integer>9</integer>
    <key>Minute</key><integer>0</integer>
  </dict>
  <key>StandardOutPath</key>
  <string>/Users/你的用户名/.openclaw/logs/daily-digest.launchd.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/你的用户名/.openclaw/logs/daily-digest.launchd.err.log</string>
</dict>
</plist>

加载：

launchctl load ~/Library/LaunchAgents/com.openclaw.daily-digest.plist

卡片语义规范（三档色）

不要做 10+ 种状态色。作者用三档就够了：

颜色	含义	例子
🟢 绿	正常，无需干预	Gateway online
🟡 黄	需注意但不紧急，周末前处理	fragments 400+、磁盘涨太快
🔴 红	立即干预	Gateway 离线、ERROR > 10 条/日

非黑即白的字段（ERROR 数 > 0）用”数字本身”表达严重度，不要为了好看把 10 条 ERROR 涂成黄色。

为什么？ 因为你不能指望每天都认真读 digest。颜色必须和紧急度强绑定，这样你一瞥就知道今天要不要多看一眼。

每日巡检的”3 秒扫描法”

卡片到飞书后，你只看 3 个地方：

1. 标题栏：有没有 🚨 / 🔴        → 没有就先不慌
2. 中间状态表：有没有 ⚠️ / 🔴    → 有就点展开
3. 底部"今日提示"              → 有事要做就加到当天 todo

不要每天都细读所有字段。那样两周后你就烦了，开始无视卡片。

扩展：watchdog（监控监控的）

daily-digest 依赖很多组件（gateway、launchd、飞书 API）。如果这些组件本身挂了，你就收不到 digest，于是你不知道你没收到 digest。

解决：watchdog。

作者的方案（~/Library/LaunchAgents/ai.openclaw.watchdog.plist + ~/.openclaw/scripts/watchdog.sh）：

每小时跑一次
如果连续 3 次发现 gateway /health 不通 → 自动 restart
如果连续 5 次 restart 还不好 → 用备用通道（如 macOS 系统通知）告警

label 前缀注意：gateway 和 watchdog 用 ai.openclaw.*，其他 digest / maintenance 脚本用 com.openclaw.*。这是历史原因留下的两套命名，不是错配 —— 作者排查 cron 是否加载时要用 launchctl list | grep -E "openclaw\|claw" 把两套都抓上。

不要把 watchdog 也放 gateway 里。它必须是独立进程，否则”gateway 挂了 watchdog 也挂”这种单点问题就出现。

每周维护（简述）

详细见 02-升级流程，这里只列 checklist：

LanceDB fragments 压缩（> 100 就跑 compact）
日志轮转（gateway.log / 各类 .launchd.log 按大小/天数切）
删完成超过 7 天的 taskflow 任务
检查 ~/.openclaw/logs/ 总大小，> 500MB 压缩老日志
review 本周 memory/YYYY-MM-DD.md 有没有需要上卷到 MEMORY.md 的稳定规则

作者有个 weekly-distillation.plist + sunday-memory-digest.plist，周日凌晨自动跑一遍，周一早上看结果。

每月节律（简述）

全量备份 ~/.openclaw/（排除 memory/lancedb-pro 原始文件，备份 experience/ 等快照）
跑一次 openclaw doctor --strict（更严苛检查）
review 本月所有 ⚠️ 告警，看是否有重复模式 → 调整 SOUL 禁区或加自愈脚本
升级 OpenClaw CLI（见 06-升级/00-npm升级兼容）

红线：不要做的事

❌ 不要靠看日志做日常巡检

翻日志是出事之后的排查手段，不是每日运维。一定要建 digest 卡片，让状态主动推给你。

❌ 不要给自己发”所有正常”通知

OpenClaw 正常时你不想被打扰。digest 默认只在异常时发详情，正常时发一行 HEARTBEAT_OK 就够，或者干脆不发。

例外：每日 9:00 的 daily-digest 必须发，作为”活着”的证明。但正常时用淡绿色 + 一句话总结，不占注意力。

❌ 不要让 watchdog 判定逻辑过于激进

“一次 /health 失败就重启” 会在升级、网络抖动时乱杀进程。一般”连续 3 次失败 + 间隔 20 秒”才触发。

❌ 不要把所有检查塞进一个脚本

单一脚本出 bug 会导致全部检查失效。按”gateway / cron / memory / tasks / logs”拆成独立检查函数，各管一段。

监控指标清单（给架构偏好强的用户）

如果你想做更严的监控，以下是作者在用的指标（不一定要全做）：

类别	指标	阈值示例
Gateway	/health 响应时间	p95 < 200ms
Gateway	进程内存	< 500 MB
Gateway	服务启动路径	指向当前可用的 `openclaw/dist/index.js`
Memory	lancedb fragments（单表）	< 100
Memory	lancedb 总磁盘占用	< 1 GB
Logs	gateway.err.log 日增	< 10 条 ERROR
Cron	关键 plist 已加载数	== 预期列表长度
Taskflow	Blocked 任务数	== 0
Disk	~/.openclaw 总大小	< 5 GB

新增建议：把 gateway 服务路径纳入巡检

最近几次真实故障里，一个高频问题是：

shell 里的 openclaw 是好的
但 launchd / systemd 仍指向旧的 nvm 或 npm 全局目录

这会导致两类表象：

openclaw --version 正常，但 http://127.0.0.1:18789/ 打不开
Control UI assets not found 或 gateway 服务反复启动失败

所以 daily / housekeeper 巡检里建议额外检查：

bash ~/.openclaw/scripts/runtime-status-report.sh

如果报告里出现服务路径缺失、dist/index.js 不存在、Node 路径不可执行，优先修：

bash ~/.openclaw/scripts/repair-gateway-service.sh --repair --restart

这项检查比单纯 /health 更靠前，因为 /health 只回答“当前端口有没有活”，不能回答“服务下次重启还会不会活”。

下一步

01-日志与监控 —— 日志体系、告警路由
02-升级流程 —— npm 升级 + hotfix 打补丁
06-升级/03-CLI与Gateway版本统一 —— 处理 nvm / npm / launchd 路径漂移
03-备份与恢复 —— memory / 配置 / credentials 分层备份策略

本章准确性保证 所有 plist label、脚本路径、检查项都基于 ~/.openclaw/scripts/ + ~/Library/LaunchAgents/ 的真实文件验证。daily-digest 字段清单参考 daily-digest.sh 的真实实现（2026-04-17 生产版本）。

导航：← 共享规范 · 📖 目录 · → 日志与监控