04-运维 · 06 每周维护编排

预计阅读：10 分钟适用版本：公开稳定包 OpenClaw 2026.5.2；作者端已验证 2026.5.7 · 最后审核：2026-05-09 前置：00-健康检查 / 02-配置/01-记忆系统目标：看懂 run-weekly-maintenance.py 这条周维护链到底做什么、哪些步骤是必须成功、哪些只是可选能力

为什么周维护不能只靠“想起来再跑”

OpenClaw 长期运行后，慢性问题通常不是当天爆，而是周级累积：

LanceDB fragments 越堆越多
记忆文件越来越碎
图谱重建长期没跑
监控脚本默默失效但没人发现

所以这条链的目标不是“出事后抢修”，而是每周固定做一次保洁和校准。

当前周维护是四步链

run-weekly-maintenance.py 现在按 A-B-C-D 四步编排：

步骤	作用	是否必须
A. LanceDB compaction	压缩和清理向量记忆碎片	必须
B. Memory consolidation	合并和整理记忆层内容	必须
C. Graphify rebuild	图谱重建	可选
D. Lance monitor	跑监控统计	可选

这里最关键的一点是：必需步骤失败必须真的失败，不允许静默跳过。

这是这条脚本相比很多“看起来没报错”的 cron 脚本更重要的地方。

每一步具体在做什么

A. LanceDB compaction

优先使用：

~/.openclaw/scripts/run-compact.mjs

如果这份脚本不在，才会退到：

openclaw memory compact --plugin memory-lancedb-pro

这里的原则非常硬：

缺脚本不是“正常跳过”
CLI 也不可用时，整个周维护应判失败

因为这一步如果长期不跑，fragments 累积会直接拖慢记忆召回。

B. Memory consolidation

这一层通常调用：

~/.openclaw/scripts/consolidate-memory.py

它属于必须步骤，因为你的记忆系统不是只靠向量库，还依赖更高层的整理和沉淀。

C. Graphify rebuild

这是可选能力。

如果本地存在：

~/.openclaw/scripts/graphify/rebuild-graph-if-needed.sh

就执行；如果没有，就明确记一条 SKIP。

也就是说：

没装 Graphify，不算周维护失败
装了 Graphify 但脚本本该存在却跑挂了，就该算失败

D. Lance monitor

这一步也是可选能力。
常见入口是：

~/.openclaw/scripts/run-lance-monitor.py

没有就 SKIP，不是假装 OK。

现在最重要的语义：必须步骤不能静默成功

过去很多自动化脚本的问题不是“报错太多”，而是“明明没做，结果还显示成功”。

这条周维护链现在刻意避免了这种假绿灯：

A、B 缺失或失败：整条链返回失败
C、D 缺失：明确记 SKIP
C、D 已安装但执行失败：应当反映在结果里

这比“永远返回 0，看起来一片平静”更适合长期运维。

先跑 `--self-test`，再考虑定时

最稳妥的起点不是直接挂 launchd，而是先跑：

python3 ~/.openclaw/scripts/run-weekly-maintenance.py --self-test

它主要会检查：

openclaw CLI 是否存在
compact 能力是否存在
consolidate-memory.py 是否存在
graph rebuild 能力是否存在
run-lance-monitor.py 是否存在

这里的判断也分层：

缺关键能力：应视为失败
缺可选能力：通常记 WARN

先把这一步跑通，再上定时任务，能省掉很多“挂上去才发现脚本根本不存在”的低级问题。

手动执行建议顺序

# 1. 先做自检
python3 ~/.openclaw/scripts/run-weekly-maintenance.py --self-test

# 2. 自检通过再跑真正维护
python3 ~/.openclaw/scripts/run-weekly-maintenance.py

# 3. 跑完后看日志
tail -n 100 ~/.openclaw/logs/weekly-maintenance.log

# 4. 如有异常，再补看运行时状态
bash ~/.openclaw/scripts/runtime-status-report.sh

不要一上来就定时化，更不要把失败日志吞掉。

日志怎么看

当前默认日志是：

~/.openclaw/logs/weekly-maintenance.log

看这份日志时，重点不是每一行 RUN:，而是看最后的汇总：

A 是否 OK
B 是否 OK
C 是 OK 还是 SKIP
D 是 OK 还是 SKIP

一个健康的结果通常是：

A=OK B=OK C=OK|SKIP D=OK|SKIP

如果你看到的是：

A=FAIL B=OK ...

先别看 graphify，先把 compaction 修好。
必需步骤优先级永远高于可选能力。

当前最容易踩的坑

坑 1：把脚本放在 `/tmp`

系统重启、清理缓存或升级后，/tmp 里的东西很容易没掉。
如果周维护关键脚本放在这里，定时任务迟早会“表面还在，实际没执行”。

公开文档里统一建议：

维护脚本放 ~/.openclaw/scripts/
定时器只引用稳定路径

坑 2：把可选能力当必需依赖

不是每个用户都装了 Graphify 或 monitor。
没装时应该明确 SKIP，而不是把整条链打成假失败。

坑 3：只看 launchd 已加载，不看脚本结果

launchctl list 只能说明任务挂上去了，不能说明任务真的跑对了。
判断周维护是否健康，还是要看 weekly-maintenance.log。

坑 4：一次失败后长期不复盘

周维护的价值在于“持续跑”。
一次失败不复盘，通常会演变成几周后才发现 fragments 已经积成一团。

和其他章节怎么配合

这条链最常和这几章一起用：

02-配置/01-记忆系统因为 compaction、consolidation、图谱重建都和记忆层直接相关
04-运维/00-健康检查因为 daily-digest 里常常会提前提示“本周该跑维护了”
04-运维/05-支持包与脱敏排障因为周维护失败后，往往值得顺手打包给作者看

红线：不要这样配周维护

❌ 不要缺关键脚本时还返回成功

这会制造最危险的假绿灯。

❌ 不要把所有能力都写死成强依赖

Graphify 和 monitor 是可选能力，不该反向拖垮所有用户。

❌ 不要只配定时，不做手动首跑

第一次一定先手动执行，确认日志和退出码都符合预期。

❌ 不要忽略 `--self-test`

这就是为了提前发现“脚本没装、CLI 不在、路径错了”这类问题。

验证清单

检查项	怎么验
自检能跑	`python3 ~/.openclaw/scripts/run-weekly-maintenance.py --self-test`
必需步骤可执行	compact 和 consolidate 的入口都存在
可选能力语义正确	没装 Graphify / monitor 时显示 `SKIP`，不是假 `OK`
日志可读	`~/.openclaw/logs/weekly-maintenance.log` 持续有新记录
首次手动执行通过	A、B 返回 `OK`
定时后可追溯	出问题时能从日志看出失败发生在 A/B/C/D 哪一步

下一步

05-排障/00-常见问题 —— 定时任务静默失效时怎么查
07-实战/11-记忆候选到周合并的完整链路 —— 周维护之外，周审记忆链还要做什么
06-升级/00-npm升级兼容 —— 升级后维护脚本为什么会失配

本章准确性保证 本章按当前模板里的 run-weekly-maintenance.py 实际执行顺序、失败语义和 --self-test 逻辑整理，所有脚本名和路径均对齐当前可交付模板，不包含作者本机私有路径。

导航：← 支持包与脱敏排障 · 📖 目录 · → 常见问题