Codex历史任务同步失败的根本原因在于本地状态与远程元数据错位，需区分Provider元数据不一致、本地文件dirty未提交或会话目录损坏三类问题，并依错误信息执行对应修复操作。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Codex历史任务同步失败时，会话文件明明存在却无法恢复、resume提示ID不存在、云端同步卡在conflict detected，问题根源往往不在网络或API，而在本地状态与远程元数据的错位。必须先区分是Provider元数据不一致，还是本地文件被标记为dirty但未提交，或是会话目录本身损坏。
确认失败类型：先看错误信息再动手
打开终端，执行codex --resume your-session-id，观察返回内容：
如果报Error: Session not found或No session history found in ~/.codex/sessions/，说明会话目录为空或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 或 OpenClaw OAuth 凭证直接调用 ChatGPT/Codex Responses 的 image_generation 工具来生成或编辑光栅图像，然后保存
重启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%\.codex\sessions
若目录为空，从最近一次Git commit或系统备份中恢复sessions/子目录；
若目录存在但文件名全是乱码或大小为0，说明JSONL写入中断，需从~/.codex/backups/中提取最近的sessions-*.tar.gz解压覆盖。
