Codex Provider Sync 是什么？切换 Provider 后 Codex 旧会话失灵的完整解决指南
【免费下载链接】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 是一款面向 Codex 用户的本地元数据同步工具：当你切换 Provider（模型服务商）后，它能把会话文件和 SQLite 聊天索引中残留的旧 Provider 信息对齐到当前配置，让因信息不一致而"失灵"的旧会话重新可用。整个过程只同步 Provider 元数据，不触碰聊天正文、登录凭证或加密内容。
一、为什么切换 Provider 后旧会话会失灵？🔍
Codex 的每个会话都留有两份"身份档案"：
- 会话文件（rollout）：记录该会话由哪个 Provider 创建；
- SQLite 聊天索引：线程表中的
model_provider字段同样记录着 Provider 信息。
当你用 CCSwitch 等工具把config.toml切到 Provider B 后，这两份档案里仍写着 Provider A。此时旧会话可能无法正常继续、压缩或显示，即使历史列表看起来一切正常。
这类问题的本质是元数据不一致，而不是会话损坏——这正是 Codex Provider Sync 要解决的。它的完整工作原理见 docs/WORKING_PRINCIPLE_ZH.md。
二、Codex Provider Sync 如何修复不一致？
工具的思路非常直接：保持你的当前配置不变，把会话文件与 SQLite 索引中的 Provider 统一对齐到当前配置。下图展示了从"同步前不一致"到"同步后会话可继续"的完整流程：
四个核心能力：
| 能力 | 说明 |
|---|---|
| 🔄 同步与切换 | 预览或直接同步；也可在工具内直接切换 Provider 并同步 |
| 💾 备份与恢复 | 修改前自动备份（默认保留 2 份），支持一键恢复 |
| 💬 聊天与日志 | 按项目浏览会话，查看每次操作的耗时与结果 |
| 🔧 存储与修复 | 自定义数据位置，按需诊断和专项修复 |
⚠️ 注意：它解决的是元数据不一致，不保证跨 Provider / 账号的旧会话一定能继续或压缩；也不处理登录、认证或加密内容。信息已经一致时，无需重复同步。
三、Codex Provider Sync 快速上手：三种入口任选
工具采用"一个核心，三个入口"的设计——Windows 桌面版、本地 Web、CLI 共用同一套同步、切换、备份与恢复逻辑，选哪个入口只影响操作方式，不影响同步结果。
1️⃣ Windows 桌面版（推荐新手）
无需安装 Node.js，下载后解压运行即可（未签名，便携版须完整解压）。日常三步走：
- 打开"概览"，确认当前 Provider、存储路径和同步状态；
- 已用其他工具切换过 Provider？点击**"预览同步"**查看影响，或直接点"直接同步"；
- 查看结果——部分完成时结束占用会话后重试；需要撤销就到"备份 / 恢复"选择备份恢复。
下图是桌面版概览页的实际界面：左侧显示状态与 Provider 分布，右侧是执行同步的操作区：
完整操作步骤见 docs/README_DESKTOP_ZH.md。
2️⃣ 本地 Web UI
适合 macOS / Linux 或多环境场景。安装 Node.js 16.20.2 及以上版本后：
npm install -g @dailin521/codex-provider-sync codex-provider web默认只监听本机127.0.0.1:8791，浏览器打开完成配对即可，跨设备与 SSH 用法见 docs/README_WEB_UI_ZH.md。
3️⃣ CLI（脚本与 WSL 用户）
两条命令，先检查再同步：
codex-provider status # 只读检查当前状态 codex-provider sync # 对齐 Provider 元数据同步错了？用codex-provider restore <backup-dir>从备份恢复。完整命令、路径参数与 JSON 退出码见 docs/README_CLI_ZH.md。
四、同步到底改了什么？为什么很快？
Codex Provider Sync 的同步只解析每个会话的首行元数据，并只改两处：会话文件首行的 Provider 和 SQLite 中的model_provider字段。聊天正文保持逐字节不变。
写入方式会自动二选一，无需任何设置：
- 原地字节更新：当新旧 Provider ID 的 JSON 字面量字节等长（如
openai → prov_a）且满足安全条件时，直接定点改写 Provider 字节，不重建整份文件； - 有界流式替换：长度不同时，写入新首行后流式复制正文再原子替换原文件，正文仍逐字节不变。
这就是为什么同步速度主要取决于需要更新的会话数量，而不是文件大小。相关实现可参考 src/session-files.js 与核心同步逻辑 packages/core/src/application/provider-sync.js。
另外两个让人放心的设计：
- 写前自动备份：没有实际改动时不创建备份；
- 异常安全：问题会话（非法 UTF-8、超大首行等）会被跳过并保留关联索引，正常会话继续处理，结果标记"部分完成"并在日志中给出原因。
五、常见问题（FAQ）📌
Q：已经用 CCSwitch 切换了，还需要做什么？打开工具确认当前 Provider 正确，然后点"同步"即可。如果会话文件和索引中的 Provider 已一致，无需重复同步。
Q：同步会修改聊天内容或登录信息吗？不会。只对齐 Provider 元数据，不修改聊天正文、历史模型或会话排序时间，也不读取或修改auth.json。
Q：同步后旧会话仍无法继续？Provider 一致只是继续会话的必要条件之一。请查看 Codex 的具体报错；若涉及加密内容或模型兼容问题，可回到原 Provider / 账号，或新建会话。
Q：显示"部分完成"怎么办？先查操作日志中的跳过原因：格式或大小问题需处理数据后重新预览；文件被占用则等会话停止写入后再同步。已完成的修改不会自动全量回滚，需要撤销时用备份恢复。
六、延伸阅读与源码路径
- 项目总览与更新日志：README.md、CHANGELOG.md
- 工作原理与落盘机制详解：docs/WORKING_PRINCIPLE_ZH.md
- 三个入口的使用指南：桌面版 · Web UI · CLI
- 核心同步实现：packages/core/src/application/provider-sync.js · src/sqlite-state.js
- 架构与决策记录：docs/architecture/NODE_CORE_ARCHITECTURE_ZH.md、docs/adr/
切换 Provider 不再是旧会话的"终点"。用 Codex Provider Sync 花一分钟对齐元数据，就能让绝大多数旧会话在新 Provider 下重新可用——先预览、后同步、随时可恢复，整个流程足够简单也足够安全。
【免费下载链接】codex-provider-syncSynchronize Codex session provider metadata across rollout files and SQLite state.项目地址: https://gitcode.com/gh_mirrors/co/codex-provider-sync
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
