Codex 会话管理实战：归档、取消归档、删除与按名字找回

2026-08-09

用 Codex（OpenAI Codex）的命令行久了，迟早会撞上同一个问题：历史会话越攒越多，想找回上周那次调试记录，选择器里翻半天也翻不到；想清理一下，又怕手一抖把有用的记录删干净。这篇专门讲 Codex CLI 这一侧的会话管理——归档、取消归档、永久删除，以及怎么把一个旧会话续回来。

先说一句边界：本文里凡是标「本机实测」的，都是在 codex-cli 0.147.0（Windows 11）上执行只读命令得到的输出，我们没有发起过任何模型对话请求，所以你不会在下面看到「我跑了个任务，它花了几分钟」这类描述。命令形态和目录结构是实测的，涉及执行效果的地方我会明确标出来。

一、先看一眼你的磁盘，这事没你想的那么小

本机在 codex-cli 0.147.0（Windows 11）上执行 codex doctor --summary，Notes 区里有一行叫 rollouts，内容是 405 active files · 3.07 GB on disk。这台机器并不是什么重度使用的构建机，日常用一用，会话记录就到了三个多 G。

顺带说一句，同一台机器上 ~/.codex/ 里还有一个 SQLite 日志库 logs_2.sqlite，单个文件 763 MB。所以「磁盘被 Codex 吃了」这件事，会话文件是一部分，但不一定是全部——这个结论后面讲「什么情况不适用」时还要用到。

二、五条命令，各管一段，别混着用

codex --help 的子命令表里，跟会话相关的有这么几条（说明取自本机实测的 help 原文）：

子命令	官方说明
`resume`	Resume a previous interactive session（默认弹选择器，`--last` 直接续最近一次）
`fork`	Fork a previous interactive session
`archive` / `unarchive` / `delete`	按 id 或会话名归档 / 取消归档 / 永久删除已保存会话

这里有两个容易搞混的地方。

resume 和 fork 不是一回事。 resume 是接着原来那条线往下走，fork 是从一个历史会话分叉出新的一条。当你想在旧上下文的基础上试一个不同方向、又不想弄脏原记录时，用 fork 比 resume 合适。

archive 和 delete 的差距是不可逆的。 help 里 delete 写的是「永久删除」，unarchive 只对应 archive，没有任何一条命令说能撤销 delete。所以清理的标准动作应该是先 archive，观察一段时间确认真的用不上了，再考虑 delete——而不是直接上 delete。

三、命令怎么写

恢复一个会话

# 直接续最近一次，不进选择器，适合中断后马上回来
codex resume --last

# 不带参数会弹选择器，从历史列表里挑
codex resume

--last 的价值在于它绕开了选择器。当你的历史里已经躺着几百条 rollout 时，弹出来的列表本身就是个负担，能确定要续最近那次就别去翻。

非交互侧同理，codex exec 有自己的 resume 子命令，同样支持按 id 续或者 --last：

# 在脚本里续最近一次的 exec 会话
codex exec resume --last

# 或者按会话 id 续
codex exec resume <会话 id>

需要提醒的是，exec resume 自己还接不接别的参数（比如能不能同时把新的一轮指令带进去），不在我们的实测范围内。真要那么用，先跑一遍 codex exec resume --help，以你当次版本的输出为准。

归档、取消归档、删除

# 归档：从常用列表里挪走，但留底
codex archive <会话 id 或会话名>

# 取消归档：捞回来
codex unarchive <会话 id 或会话名>

# 永久删除：没有回收站，想清楚再敲
codex delete <会话 id 或会话名>

我们实测过的只有顶层 codex --help，这三条子命令自己的参数细节（有没有批量选项、支不支持通配）不在实测范围内。所以第一次用之前，请在你自己机器上先跑一遍 codex archive --help，以你当次版本的输出为准——版本会变，这一点下面还会再说一次。

「按名字找回」的老实说法

help 里写的是「按 id 或会话名」，也就是说这几条命令确实认名字，不是只认一串 id。但会话名从哪儿来、能不能自己指定，这个我们没有实测依据，本文不编。稳妥的做法是：先用不带参数的 codex resume 打开选择器，在里面确认目标会话的标识形态，再拿这个标识去喂 archive / delete。先看清楚再动手，比猜一个名字敲进去安全得多。

四、产出物长什么样：会话到底存在哪

本机在 codex-cli 0.147.0（Windows 11）上查看 ~/.codex/（也就是 CODEX_HOME），跟会话直接相关的条目有这么几个：

sessions/：会话 rollout 的落盘目录，按年份分子目录，本机是 2026/
archived_sessions/：归档会话
history.jsonl：历史记录
logs_2.sqlite（含 -shm / -wal）：SQLite 日志库

Windows 上这个目录就是 %USERPROFILE%\.codex\，Git Bash 里写 ~/.codex/ 是同一个地方。

有一点必须说明白：sessions/ 和 archived_sessions/ 这两个目录都是本机实测看到的，但我们没有真的执行过 codex archive 去观察文件是怎么从前者挪到后者的。目录名字摆在那儿，你我都能猜到大概是怎么回事，但猜出来的东西不能当结论用。真要确认，就在你自己机器上归档一条无关紧要的会话，前后各看一次这两个目录的文件数。

至于 rollout 文件内部的字段结构，本文一个字都不写——没取过，不编。

五、怎么验收：拿 doctor 当量尺

会话管理最难受的地方是「操作完了看不出变化」。好在 codex doctor 提供了几个可以对照的抓手。本机在 codex-cli 0.147.0（Windows 11）上执行 codex doctor --summary，观测到的相关检查项是：

Notes / rollouts：本机显示 405 active files · 3.07 GB on disk。这是最直观的一把尺子——归档或删除一批会话后再跑一次，看这两个数字有没有降下来。
Environment / threads：本机提示 rollout files and state DB thread inventory agree，即磁盘上的 rollout 文件和状态数据库里的清单是对得上的。这条检查比对的是磁盘上的 rollout 文件与状态库里的清单，按它自己的定义推断，绕过命令去 sessions/ 里手动删文件，很可能先在这里露馅——不过我们没有实测过删除之后这条检查的实际表现，以你自己机器上跑一次 doctor 的输出为准。
Environment / state：本机显示 databases healthy。
结尾统计行本机形如 17 ok · 1 idle · 1 notes · 0 warn · 0 fail ok，并提示可以用 --all 展开被截断的列表。

所以验收动作可以固化成三步：

# 1. 动手之前先记一次基线
codex doctor --summary

# 2. 执行归档或删除
codex archive <会话 id 或会话名>

# 3. 再跑一次，比 rollouts 计数和 threads 一致性
codex doctor --summary

最容易出错的是哪一步？是第二步之前的目标确认。选择器里相邻两条会话可能长得很像，一旦 delete 敲下去没有回头路。另一个坑是有人图快直接去文件系统里删——rollouts 的数字确实会掉，但 threads 那条一致性检查就未必还能保持 agree 了，这种不一致比多占几个 G 麻烦得多。

补一句排查经验：本机实测过，如果 config.toml 写坏了（比如 codex -c 'features=[unclosed' doctor --summary），doctor 不会崩，照样跑完，但会打出 ✗ config config could not be loaded。所以「我改了配置怎么没生效」的第一步永远是跑 doctor 看这一行，而不是反复重启 CLI。

还有一条对协作有用的：codex doctor --json 的官方说明是 “Emit a redacted machine-readable report”，是脱敏的输出。要把诊断结果贴给同事或提到 issue 里，用这个比截屏安全。

六、几个跟会话留存直接相关的配置键

官方《Configuration Reference》里跟这件事沾边的键：

键	取值 / 默认	说明
`history.persistence`	`save-all` 或 `none`	历史是否落盘
`history.max_bytes`	—	历史体积上限
`tui.resume_cwd`	`current` / `session`	恢复会话时用当前目录还是原会话的目录
`log_dir`	默认 `$CODEX_HOME/log`	日志目录
`sqlite_home`	—	SQLite 存放位置

tui.resume_cwd 这个键值得单独说。续一个旧会话时，工作目录是沿用你现在所在的目录，还是回到当初那个会话的目录，行为完全不同——如果你习惯在不同仓库之间跳，这个键设错了，恢复出来的会话很可能对着错的目录干活。命令行侧还有 -C, --cd <DIR> 可以显式指定 agent 的工作根目录，拿不准的时候显式写出来最省心。

另外，codex exec 有一个 --ephemeral 选项，官方说明是不把会话文件落盘。批量跑一次性任务时挂上它，从源头上就不会往 sessions/ 里堆东西——这比事后归档划算得多。

# ~/.codex/config.toml 片段
[history]
persistence = "save-all"

[tui]
resume_cwd = "session"

以上为按官方文档键位组合的示例，未逐项实测，以官方文档为准。

顺带提醒：~/.codex/auth.json 是登录凭据，官方明确要求当密码看待。清理 CODEX_HOME 的时候，别顺手把它一起处理了，也别把整个目录打包发给别人。

七、什么情况不适用

一、桌面应用那侧的「聊天」不归这几条命令管。 官方《Troubleshooting》里对「找不到已归档的聊天」给的做法是去 Settings 里找归档聊天，取消归档后会回到原来的侧栏位置；对「侧栏只显示部分聊天」给的做法是点 “Chats” 旁的筛选图标选 “Chronological”，同时去 Settings 查归档。这些是官方文档口径的桌面应用操作，我们没有实测过，也别拿 CLI 的 codex archive 去套。

二、指望删会话解决磁盘问题，可能会落空。 本机那三个多 G 的 rollouts 之外，还有一个 763 MB 的 SQLite 日志库。删干净会话不等于磁盘就宽敞了，动手前先看清楚大头在哪。

三、--ephemeral 跑出来的东西没得恢复。 既然不落盘，就不存在归档和 resume。图省事挂了这个选项，就别指望第二天还能续回来。同理，如果把 history.persistence 设成 none，也是一样的道理。

四、有留存和审计要求的场景，别把 delete 当日常清理手段。 它写的就是永久删除，没有撤销命令。合规相关的记录该怎么留，走你们自己的流程，不要依赖一个 CLI 子命令的默认行为。

五、别用记忆里的版本号做判断。 本机采集时有个很实在的现象：开头执行 codex --version 得到 codex-cli 0.131.0，十几分钟后同一条命令得到 codex-cli 0.147.0，而 which -a codex 全程只有一个可执行文件。Codex 具备自更新能力（config 里 check_for_update_on_startup 默认 true），所以子命令的参数形态、doctor 的检查项名字都可能随版本变。排查任何跟版本有关的问题，都以你当次 codex --version 的实时输出为准。

收个尾

会话管理这件事，说到底就三个动作：归档留底、确认再删、恢复前先看清工作目录。 再配上一句「动手前后各跑一次 codex doctor --summary」，基本就不会出大问题。真正的坑不在命令本身，而在于绕过命令去手动删文件、以及把 delete 当成 archive 用。