长期运行的 OpenClaw 部署，sessions.json 和 transcript 文件会持续累积，官方为此内置了一套自动维护机制——本文基于官方文档详解 session.maintenance 配置项和 openclaw sessions cleanup 命令的使用方法。
两层持久化，都需要维护
Session Store（sessions.json）
键值映射：sessionKey -> SessionEntry
体积小，可变，可安全编辑（或删除条目）
记录会话元数据（当前会话id、最后活动时间、开关、
Token计数器等）
Transcript（<sessionId>.jsonl）
只追加的树状结构 transcript
存储实际对话内容+工具调用+压缩摘要
用于为后续轮次重建模型上下文
磁盘位置（按 agent 划分，位于 Gateway 主机上）：
Store: ~/.openclaw/agents/<agentId>/sessions/sessions.json
Transcripts: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
Telegram 话题会话：
.../<sessionId>-topic-<threadId>.jsonl
session.maintenance 配置项详解
mode "warn"（默认）或 "enforce"
pruneAfter 过期条目年龄阈值（默认 30天）
maxEntries sessions.json 条目数上限（默认 500）
rotateBytes sessions.json 超大时轮转（默认 10mb）
resetArchiveRetention
*.reset.<timestamp> 归档transcript的保留期
（默认与 pruneAfter 相同；false 表示禁用清理）
maxDiskBytes 可选的会话目录磁盘预算
highWaterBytes 可选的清理后目标值
（默认为 maxDiskBytes 的 80%）
enforce 模式下的清理执行顺序
这个顺序值得重点记住，理解它能帮你预判"哪些数据会先被清理掉"：
1. 优先移除最旧的归档或孤立 transcript 文件
2. 如果仍超出目标值，驱逐最旧的会话条目及其 transcript 文件
3. 持续执行，直到用量降至 highWaterBytes 或以下
换句话说，系统会先清理"确定不再需要"的归档/孤立文件，只有在这还不够的情况下，才会动到"活跃会话条目"这个更敏感的层级——这个先后顺序本身就是一种保守的安全设计。
warn 模式：只报告不动手
在 mode: "warn" 下，OpenClaw 只报告"潜在会被驱逐"的内容，
不会真正修改 Store 或文件
这也是默认模式——意味着开箱即用的 OpenClaw 部署不会自动删除任何数据，只会在日志/诊断中提示"如果切到 enforce 模式，这些内容会被清理"。如果你想真正启用自动清理，需要显式把 mode 改成 "enforce"。
手动执行维护命令
bash
# 先看看会清理什么，不实际执行
openclaw sessions cleanup --dry-run
# 真正执行清理
openclaw sessions cleanup --enforce--dry-run 是排查和验证配置的安全选项——在正式对生产环境启用自动清理之前，强烈建议先用这个命令确认清理范围和数据量符合预期，避免误删还需要的会话。
实战建议
1. 生产环境部署，即便暂时不打算启用 enforce 自动清理，
也建议配置合理的 maxDiskBytes / highWaterBytes，
这样至少能在 warn 模式下持续观察磁盘增长趋势
2. 启用 enforce 模式前，务必先跑一次
openclaw sessions cleanup --dry-run，
人工确认清理列表里没有还需要保留的重要会话
3. 大量使用 Telegram 话题会话的部署，注意这类会话
transcript 文件名带 -topic-<threadId> 后缀，
同样会被计入磁盘清理的统计范围
4. 如果对某些历史会话有长期归档需求（比如合规审计），
考虑用 resetArchiveRetention: false 禁用归档自动清理，
转而手动管理归档策略
5. Cron 密集型部署额外注意 cron.sessionRetention 和
cron.runLog.maxBytes/keepLines 这两组独立的保留控制，
它们不受 session.maintenance 统一管理
总结
OpenClaw 的 Session 磁盘维护机制设计得相当保守——默认只报告不删除（warn 模式），清理顺序优先动"确定不再需要"的归档/孤立文件，且提供了 --dry-run 这样的预演选项。对于长期运行的生产部署，理解并主动配置这套机制，是避免"某天磁盘突然写满导致服务中断"这类运维事故的重要一环。
来源：Session Management & Compaction Deep Dive — OpenClaw 官方文档