企业官网建设流程全解析

旧版 headroom wrap codex 用完后 Codex 会话历史丢失怎么恢复

【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom

如果你用过旧版 Headroom 的headroom wrap codex来包裹 Codex 运行，退出 wrapper 后可能会发现：期间产生的聊天和配置没有出现在正常的 Codex 历史里。原因是旧版本会让 Codex 使用一个临时CODEX_HOME（目录名为headroom-codex-home-*），会话和配置都留在了这个临时目录中，wrapper 退出后就从常规历史里“消失”了。Headroom 提供的headroom recover codex命令可以把这些保留下来的状态合并回持久化的 Codex home，且不会删除任何一端的数据。

这个恢复流程能找回两类来源：仍然存在的临时 home，以及之前恢复中断后保留下来的source-pinned/副本。临时 home 如果已经被删除，又没有保留副本，就无法重建。Headroom 会报告线程数据库里仍在引用但已被删除的临时 home，但不会把粘贴在提示词或报错信息里的路径当成恢复来源。该回归的详细说明见仓库 issue #2159。

恢复前：确认哪些状态还能找回

在动手前先确认两件事：

1. 关闭 Codex 以及所有正在使用临时或持久 Codex home 的进程。恢复过程会在每次创建备份时检测期间发生的改动并中止，但只有 home 处于静止状态才能保证迁移一致。
2. 确认恢复目标。目标目录默认取$CODEX_HOME（如果已设置），否则为~/.codex。在确认迁移前，先检查这确实是你平时使用的持久 home。

另外要明确恢复的边界：

• 能恢复：仍存在的headroom-codex-home-*临时目录，以及中断/失败的恢复尝试留下的source-pinned/副本。
• 不能恢复：临时 home 已删除且没有任何保留副本的情况。只有提示词文本的 history-only 记录无法重建完整对话记录。

修复此问题的版本见 CHANGELOG.md 中 0.32.0 的codex: preserve wrapped sessions and recover state条目（issue #2160），仓库当前版本为 0.37.0。因此需要安装 0.32.0 或更新的版本。

准备：安装修复版 Headroom

恢复命令来自headroomCLI，按 安装文档 用 pip 或 uv 安装（要求 Python 3.10+，发布名为headroom-ai）：

pip install "headroom-ai[all]"

或者在 macOS Apple Silicon / Linux 上用 uv 安装到独立环境：

uv tool install --python 3.13 "headroom-ai[all]"

安装后用headroom --version确认命令可用，或按文档验证版本：

python -c "import headroom; print(headroom.__version__)"

方式一：自动恢复（运行 wrap 时提示）

修复版headroom wrap codex的第一次交互式运行会自动搜索 Python 的临时目录、$TMPDIR、/tmp、/private/tmp以及 macOS 的/private/var/folders/*/*/T根目录下所有非空的headroom-codex-home-*目录。如果找到，它会列出这些目录，并在 Codex 启动前询问你是否先备份并恢复它们。

拒绝这个提示不会改变任何内容，之后仍可以手动执行下文的命令。

方式二：手动执行 headroom recover codex

直接运行命令，让 Headroom 自动发现保留的临时 home 和source-pinned/副本，并预览迁移内容：

headroom recover codex

命令会先打印目标 Codex home 和所有将要合并的 source，并提示“两端都会先备份”，然后请求确认。确认后才开始合并；取消则不改动任何 Codex 状态。

如果已知具体要恢复哪个临时 home，且想显式指定持久目标（/path/to/headroom-codex-home-12345替换为实际临时目录路径，可从自动发现输出或上表扫描的目录中取得）：

headroom recover codex \ --source /path/to/headroom-codex-home-12345 \ --target "${CODEX_HOME:-$HOME/.codex}"

• 重复--source可以一次合并多个临时 home。
• --yes跳过确认提示，文档明确建议只在自动化场景、且这些路径已经人工审查过时才使用。

如果没有任何可恢复的副本，命令不会报错退出，而是转而审计持久 Codex home：检查线程数据库、rollout 文件和history.jsonl，报告已索引的 active/archived 会话数、存在但未进线程索引的 rollout 文件，以及 rollout 已不存在的 history-only 记录，并输出类似 “Their full transcripts cannot be restored without a retained rollout.” 的提示。此时文档建议你自己运行codex resume --all查看所有工作目录下已索引的会话——因为 Codex 默认的 resume 选择器会按当前工作目录过滤，而 Headroom 在恢复期间不会替你启动 Codex。

合并规则：恢复过程会迁移什么

当 source 使用了旧 wrapper 注入的 localhostheadroommodel provider 时，恢复会把 SQLite 线程行和 rolloutsession_meta记录中的该 provider 改写为当前目标 provider，这也能修复早期损坏恢复留下的目标记录。用户自定义的、名为headroom的远程 provider 会被保留。其余合并规则：

• history.jsonl等 JSONL 索引去重合并；格式错误的输入会从结果中剔除并复制到备份的 quarantine 目录。
• sessions/和archived_sessions/下的会话 rollout，同一路径两端都存在时保留较新的文件。
• SQLite 数据库仅在表、索引、触发器、视图和迁移校验和兼容时才合并；主键冲突时保留较新数据库的行；恢复的线程行会被改写到持久 rollout 路径（包括临时 home 删除后从 pinned source 恢复的行）。
• config.toml的表递归合并，较新配置的值优先，旧 wrapper 注入的 localhost Headroom 路由会被移除。
• 其他文件（包括凭据和用户设置）保留较新副本；修改时间相同时持久目标端优先；source 中不存在的文件永远不会删除目标端文件。
• socket、锁文件、SQLite journal、FIFO 等运行时产物只记录、不复制。

备份与回滚机制

每次合并前，source 会被 pin 住，现有持久 home（包括当前 Codex 配置）也会先备份。备份为 owner-only 权限，保存在目标旁边：

<target-parent>/.headroom-codex-recovery/<timestamp-pid>/ ├── source-pinned/ ├── target-before/ ├── target-failed/ # only when a merge is rolled back ├── manifest.json └── quarantine/ # only when malformed input is found

• 恢复前目标目录原本不存在时，target-before/不存在。
• manifest.json记录所有 copied、merged、quarantined、skipped 的路径。

如果配置解析、SQLite schema 校验、完整性检查、外键检查或文件写入失败，Headroom 会先把失败的目标原子重命名为target-failed/，再恢复target-before/，失败现场得以保留供检查。此外，恢复会拒绝 source 与 target 路径重叠、target 符号链接穿越，以及 pin 住 source 期间 source 发生变化这三种情况。

验证恢复结果

每个 source 合并成功后，命令会打印保留的备份路径（Recovery complete. Backup retained at <路径>）。接下来的验证步骤：

1. 检查该备份目录下的manifest.json，确认合并、隔离和跳过的路径符合预期。
2. 正常启动 Codex，确认恢复出来的会话和设置都出现了。
3. 如需查看全部工作目录下的会话，运行codex resume --all。

在验证持久历史无误之前，保留这份备份，不要提前清理。

限制与后续

• 临时 home 已删除且无保留副本的状态无法恢复；Headroom 只会报告被引用但已删除的临时 home。
• history-only 记录（只有提示词文本、没有 rollout）无法重建完整对话记录。
• 修复版headroom wrap codex会让 Codex 直接运行在持久 home 上，代理路由只作用于被启动的进程，之后新的 wrapped 会话在 Headroom 退出后依然可见，不会再出现同类丢失。

完整的恢复细节见 Recover Codex State。

【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom