跳转至

存储维护与保留

存储维护与磁盘控制

session.maintenance 控制 SQLite 会话行、SQLite 转录行、归档产物和轨迹伴随文件的自动维护:

Key Default Notes
mode "enforce" 或 "warn"(报告年龄、数量和磁盘预算策略,但不应用它们)
pruneAfter "30d" 过期条目的年龄阈值
archiveDashboardAfter "7d" 仪表盘归档阈值;false 或 0 仅禁用此触发器
maxEntries 5000 在保护允许时,未归档会话行的上限
preserveRecent 已禁用 保护交互式会话及其历史代的不活动窗口;false 禁用
resetArchiveRetention 保留(无年龄阈值) *.reset.*/*.deleted.* 转录归档的年龄阈值;设置时长即启用删除
maxDiskBytes 10gb 每个代理的会话磁盘预算;false、0 或 "0" 禁用
highWaterBytes maxDiskBytes 的 80% 清理后的目标值;解析为零的值使用默认值,负值无效
coldStorage.enabled false 在后台工作线程中将符合条件的不活动转录负载移动到压缩 JSONL 文件
coldStorage.afterDays 30 冷存储的正整数不活动天数阈值

重置边界会开启一个新的历史窗口,而不会删除较早的转录行。当会话轮换推进实时的 sessionKey -> sessionId 映射时,先前的 SQLite 会话、转录、轨迹和搜索行也会保留;普通条目和会话列表仅显示实时映射。保留的重置历史受磁盘预算限制,而不是受 resetArchiveRetention 限制,后者仅使归档产物老化。显式删除有所不同:它会在删除被删会话行的同一事务中,将压缩转录归档存储到 SQLite 并对其进行验证。当 zstd 可用时,它随后会发布、同步并读回派生的 *.jsonl.deleted.<timestamp>.zst 文件,然后才报告成功。

如果删除提交后归档文件导出失败,其规范归档会保留在 SQLite 中以便重试。创建无关的新会话不会重试该导出,也不会因此失败。解决文件错误后,重试删除以发布保留的归档,即使被删除的会话已经不存在。

归档会话会更改其可见性和保留元数据,同时将其转录行保留在 SQLite 中。将回收的历史转换为转录归档会用 SQLite 的 session_transcript_archives 表中的压缩规范 Blob 以及会话目录中的派生 JSONL 文件替换这些行。因此,压缩负载仍占用数据库空间;该文件不是其唯一副本。不支持 zstd 的运行时写入普通 JSONL 重置/删除归档。可选的冷转录存储会将不活动的转录负载完全移出 SQLite;pruneAfter 控制会话保留,resetArchiveRetention 控制重置/删除归档的删除。

maxDiskBytes 强制执行使用物理字节:每个代理的 SQLite 主文件、其 -wal 文件以及代理会话目录中计入的文件。它从不估算行 JSON 大小,也不从该总和中减去逻辑行大小。这是一个清理预算,而不是保证的物理上限:受保护的历史和暂时无法回收的数据库页面可能使使用量高于目标。

网关模型运行检查会话(键匹配 agent:*:explicit:model-run-<uuid>)具有单独的固定 24h 保留期。此修剪受压力门控:仅当达到会话条目维护/上限压力时运行,并且仅在全局过期条目清理/上限步骤之前运行。其他显式会话不使用此保留期。

当总物理使用量超过 maxDiskBytes 时,mode: "enforce" 首先回收可检查点的数据库空间,然后删除最旧的保留重置/删除归档。如果使用量仍高于 highWaterBytes,它会按 sessions.updated_at 遍历历史 SQLite 会话,从最旧的开始。历史表示该会话 id 未被实时会话条目、路由目标或已准入/进行中的运行引用。对于每个目标,清理会在删除会话行及其转录、轨迹、活动、索引和 FTS 投影的同一写入事务中存储压缩归档。提交后,它会发布、同步并读回派生文件。这包括包含轨迹事件但不包含转录事件的会话。如果这些层级不足,清理会永久删除记录归档原因为 active-session-cap 的最旧会话。手动、遗留、年龄保留、过期仪表盘和恢复归档保护每一代历史。清理在删除时重新检查条目身份和准入引用,在每个目标之后重新测量物理使用量,并在 highWaterBytes 处停止。

已提交的写入和删除首先落入 WAL。清理尝试在不等待读取者的情况下截断它。如果截断被阻塞,在 PASSIVE 检查点将每个观察到的 WAL 帧复制到主数据库后,清理可以继续;部分检查点仍会延迟清理。增量 vacuum 从主文件返回符合条件的空闲尾部页面。保留的 WAL 字节和尚未可回收的页面仍会计入下一次物理测量。mode: "warn" 报告当前物理超额,而不执行检查点、写入归档或删除行。

在大量清理后进行完整文件重写时,请使用 Doctor 的离线 --session-sqlite compact 模式。 它会检查点 WAL 并运行 VACUUM;它不会选择额外的历史记录用于删除,也不会用摘要替换对话内容。在大型安装上更改保留策略之前,请先参见 在副本上测试清理。

按需运行维护:

openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce

maxEntries 统计未归档的会话行;已归档的行不会占用上限。清理会归档最旧的符合条件的普通会话,直到未归档总数达到 maxEntries,或没有可处理的对象剩余。已固定会话、活动或已接纳的工作、模型锁定会话,以及持久外部对话指针(例如群会话和线程范围聊天会话)仍受保护,因此受保护行可能使未归档总数高于上限。合成运行时条目(cron、hooks、heartbeat、ACP、sub-agents)仍为可丢弃项,一旦超过配置的年龄、数量或磁盘预算,仍会被移除。隔离的 cron 运行使用独立的 cron.sessionRetention 控制,独立于模型运行检查保留。

每次新归档都会自动记录结构化原因。显式归档操作记录 manual;数量上限和过期仪表盘维护分别记录各自原因;pruneAfter 以 age-retention 归档符合条件的持久会话,同时删除可丢弃自动化;恢复归档记录 restart-recovery。Control UI 会渲染人类可读的说明。缺失或无法识别的原因会被视为受保护的遗留状态,而不是被推断。

--dry-run 预览未归档行上限,并识别满足该上限的非受保护行;--enforce 立即应用该清理,但不会移除保护。要减少受保护历史,请取消归档、取消固定、等待活动工作完成,或显式删除你不再希望保留的会话。

常规 Gateway 写入通过会话访问器进行,该访问器通过运行时写入器路径序列化每个 agent 的 SQLite 变更。运行时代码应优先使用 src/config/sessions/session-accessor.ts 中的访问器辅助函数;旧版 sessions.json 辅助函数是迁移和离线维护工具。当 Gateway 可达时,非 dry-run 的 openclaw sessions cleanup 和 openclaw agents delete 会将存储变更委托给 Gateway,使清理加入同一写入器队列;--store <path> 是针对选定旧版存储的显式离线修复路径,并且始终保持本地(--dry-run 也是如此)。对于生产规模的存储,maxEntries 清理是批处理的,因此在下次高水位清理将其重写降低之前,未归档数量可能短暂超过配置上限。Gateway 启动期间,读取永远不会修剪或限制条目。常规条目写入会在下一个年龄边界触发一次合并后的后台处理,并在该数据库连接保持打开期间每 30 分钟重新检查一次,因此保留策略可以在没有更多流量的情况下运行。未变化的年龄/数量事实可让写入跳过维护候选扫描。openclaw sessions cleanup --enforce 会立即应用上限,并修剪旧的未引用旧版转录、检查点和轨迹产物,即使未配置磁盘预算。

后台计划在写入器事务外准备,然后在提交前重新检查选定行、转录版本和会话保护。无关写入不会取消该计划。冲突输入最多获得三次立即规划尝试,之后维护会暂停,直到后续写入;已确定的拒绝会保留 worker 连接。保留策略和存储数据格式保持不变。

OpenClaw 不再在 Gateway 写入期间自动创建 sessions.json.bak.* 轮换备份。当前模式拒绝旧版 session.maintenance.rotateBytes 键,并且 openclaw doctor --fix 会从旧配置中移除它。

迁移恢复原始文件和精确的 Doctor 前恢复文件独立于普通会话保留:它们被排除在活动会话磁盘预算之外,并且没有自动过期。验证升级后,使用 openclaw update cleanup --dry-run 在线检查它们。显式离线 更新清理 可以退役已验证的原始文件,而不会移除当前 SQLite 历史;从磁盘预算中排除并不等于删除权限。

转录变更通过会话访问器和 SQLite 写入器队列进行。 每个变更都会在其提交事务内验证活动运行的持久写入器声明,因此被取代的运行无法写入转录。

插件生命周期清理在加载其条目和已保存快照之前,从元数据中选择旧的匹配会话。它分页规划孤立的转录窗口,并在页之间释放读取事务。删除仍会在归档准备后重新检查当前引用、选定条目、转录快照和活动生命周期权限。此规划变更不需要更新迁移;保留和归档持久性保持不变。

冷转录存储

启用冷存储,可将较旧的转录负载保存在压缩的 .jsonl.zst 文件中,同时在 SQLite 中保留其会话身份:

{
  session: {
    maintenance: {
      coldStorage: { enabled: true, afterDays: 30 },
    },
  },
}

当前和历史转录窗口都可以符合条件,只要其活动早于 afterDays。逻辑会话上的近期活动或运行状态会保护其当前窗口;历史窗口使用其自身的活动和运行状态。恢复所有权、实际运行接纳以及检查点等显式历史引用会继续保护所需窗口。固定或归档会话不算作持续活动,也不会仅凭此将其负载保留在 SQLite 中。Gateway 会在启动时和每分钟检查一次,运行具有 128 个转录和 64 MiB 工作预算的后台批次,而无需新消息。对这些设置的更改适用于未来工作,无需重启 Gateway;关闭该功能不会丢弃或遗留现有冷历史。

coldStorage.enabled 是独立的可选启用策略。即使 session.maintenance.mode 为 warn,它也会运行;该模式控制基于年龄、数量和磁盘预算的清理。禁用 coldStorage.enabled 可停止未来的提取。

打开聊天、请求历史记录以及频道写入会在使用前异步恢复冷历史。批量 sessions.preview 请求会保持载荷已归档,并返回明确的 cold 状态,以便菜单预热不会重新填满数据库。会话列表也会保持冷载荷已归档。当转录标题字段尚未缓存时,列表会使用会话元数据,并在历史恢复之前省略最后一条消息预览。 低层同步转录 API 在转录处于冷状态时会返回需要恢复的错误;其调用方必须先等待异步恢复完成。存储和使用量清单可以在不恢复的情况下统计冷转录。文本搜索会排除冷转录内容,并报告它排除了多少已归档转录;恢复后的转录会再次可搜索。导入和跨存储修复会拒绝尚未恢复的冷转录,而不是复制不完整的历史。

恢复后,正在运行的 Gateway 会将该转录保持热状态 24 小时,以避免反复提取最近查看的历史。此冷却期是进程本地的,并在进程重启时重置。未压缩 JSONL(包括恢复元数据)超过 64 MiB 的转录会保留在 SQLite 中;该上限限制恢复内存和 worker 时间。

worker 会在受保护事务记录其位置并删除相应转录行之前,写入、同步并验证一个不可变归档。归档会保留原始序列化事件及其恢复元数据。失败或中断的准备过程会保持 SQLite 转录完整。在事务未提交之前发布的文件可能作为未引用的归档保留。

冷归档位于 agent 的会话工件目录下的 cold/ 中。它们是权威历史,而不是可丢弃的缓存。重置/删除归档保留和普通磁盘预算清理不会删除它们。转录恢复后文件仍会保留,以便进行中的备份仍能捕获其原始快照。因此,冷存储会减少工作数据库;它并不保证每次维护运行后总磁盘使用量都会缩小。后台维护会对 SQLite 做检查点,并在有界的 worker 传递中回收空闲页,包括没有新归档候选项的后续传递。因此,物理数据库大小会逐渐缩小;读取器可能会延迟回收。需要完整重写时,请使用 Doctor 的离线 compact 操作。

如果归档缺失,或其记录的大小或哈希不匹配,读取或恢复该转录会明确失败。OpenClaw 不会替换为空转录。请从备份中恢复匹配的文件,或恢复完整的支持的数据库备份;校验和无法重建已删除的字节。在启用提取之前,请保留独立备份。

不需要转录内容的更新可以在归档缺失时成功。它会保留冷引用;更新软件包不会恢复缺失的历史。

用于完整归档、SQLite 快照和 Git 备份的支持备份命令会在其私有数据库副本中嵌入经过验证的冷载荷。其恢复的数据库是自包含的,不需要原始归档目录。启用冷存储后,后台维护会将这些嵌入的压缩载荷移回经过验证的归档文件,从而允许回收其数据库空间。这不会将转录解包为事件行。设置会将这些移动与新归档的转录分开报告。直接数据库复制也需要 cold/ 文件;参见 备份冷转录。

冷存储使用 agent 模式 20。 请使用支持的更新路径和经过验证的升级前备份。在冷载荷已从事件表中移出后,旧版本构建不得打开数据库,因此降低模式标记不是降级流程。

SQLite 切换后降级

停止 Gateway 并备份其状态。使用当前支持 SQLite 的 OpenClaw 版本,在启动旧的文件支持版本之前,恢复已归档的旧版会话存储和转录工件:

openclaw doctor --session-sqlite restore --session-sqlite-all-agents

迁移会将导入的热转录 JSONL 文件以及经过验证、完全覆盖的旧版 sessions.json 存储归档到 session-sqlite-import-archive/。 覆盖不完整或存在阻塞迁移问题的旧版存储会保留在原位。旧的文件支持运行时在启动前需要 sessions.json 及其 sessionFile 路径引用的工件位于原始位置。

恢复会使用迁移清单,仅移动原始路径缺失的已记录归档工件,报告冲突而不是覆盖现有文件,并保留 SQLite 数据库以便向前恢复。

由 openclaw update cleanup 退役的原始文件无法再从迁移归档中恢复。恢复会报告有意处置或待清理,而不是将其中任何一种视为意外缺失的文件。如果在处置后需要这些文件,则需要包含旧版工件的独立备份;参见 更新前备份。

恢复不会导出迁移后仅在 SQLite 中做出的更改。SQLite 切换后创建的会话仅存在于 SQLite 中,不会显示在旧的文件支持运行时中。如果在降级后重新升级,请再次运行 Doctor 检查和验证序列,以便 OpenClaw 可以在导入前验证恢复的旧版工件。

定时任务会话和运行日志

隔离的 cron 运行会创建自己的会话条目/转录,并具有专用保留策略:

  • cron.sessionRetention(默认 "24h")会从存储中清理旧的隔离 cron 运行会话;false 或零时长(如 "0h")会禁用该功能。
  • 终端运行历史保留 7 天(lost 行保留 24 小时),每个作业最多保留最新的 2000 行,并且历史类别作为额外上限强制执行。

当 cron 强制创建新的隔离运行会话时,它在写入新行之前会清理之前的 cron:<jobId> 会话条目:它会保留安全的偏好设置(thinking/fast/verbose/reasoning 设置、标签、显示名称)以及用户明确选择的模型/认证覆盖项,但会丢弃环境会话上下文(频道/群组路由、发送/队列策略、提权、来源、ACP 运行时绑定),以便新的隔离运行不会从旧运行中继承过期的投递或运行时权限。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw