会话保存、延续与切换

会话默认会被保存，便于中断后继续；在非交互/脚本入口 codex exec 中，官方源码提供了 resume（恢复同一线程）与 fork（分叉出新线程）等子命令。本节先分清"续作原会话"与"另起探索线"，再讲保存机制、恢复与分叉的适用场景。注意：以下子命令属于 codex exec 脚本入口；交互界面内的对应操作与具体可用项以当前版本界面和官方文档、codex exec --help 为准。

一、会话保存机制

• 默认落盘：普通运行会把会话记录保存到本地，供后续恢复与追溯；会话与所在工作目录相关联。
• 一次性不留痕：脚本入口提供 --ephemeral 选项，运行时不把会话文件写入磁盘，适合临时、无需追溯的一次性任务。
• 配置位置：用户配置默认位于 $CODEX_HOME/config.toml（未自定义 CODEX_HOME 时对应默认用户目录下的 .codex/config.toml）；自动化环境若设置了 CODEX_HOME，配置随该目录走。
• 目录配套：恢复会话应回到对应项目目录；在错误目录下恢复，看到的上下文与工作区可能不匹配。

二、恢复同一线程：resume

能力	说明（脚本入口 codex exec resume）
按标识恢复	可按会话 ID（UUID）或线程名恢复指定会话；UUID 可解析时优先按 UUID 识别
恢复最近会话	使用 --last 直接选取最近（最新）的已记录会话，无需手填 ID
放宽目录过滤	默认按当前工作目录过滤会话；--all 用于显示全部会话、关闭目录过滤，便于找回跨目录记录
恢复后续作	恢复时可附带一条继续指令；未以参数给出时可从标准输入读取（以 - 表示读 stdin）
附加图像	可用 --image（短选项 -i）为恢复后的首轮补充图片输入

恢复的本质是把既有对话与工具结果作为上下文继续推进，适合"同一件事没做完、接着做"。

三、分叉新线程：fork

对比	resume 恢复	fork 分叉
对象	在原线程上继续写	以某历史会话为起点复制出一条新线程
原会话	被直接延续、状态向前推进	保留不动，新探索不污染原结论
典型用途	完成既定任务、延续讨论	尝试备选方案、对比不同改法、保留一条干净主线
输入	会话标识 + 可选续作提示	起始会话标识 + 可选后续提示与图片

当你想"基于前面的分析试另一条路，又不想打乱原进度"时，fork 比直接在原线程上改方向更稳妥。

四、何时恢复、分叉或新建

情形	推荐动作
同一任务中断、需接着完成	回到项目目录后 resume 原会话
想并行比较两种实现/方案	用 fork 从共同起点分出探索线
全新、无关的任务	直接开启新会话，避免旧上下文干扰判断
临时验证、无需留痕	使用 --ephemeral 一次性运行
结论需要长期复用	写入仓库文档或项目约定，而不是只留在某条会话历史里

五、常见问题排查

• 找不到目标会话：先确认当前目录；用 --all 关闭目录过滤再找；确认会话是否被归档或位于其他 CODEX_HOME。
• 恢复后响应变慢：长线程携带的历史多、推理更长；此时更适合新会话加文档交接（见下一节）。
• 恢复后结果与预期不符：检查工作目录是否正确、续作提示是否明确，避免旧线程里的旧假设被默认沿用。
• 会话文件不等于版本记录：代码改动仍以 Git 提交为准；会话历史是辅助追溯，不能替代提交与文档。

六、FAQ

问题	处理建议
交互界面里怎么恢复上次对话	以当前版本界面提供的入口为准；本节 resume/fork 描述对应脚本入口 codex exec，不把脚本参数等同于界面按钮。
resume 和 fork 一定二选一吗	目标是延续就 resume；要保留主线、另试方案就 fork；无关新任务直接新建。
--ephemeral 适合日常开发吗	不适合需要追溯的常规任务；仅用于一次性、无需保存的临时运行。
命令参数版本不一致怎么办	以本机 codex exec --help 与当前官方文档为准，不同版本子命令与选项可能调整。

七、动手练习

• 练习：为一次中断任务设计"恢复方案"：确认项目目录、判断应 resume 还是 fork、准备一条明确的续作提示；再为一个一次性临时验证选择 --ephemeral 的适用理由。