OpenClaw Session 清理指南：手动定点删除 vs cleanup 全局维护

很多人在清理 OpenClaw 里的旧 session 时，容易把两类操作当成一回事：

  1. 手动删除指定 session
  2. 运行 openclaw sessions cleanup --all-agents --enforce

但这两者其实差别很大。

前者更像定点手术，后者更像按规则跑一遍系统保洁。

如果你的目标是“我就要把这几个指定 session 立刻删掉，并让它们马上从列表里消失”，那通常不能简单把它等同于 cleanup。

一、这次手动做的到底是什么

这次做的是：手动、精确删除指定 session。

核心动作分两步：

  1. 先删指定 session 的 transcript 文件 *.jsonl
  2. 再删对应 agent 的 sessions.json 里的索引条目

目标很明确：

让这几个指定 session 立刻从列表里消失。

这种方式的特点

  1. 按你指定的 session 删
  2. 不依赖 OpenClaw 的保留策略
  3. 可以删除“规则本来未必会清”的 session
  4. 风险也更直接：删错就是删错，没有策略兜底

所以它适合“我知道自己要删谁，而且希望立刻见效”的场景。

二、openclaw sessions cleanup --all-agents --enforce 是什么

从命令帮助的语义来看，这条命令做的事情不是“精确删除指定对象”，而是：

1）cleanup

表示跑一遍 session-store maintenance。

也就是：

  • 按 OpenClaw 自己的维护规则处理 session store
  • 执行一轮基于策略的清理或维护

2）--all-agents

表示对 所有 agent 执行，而不只是默认 agent。

3）--enforce

表示：

  • 即使当前配置只是 warn 模式
  • 也强制执行实际维护动作

它的含义不是“更彻底地乱删”，而是：

把本来只提醒、不真正执行的维护规则，正式执行掉。

三、最关键的差别在哪里

差别 A：是不是按“指定目标”删除

我们这次的方式

删的是你明确点名的那几个 session。

比如：

  • 这 5 个 session 就是要删
  • 其他 session 不动

cleanup --all-agents --enforce

删的是 符合维护规则 的 session，
不是按你手工点名删除。

所以两者最核心的区别就是：

  • 手动删除：以你的名单为准
  • cleanup：以系统规则为准

差别 B：会不会处理“文件已丢失，但索引还在”的脏数据

默认情况下，不一定会处理。

这里有个非常关键的参数：

1
--fix-missing

它的含义是：

Remove store entries whose transcript files are missing

也就是：

删除那些 transcript 文件已经不存在，但索引条目还残留在 store 里的记录。

这点非常重要，因为它直接对应一种常见异常情况：

  1. jsonl 文件没了
  2. 但 sessions.json 里的索引还在
  3. 结果 sessions_list 里还能看到旧 session

这意味着什么

如果你只是运行：

1
openclaw sessions cleanup --all-agents --enforce

它的重点是：

  • 执行维护策略
  • 但不保证会清掉“缺 transcript 的残留索引”

如果你遇到的是这次这种情况，更接近应该用的是：

1
openclaw sessions cleanup --all-agents --enforce --fix-missing

四、为什么这次没有直接用 cleanup 命令

因为这次的目标非常明确：

  1. 指定一批 session
  2. 立刻删除
  3. 立刻从列表里消失

而 cleanup --all-agents --enforce 至少有两个不确定点：

  1. 它按策略处理，不按你的指定名单处理
  2. 如果没有 --fix-missing，不一定会处理残留索引

所以在这种场景下，手动定点删除会更可控。

换句话说：

  • 如果你要的是“系统按规则维护一遍”，用 cleanup
  • 如果你要的是“这几个我点名的 session 现在就消失”，手动删更直接

五、实际该怎么选

不同目标，适合不同方案。

方案 1：你知道自己要删谁

更适合用手动方式：

  1. 删除对应 transcript
  2. 删除 sessions.json 里的对应 key

例如：

删除 transcript

1
rm -f ~/.openclaw/agents/<agent>/sessions/<session-id>.jsonl

删除索引 key

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
python3 - <<'PY'
import json
from pathlib import Path

path = Path('/Users/mm/.openclaw/agents/<agent>/sessions/sessions.json')
keys_to_remove = [
    '你的 session key 1',
    '你的 session key 2',
]

data = json.loads(path.read_text())
for key in keys_to_remove:
    if key in data:
        del data[key]
        print('REMOVED', key)
    else:
        print('NOT_FOUND', key)
path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + '\n')
PY

适用场景

适合：

  1. 精确清理
  2. 只删少量历史 session
  3. 不想影响别的 agent 或其他 session

方案 2：你想做系统级保洁

更适合先跑 cleanup。

建议顺序如下：

先 dry-run 看结果

1
openclaw sessions cleanup --all-agents --dry-run

再看缺 transcript 的脏索引会不会被处理

1
openclaw sessions cleanup --all-agents --dry-run --fix-missing

确认后再真正执行

1
openclaw sessions cleanup --all-agents --enforce --fix-missing

适用场景

适合：

  1. 全局维护
  2. 扫描老旧 session
  3. 修复缺失 transcript 的脏索引

这种方式更像批量保洁，不适合把它理解成“我指定删谁，它就删谁”。

六、两种方式怎么理解最准确

可以把它们这样区分：

手动删除

是定点手术。

特点是：

  • 指哪删哪
  • 删除范围明确
  • 可控性强
  • 风险也更集中

cleanup 命令

是规则驱动的全局维护。

特点是：

  • 按系统维护规则执行
  • 更适合整体验证和批量保洁
  • 是否删、删哪些，取决于规则和参数

如果你只是想处理某几个已知对象，不一定需要上升到全局 cleanup。

七、针对这次场景的实用判断

如果你的问题是：

  • jsonl 没了
  • sessions.json 里的索引还在
  • 列表里还能看到这个 session

那么从语义上说，最接近的 cleanup 命令应该是：

1
openclaw sessions cleanup --all-agents --enforce --fix-missing

但即便如此，它仍然和“手工定点删除指定 session”不是一回事。

原因很简单：

  1. 它还是按规则执行
  2. 不是按你的明确名单逐个删除
  3. 在需要强可控、强确定性的情况下，手动方式仍然更稳

八、一句话结论

可以直接记住下面这 4 句：

  1. 这次操作 = 精确删除指定 session
  2. cleanup --all-agents --enforce = 按 OpenClaw 配置规则做全局维护
  3. 如果你想处理“文件没了但列表还在”，要特别关注 --fix-missing
  4. 就这次场景来说，更接近的是：
1
openclaw sessions cleanup --all-agents --enforce --fix-missing

但它仍然不如手工定点删除可控。

九、建议怎么用最稳

最后给一个实用建议：

当你只想删少量、明确指定的 session

优先手动删除：

  1. 删除 transcript
  2. 删除索引 key

当你想做一轮全局维护

优先这样执行：

  1. openclaw sessions cleanup --all-agents --dry-run
  2. openclaw sessions cleanup --all-agents --dry-run --fix-missing
  3. 确认结果后，再执行：
    openclaw sessions cleanup --all-agents --enforce --fix-missing

这样既能保留可控性，也能避免把 cleanup 命令误当成“精确删除工具”。