Codex历史会话消失？一键恢复可见！Codex Provider Sync使用教程
大家好 这里是「代码简单说」`,欢迎大家关注同名公众号,不定时更新更多实用有趣的教程 也欢迎大家在评论区一起讨论交流!~
关键词：Codex历史会话恢复、Codex Provider切换、Codex会话丢失、Codex Desktop、Codex Provider Sync、Codex历史记录找回、Codex会话不可见解决方法
最近不少开发者在使用 Codex 时遇到一个非常头疼的问题：切换了 model_provider 之后，之前的聊天记录突然没了。
codex客户端下载:https://codexdown.cc/
明明会话文件还在磁盘中，但是：
- Codex Desktop看不到
/resume找不到- 项目侧边栏显示空白
- 历史对话仿佛消失
很多人第一反应以为是数据丢失了。
实际上，大多数情况下并不是会话丢失，而是 Codex 内部的 Provider 元数据没有同步导致的。
今天分享一个开源工具：
codex-provider-sync
专门用于修复 Codex Provider 切换后历史会话不可见的问题。
什么是 codex-provider-sync
GitHub项目：
codex-provider-sync
作用非常简单：
当切换 model_provider 后，自动同步 Codex 的各种元数据，让历史会话重新显示出来。
它不会修改你的聊天内容。
不会修改历史记录。
不会修改消息数据。
仅修复：
- Provider 元数据
- Rollout 元数据
- SQLite状态数据
- 项目缓存数据
从而让 Codex Desktop 和 CLI 能重新识别这些历史会话。
为什么会出现历史会话消失
Codex内部会维护多种状态文件：
~/.codex/sessions
~/.codex/archived_sessions
~/.codex/state_5.sqlite
.codex-global-state.json
当你切换：
model_provider = "openai"
改成：
model_provider = "apigather"
或者其它 Provider 时：
这些文件中的 Provider 信息可能不一致。
结果就是：
会话文件存在
↓
SQLite记录不匹配
↓
Desktop过滤掉
↓
历史会话不可见
所以看起来像丢失了。
实际上数据还在。
codex-provider-sync解决方案
工具会自动同步：
| 同步内容 | 说明 |
|---|---|
| sessions | 会话文件 |
| archived_sessions | 归档会话 |
| state_5.sqlite | SQLite状态库 |
| 项目缓存 | .codex-global-state.json |
同步后：
Desktop重新识别
CLI重新识别
历史会话恢复显示
软件下载
| 名称 | 下载地址 |
|---|---|
| codex-provider-sync | https://pan.quark.cn/s/6f3f494f57b9 |
Windows图形版使用教程
对于大部分用户来说：
直接使用 EXE 即可。
启动：
CodexProviderSync.exe
操作步骤：
第一步：刷新状态
点击：
Refresh
扫描当前Codex环境。
第二步：选择Provider
例如：
openai
或者：
apigather
选择你当前正在使用的Provider。
第三步：执行同步
点击：
Execute
即可开始修复。
CLI安装方式
如果你喜欢命令行。
安装：
npm install -g git+https://github.com/Dailin521/codex-provider-sync.git
要求：
Node.js 24+
如果是：
Node 20
Node 22
可能出现：
node:sqlite
相关错误。
建议升级到：
Node.js 24+
常用命令详解
查看状态
codex-provider status
用于诊断：
- 当前Provider
- SQLite状态
- Rollout状态
- 项目可见性
同步历史会话
codex-provider sync
功能：
不切换Provider
只同步历史会话元数据
指定Provider同步
codex-provider sync --provider openai
示例：
codex-provider sync --provider apigather
切换Provider并同步
codex-provider switch apigather
执行过程：
修改config.toml
↓
切换Provider
↓
同步所有元数据
一步完成。
恢复备份
codex-provider restore backup_path
例如：
codex-provider restore C:\Users\Admin\.codex\backups_state\provider-sync\20260608
支持：
--no-config
--no-db
--no-sessions
选择性恢复。
清理旧备份
codex-provider prune-backups --keep 5
表示：
保留最近5份备份
删除更早备份
关于最近50条会话限制
这是很多人误判的问题。
即使同步成功：
Desktop仍然看不到历史记录
原因可能不是同步失败。
而是：
Codex Desktop只加载最近50条会话
官方前端存在限制。
例如：
项目A有20条
项目B有30条
项目C有100条
Desktop首屏：
只显示最近50条
那么：
项目C的旧记录
即使恢复成功。
仍然不会出现在列表中。
如何判断是不是50条限制
执行：
codex-provider status
或者GUI：
Refresh
如果看到：
first page 0/50
或者：
ranks 64-77
类似提示。
说明：
会话已经恢复
只是没有进入前50条列表
不是同步失败。
工具不会做什么
为了安全性。
作者明确限制了修改范围。
不会修改：
登录状态
auth.json
不处理。
账号切换
第三方切号工具不处理。
聊天内容
不会修改：
消息内容
会话标题
历史记录
会话排序
不会修改：
updated_at
不会通过作弊方式把会话顶到前面。
加密内容转换
不会重新加密：
encrypted_content
因此：
跨Provider
跨账号
虽然能恢复列表显示。
但继续聊天时仍可能出现：
invalid_encrypted_content
错误。
自动备份机制
每次执行：
sync
或者：
switch
之前。
工具都会自动创建备份。
路径：
~/.codex/backups_state/provider-sync/<timestamp>
例如：
~/.codex/backups_state/provider-sync/20260608123000
这样即使出现异常。
也能随时恢复。
常见问题
state_5.sqlite被占用
出现：
database locked
解决：
关闭：
Codex
Codex Desktop
app-server
然后重新执行。
SQLite损坏
出现：
malformed
或者：
unreadable
说明数据库已经损坏。
工具会停止同步。
避免进一步破坏数据。
EXE无法启动
检查：
是否已经解压
然后查看：
%AppData%\codex-provider-sync\startup-error.log
或者PowerShell运行：
./CodexProviderSync.exe
查看具体错误。
项目特点总结
| 功能 | 支持 |
|---|---|
| 恢复历史会话显示 | √ |
| 同步Provider元数据 | √ |
| 修复SQLite状态 | √ |
| 自动备份 | √ |
| Windows图形界面 | √ |
| CLI命令行 | √ |
| 修改聊天内容 | × |
| 处理登录认证 | × |
| 修改会话排序 | × |
| 重新加密历史内容 | × |
总结
如果你经常在多个 Codex Provider 之间切换，那么大概率会遇到：
历史会话突然消失
的问题。
事实上绝大部分情况下：
数据没丢
只是元数据不一致
而 codex-provider-sync 正是专门解决这个问题的工具。
它能够同步：
- sessions
- archived_sessions
- state_5.sqlite
- 项目缓存
让 Codex Desktop 和 CLI 重新识别历史会话。
对于频繁使用：
- OpenAI
- API聚合平台
- 本地Provider
等多Provider环境的开发者来说，是一个非常实用的辅助工具。
下载地址
| 软件 | 链接 |
|---|---|
| codex-provider-sync | https://pan.quark.cn/s/6f3f494f57b9 |
如果你经常遇到 Codex 历史记录消失的问题，建议收藏备用。
