切换 Codex 的 Provider 是个常见操作——从个人订阅切到公司账号，或者从官方 OpenAI 切到自定义中转。但切完之后打开对话列表，发现历史会话全没了。
第一反应通常是：数据是不是丢了？
大概率没丢。会话文件还在 ~/.codex/ 目录下，只是 rollout、SQLite 和项目可见性这些元数据还指向旧 Provider，新 Provider 下读不到，所以列表是空的。
手动修很麻烦——rollout 文件、SQLite 数据库、项目路径信息散落在不同位置，改错一个就可能把会话彻底搞坏。codex-provider-sync 就是专门解决这个的。它只做一件事：把旧 Provider 的会话元数据同步到当前 Provider，让历史记录重新可见。不碰认证信息，不改消息内容。
目前 GitHub 上 3.1k star，MIT 协议，提供 Windows GUI 和跨平台 CLI 两种使用方式。项目地址：github.com/Dailin521/codex-provider-sync
为什么会这样
Codex 的本地会话存储路径与 Provider 标识绑定。切换 model_provider 后，以下位置的元数据还指向旧 Provider：
- Sessions 目录：
~/.codex/sessions和~/.codex/archived_sessions中的 rollout 文件 - 状态数据库：
state_5.sqlite（存储插件 UI 状态及会话索引） - 项目可见性：相关的路径信息
这不是数据丢失，是读取路径失效。工具做的事就是把这些元数据重新映射到当前 Provider。
操作前的准备
前提条件：确保已在 IDE 中完成 Provider 切换，并关闭 Codex 进程（包括 Codex Desktop 和 app-server）。SQLite 被占用时同步会失败。
不管用什么工具操作本地数据，先备份是基本操作。工具本身每次同步前会自动备份到 ~/.codex/backups_state/provider-sync/<timestamp>，但手动再来一份更稳妥：
cp -r ~/.codex ~/.codex_bak方式一：Windows GUI（推荐非命令行用户）
如果你的环境是 Windows，不需要命令行，直接去 Release 页面下载单文件 GUI：
github.com/Dailin521/codex-provider-sync/releases/latest
下载 CodexProviderSync.exe，打开后四步搞定：
- 点击「刷新」
- 选择目标 Provider
- 点击「立即同步」
- 等待同步完成，重启 Codex
GUI 会自动保留备份并显示同步结果。每天首次启动会检查一次更新，网络查询最多等待 10 秒。
EXE 未做代码签名，从浏览器下载后 Windows SmartScreen 可能会拦截。确认是从 GitHub Release 页面下载的即可放心使用。
方式二：CLI 命令行
CLI 支持 Node.js 16+，三个命令完成修复。
第 1 步：安装
npm install -g git+https://github.com/Dailin521/codex-provider-sync.git第 2 步：检查当前状态
codex-provider status这个命令会显示当前 Provider、rollout、SQLite 和项目可见性的诊断信息。确认信息无误后再执行同步。
第 3 步：执行同步
codex-provider sync重启 Codex，对话列表应该就回来了。
如果你需要切换 Provider 和同步一步到位，也可以用：
codex-provider switch <provider-id>这个命令会在修改 model_provider 后直接执行同步。
工具还会处理什么
除了基本的会话同步，codex-provider-sync 还做了这些事：
- 同步
~/.codex/sessions和~/.codex/archived_sessions中的 rollout metadata - 同步 Codex SQLite 线程记录，支持 SQLite 与 Codex Home 分开存放的场景
- 修复项目可见性相关的路径信息，必要时同步 model metadata
- 大型 rollout 文件在满足条件时原地更新，否则自动使用完整安全重写
codex-provider watch可以监听配置、SQLite 及 WAL 变化并自动同步，适合频繁切换的场景
安全边界
这个工具的设计比较克制，几个值得注意的点：
不碰的东西：消息历史、会话标题、认证信息、auth.json 和 updated_at 时间戳。它不会修改时间戳来欺骗排序，也不会在多台设备之间复制配置或会话文件，只修复当前 Codex Home 的 metadata。
自动备份：每次 sync / switch 前都会备份到 ~/.codex/backups_state/provider-sync/<timestamp>。出了问题可以用 codex-provider restore <backup-dir> 恢复。
活跃会话锁：活跃会话锁住 rollout 文件时，工具会跳过该文件并继续处理其他会话。结束活跃会话后可以再次同步。
一个边界情况：含 encrypted_content 的会话跨 Provider/account 后，可能只能恢复列表可见性，继续对话或 compact 仍可能报 invalid_encrypted_content。这是加密机制的限制，不是工具的 bug。
首屏显示限制：Codex Desktop 首屏只显示最近 50 条会话。如果 /resume 能看到但项目侧不显示，查一下 status 里的 first page / ranks 诊断。
什么情况下不需要它
如果所有中转都能稳定复用同一个 model_provider，并且历史会话始终可见，那么统一 Provider ID 是更简单的方案，不需要额外同步。
这个工具主要用于无法统一 Provider ID，或需要在官方订阅和自定义 Provider 之间切换的场景。
写在最后
切换 Provider 导致会话消失这件事，本质上是元数据的路径映射问题，不是数据丢失。codex-provider-sync 把这个手动修起来很痛苦的活自动化了，备份和恢复机制也做得比较扎实。
如果你遇到过这个问题，可以试试：github.com/Dailin521/codex-provider-sync
本文基于 codex-provider-sync 项目 README 整理，工具持续更新中，具体命令和参数请以官方仓库最新文档为准。