Codex 历史任务同步失败的根本原因，通常在于本地状态与远程元数据发生错位。排查时需要重点区分三种常见情况：Provider 元数据不一致、本地文件处于 dirty 状态但未提交，以及会话目录损坏或丢失，并根据对应报错信息采取正确的修复方法。

遇到 Codex 历史任务同步失败时，常见表现其实很集中：明明本地会话文件还在，却无法恢复；执行 resume 时直接提示 ID 不存在；云端同步长期卡在 conflict detected。很多用户第一时间会怀疑是网络异常或 API 故障，但大多数情况下，真正的问题并不在连接层，而是本地状态与远程元数据没有正确匹配。想要快速定位原因，首先要判断具体属于哪一类：是 Provider 元数据前后不一致，还是本地文件已被标记为 dirty 却迟迟没有提交，又或者是会话目录本身已经损坏。

确认失败类型：先看错误信息再处理

打开终端，执行codex --resume your-session-id，重点观察返回的错误提示：

如果出现Error: Session not found或No session history found in ~/.codex/sessions/，通常表示会话目录为空，或者 session ID 输入错误；

如果出现Error: Failed to parse session data，说明会话文件解析失败，文件内容大概率已经损坏，需要通过备份恢复；

如果出现Sync failed: conflict detected，这一般不是网络问题，而是本地文件状态与 Codex 内部快照不一致——此时应立即停止重复操作，不要盲目强制重试。

Provider元数据不同步导致历史记录“消失”

切换 model_provider 之后看不到历史任务或历史会话，根本原因通常不是“数据丢失”，而是 SQLite 状态库与 session JSONL 中的 provider 字段无法对应。进一步来说，最新的 OpenAI 规范要求 reasoning ID 必须以 rs_ 开头；而第三方写入的 item_ID 往往仍然使用通用格式。只要字段格式不符合预期，Codex 往往不会仅跳过异常记录，而是会直接拒绝加载整个会话历史。

方法一：使用codex-provider-sync一键修复

安装工具：npm install -g codex-provider-sync

执行同步：codex-provider-sync --from openai --to custom（将 openai profile 的历史元数据映射到 custom provider）

【务必先--dry-run】先加上--dry-run参数预览变更内容，确认无误后再执行正式同步。

方法二：手动统一 provider ID（适合高级用户）

编辑~/.codex/config.toml，将第三方 provider 节点名改为非保留 ID，例如把[model_providers.openai]改为[model_providers.xcode-openai]；

保持name = "openai"不变，只修改方括号内的 ID；

重启 Codex Desktop 或 CLI 后，历史会话通常就会重新显示。

本地文件冲突阻断同步

当 Codex 检测到 Git 暂存区之外仍有修改、符号链接元数据发生漂移，或硬链接 inode 不一致时，会主动拒绝同步，以避免覆盖你尚未提交的有效更改。

第一步：进入项目根目录，运行git status

第二步：对所有modified但尚未git add的文件，执行git add .或git stash（如果暂时不想提交）

第三步：检查软链接文件是否被直接编辑过——例如config.local.json是通过ln -s ../shared/config.json创建的，就不要直接修改它，而应修改源文件

第四步：清除 Codex 缓存：codex cache clear

第五步：重新尝试同步：codex sync --force

会话目录损坏或丢失

检查~/.codex/sessions/目录是否存在且不为空：

Linux/macOS 执行：ls -la ~/.codex/sessions/ | head -n 5

Windows 执行：dir %USERPROFILE%.codexsessions

如果目录为空，可从最近一次 Git commit 或系统备份中恢复sessions/子目录；

如果目录存在，但文件名全部乱码或文件大小为 0，通常说明 JSONL 写入过程中发生中断，此时需要从~/.codex/backups/中提取最近的sessions-*.tar.gz并解压覆盖。