5分钟上手 Codex Provider Sync：安装到首次完成 Codex Provider 同步的保姆级教程
【免费下载链接】codex-provider-syncSynchronize Codex session provider metadata across rollout files and SQLite state.项目地址: https://gitcode.com/gh_mirrors/co/codex-provider-sync
Codex Provider Sync是一款本地元数据一致性工具，用于在切换 Provider 后，把 Codex 的会话文件（rollout）与 SQLite 聊天索引中的 Provider 信息对齐到当前配置，让旧会话有机会重新可用。只需 3 条命令，你就能完成从安装到首次 Codex Provider 同步的全部流程。
它只对齐 Provider 元数据，不修改聊天正文，也不读取或改动登录凭据
auth.json。
一、它解决什么问题？
用 CCSwitch 等工具切换 Provider 后，config.toml已经指向了新 Provider，但旧会话文件和 SQLite 索引里仍记录着原来的 Provider。这份"元数据不一致"常常是旧会话无法正常继续的原因之一。
同步前的不一致状态会变成同步后的一致状态，而聊天内容本身逐字节不变。更多细节见 docs/WORKING_PRINCIPLE_ZH.md。
二、先选入口：桌面版、Local Web 还是 CLI？
一个核心，三个入口：Windows 桌面版、Local Web 和 CLI 共用同一套同步、切换、备份与恢复逻辑，选择入口只影响操作方式，不影响同步结果。
| 入口 | 适合谁 | 前置条件 |
|---|---|---|
| 🖥️ Windows 桌面版 | 日常双击使用的新手 | 无需 Node.js，下载即用 |
| 🌐 Local Web | 跨平台、想在浏览器里操作 | Node.js16.20.2+ |
| 💻 CLI | 脚本、自动化、WSL 用户 | Node.js16.20.2+ |
💡 新手推荐：Windows 用户直接选桌面版；其他平台选 CLI，教程中的命令同样适用于 Local Web。
三、第一步：安装 Codex Provider Sync
方式 1：Windows 桌面版
到项目的官方 Release 页面下载Windows x64安装版或便携 ZIP（未签名；便携版须完整解压，不要只复制一个 EXE）。下载入口说明见 README.md 的"下载 Windows 桌面版"一节，完整操作说明见 docs/README_DESKTOP_ZH.md。
方式 2：CLI / Local Web（npm 安装）
安装 Node.js16.20.2+后，一条命令装好（npm 包名为@dailin521/codex-provider-sync，CLI 入口即 src/cli.js）：
npm install -g @dailin521/codex-provider-sync方式 3：从源码使用
如果你想在本地跑 Web UI 或参与开发，可先克隆仓库：
git clone https://gitcode.com/gh_mirrors/co/codex-provider-sync开发环境使用 Node 24，完整构建与测试命令见 CONTRIBUTING.md。
四、第二步：检查当前状态
同步前，先确认当前 Provider、Codex Home、SQLite Home 和实际数据库文件是否正确。
CLI 用户执行只读检查（不会写入任何数据）：
codex-provider status桌面版用户打开"概览"页面即可看到相同信息：当前 Provider、rollout 文件数、SQLite threads 数、按 Provider 分布的会话柱状图，以及待执行的同步入口。
核对要点（详见 docs/README_CLI_ZH.md）：
- ✅ 当前 Provider 是你要使用的目标；
- ✅ 会话文件数量与索引行数不一定相等，Provider 分布才是同步判断的主要依据；
- ⚠️ 若状态尚未完整读取，不要把命令退出 0 当作"已同步"。
五、第三步：完成首次 Codex Provider 同步
确认状态无误后，正式执行同步。
CLI 用户：
codex-provider sync同步目标始终来自config.toml根级model_provider（缺失时使用内置openai）。sync不修改配置，也不调整历史模型、目录或消息标记。
桌面版用户（两种方式，内部走同一套计划、锁、复核和备份检查）：
- 预览同步：先查看影响范围和备份提示，确认后执行，适合第一次使用；
- 直接同步：点击即执行，没有第二次确认。
同步完成后你会看到最终结果：更新数量、跳过数量、备份位置。若出现"部分完成"，通常是某些会话正被占用或首行格式异常——结束相关占用会话后重试即可，已完成的部分不会自动全量回滚。
🛡️ 安全机制：存在实际写入时会先创建受管备份（默认保留最近 2 份），无需修改时不产生备份。备份位于
<Codex Home>/backups_state/provider-sync/。
六、同步出问题？三步自救
- 查看原因：桌面版在"操作日志"查看失败阶段与错误码；CLI 可用
codex-provider sync --json检查outcome字段（退出码 3 表示部分完成，需查看失败阶段）。 - 等待占用结束：正在被 Codex 写入的会话会被跳过，等它停止写入后重新同步。
- 手动恢复：若同步错了，在"备份 / 恢复"中选择对应操作前的备份恢复；CLI 使用：
codex-provider restore "<BACKUP_ID>"具体步骤见 docs/README_DESKTOP_ZH.md 与 docs/README_CLI_ZH.md。
七、常见问题速答
Q：已经用 CCSwitch 切换了 Provider，还需要做什么？只需打开本工具确认当前 Provider 正确，再点击同步。若会话文件和索引中的 Provider 已一致，就无需重复同步。
Q：同步会修改聊天内容或登录信息吗？不会。只对齐 Provider 元数据，不碰聊天正文、历史模型、排序时间，也不读取auth.json。
Q：同步后旧会话仍无法继续怎么办？Provider 一致只是继续会话的一个条件。请查看 Codex 的具体报错；若涉及加密内容或模型兼容问题，可回到原 Provider / 账号，或新建会话。
Q：想省得手动执行，可以自动同步吗？可以。CLI 运行codex-provider watch持续监听配置与 SQLite 状态事件；桌面版在"设置"中开启 Watch 即可。
总结：5 分钟回顾
| 步骤 | 操作 | 耗时 |
|---|---|---|
| 1️⃣ 安装 | npm install -g @dailin521/codex-provider-sync（或下载桌面版） | ~1 分钟 |
| 2️⃣ 检查 | codex-provider status核对 Provider 与分布 | ~1 分钟 |
| 3️⃣ 同步 | codex-provider sync完成首次 Codex Provider 同步 | ~3 分钟 |
至此，你已经完成了从安装到首次同步的全部流程。接下来可以继续探索：按项目浏览聊天记录的 Local Web（docs/README_WEB_UI_ZH.md）、桌面版完整功能（docs/README_DESKTOP_ZH.md）、版本变更（CHANGELOG.md），以及同步的工作原理（docs/WORKING_PRINCIPLE_ZH.md）。
【免费下载链接】codex-provider-syncSynchronize Codex session provider metadata across rollout files and SQLite state.项目地址: https://gitcode.com/gh_mirrors/co/codex-provider-sync
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
