Codex会话（2026.08.10）

概念编号：037

一句话理解

Codex 会话是一条对话从开始到结束的完整持久化记录：不只是聊天内容，还包括它所在项目、用的模型、运行路径和归档状态——由一组互相依赖的文件共同管理，缺一不可。

一次 Codex 会话在磁盘上由以下部分构成：

正文文件：~/.codex/sessions/年/月/日/rollout-<时间戳>-<UUID>.jsonl，逐行记录用户输入、模型回复、工具调用与结果；
会话目录数据库：~/.codex/state_5.sqlite 的 threads 表，每条记录含 rollout_path、cwd（项目路径）、model_provider、title、置顶/归档状态等字段，这是桌面版界面显示会话列表的真正来源；
会话索引：~/.codex/session_index.jsonl，提供快速检索；
全局状态：~/.codex/.codex-global-state.json，记录会话与项目的分配关系、侧边栏排序和置顶；
归档会话：~/.codex/archived_sessions/，存放已归档的老会话正文。

这些文件必须保持一致：界面先查”目录页”（数据库/索引/状态），再按目录去读正文文件。任何一环节与其他不一致，会话列表就会出现异常。

Codex会话与 Codex（AI工作台）：Codex 是承载会话的环境和产品系统；会话是其中一次具体的任务记录。参见 Codex（AI工作台）（2026.08.08）。
Codex会话与项目：项目（cwd）是会话发生的工作目录，一个项目下可以有大量会话；会话通过 threads.cwd 字段归属项目，二者不是一一对应。
Codex会话与 Skill：Skill 是可复用的方法包，被会话中的 Agent 调用；Skill 跨会话复用，会话是单次执行记录。
Codex会话与云同步会话：走官方路由时云端账号的会话会被灌入本地 threads 表（provider 为 openai），这类会话没有对应的本地正文文件，是造成目录错乱的常见来源。
本卡聚焦”会话作为持久化数据单元”的组成与恢复，不展开模型、平台与产品版本差异。

日常在苏苏OB知识库打开 Codex 处理任务，每轮对话生成一个 rollout-2026-08-09T...jsonl 文件，同时在 threads 表登记一条记录，cwd 指向 /Users/bairimengyushi/苏苏OB知识库。
切换 CC Switch → 官方路由后，云同步往 threads 表灌入数百条 openai 会话，正常会话在界面消失——正文文件没丢，目录被污染。
恢复动作：从 Time Machine 取出问题前的 state_5.sqlite、session_index.jsonl、.codex-global-state.json、archived_sessions/ 一并还原，会话列表即恢复正常。

2026.08.09｜创建概念卡：用户要求将”Codex 会话”登记为概念；依据本次会话丢失与恢复实战（恢复 state_5.sqlite/session_index.jsonl/全局状态/归档后会话列表恢复），登记为 037。
2026.08.10｜更新：补充”provider 标记过滤”机制——Codex 桌面版侧边栏按 threads.model_provider 过滤会话列表，切换路由后历史会话”消失”的根因是 provider 标记与当前路由不一致（数据未丢失），解法为 UPDATE threads SET model_provider='openai' WHERE model_provider IN ('cc-switch-official','custom')；配套前提为 config 的 model_provider 一致、auth.json 为 chatgpt 账号模式、官方 API 可达（401 属正常）。
2026.08.10｜更新：补入完整事件复盘作为实践证据（生图失败→切官方订阅→会话消失→AI 自救无效→WorkBuddy 恢复），并将”会话正文从未丢失、丢失的只是目录页与 provider 标记”写入边界说明；关联 032｜Codex。
2026.08.10｜更新：补充”最深层根因”——Codex 打开会话读的是 rollout 正文文件第一行 session_meta.model_provider，不是数据库；只改数据库会被 Codex 启动时按正文文件写回旧值。完整解法：批量改正文文件（sessions+archived_sessions 约 690 个）第一行 provider 为 openai + 同步数据库 + config 保留旧 provider 定义指向官方（双保险），详见复盘”六点五”。