Codex Provider Sync CLI 实战教程：3 条命令搞定 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 会话文件与 SQLite 索引里的 Provider 元数据对齐到当前配置，让切换 Provider 后的旧会话恢复可用。本文带你用status、sync、switch3 条命令完成检查、同步与切换，并讲清自动备份与恢复的兜底机制。
它解决什么问题？
切换 Provider 后，旧会话文件与 SQLite 聊天索引里记录的仍是原来的 Provider，元数据不一致会导致历史会话不可用。Codex Provider Sync 的作用就是把这份 Provider 信息对齐到当前配置——只改 Provider 元数据，不碰聊天正文：
同步如何读写，速度取决于什么
- 原地写：当 Provider 名称字节等长等条件满足时，直接改写 Provider，不生成整份会话副本；
- 流式替换：其他情况更新首行后流式复制正文到新文件再替换原文件。
两种方式自动选择，无需调任何加速选项。速度主要取决于需更新的会话数量，详细原理见 docs/WORKING_PRINCIPLE_ZH.md。
准备工作：一键安装 CLI
CLI 通过 npm 发布，要求 Node.js16.20.2+：
npm install -g @dailin521/codex-provider-sync codex-provider help命令是否可用以安装版本的--help为准。完整 CLI 入口逻辑在 src/cli.js，同步业务核心在 packages/core/src/application/provider-sync.js。
第 1 条命令：codex-provider status 只读检查
codex-provider statusstatus是纯只读检查，重点核对：
- 当前 Provider：来自
config.toml根级model_provider； - Codex Home / SQLite Home：确认工具看到的是你想操作的那份数据；
- Provider 分布：会话文件数与索引行数不一定相等，Provider 分布才是同步判断的主要依据。
状态未完整读取时，不能把命令退出 0 当作"已同步"。
第 2 条命令：codex-provider sync 同步到当前配置
如果你已用 CCSwitch 等工具切好 Provider，只需要：
codex-provider sync关键行为：
- 目标始终来自
config.toml，不修改配置，不调整历史模型、目录或消息标记； - 无实际写入时不产生备份（noop）；
- 有实际写入时先创建受管备份，默认保留最近 2 份；
- 问题会话会被跳过并保留关联索引，正常会话继续处理，显示"部分完成"。
写前会自动备份，备份位于<Codex Home>/backups_state/provider-sync/，同一 Home 的操作共用备份池。
第 3 条命令：codex-provider switch 切换 Provider
希望由本工具直接切换 Provider 时：
codex-provider switch openai codex-provider switch my-provider --keep-root-model codex-provider switch my-provider --model model-name| 模型策略 | 对根级model的影响 |
|---|---|
| 不传模型选项 | 目标 Provider 配置了model时采用该值，否则保留当前根模型 |
--keep-root-model | 保留当前根模型 |
--model NAME | 设置为指定名称 |
三种方式都先修改配置，再执行同一个 ProviderSync，不会修改历史会话记录的模型。自定义 Provider 需要预先配置，不会由此命令创建。
安全兜底：恢复备份与清理
codex-provider restore "<备份目录>" codex-provider sync --keep 2 codex-provider prune-backups --keep 2restore默认恢复备份实际包含的配置、索引和会话元数据，--no-config、--no-db、--no-sessions可排除对应内容；- 恢复依赖的受保护备份不会被强制裁剪；
prune-backups的0表示删除全部可清理备份，不是"关闭清理"； - Restore 会先保存目标当前状态，再用独立 journal 和补偿机制恢复，不要用删除锁文件绕过未完成状态。
一个核心，三个入口
Windows 桌面版、Local Web 和 CLI 使用同一套同步、切换、备份与恢复逻辑——选择入口只影响操作方式，不影响同步结果（设计决策见 docs/adr/0002-node-core-as-single-authority.md）。想先"预览影响再确认"，推荐桌面或 Web 界面：
Web 模式通过codex-provider web启动，默认只监听127.0.0.1:8791，打开浏览器完成配对即可。
进阶技巧：JSON 输出与退出码
自动化脚本务必加--json，stdout 只输出一个终态对象{schemaVersion, command, ok, outcome, result, warnings, error}：
codex-provider sync --json| 退出码 | 含义 |
|---|---|
| 0 | 成功或无需修改 |
| 1 | 普通失败（可能已回滚，结合outcome判断） |
| 2 | 输入无效、计划过期或状态变化 |
| 3 | 部分完成，查看失败阶段与重试建议 |
| 4 / 5 | 需要恢复处理 / 正忙或无法验证锁 |
| 130 | 已取消 |
另外codex-provider watch可长期监听配置与 SQLite 状态事件，自动调用同一 Sync（默认防抖 750 ms，Ctrl+C 停止）。
常见问题速查
- Provider 未定义：先修复配置，Sync 不会擅自切回 OpenAI；
- 数据已变化 / 计划过期：重新检查并运行命令，不要重放旧 planId；
- 会话占用：结束相关写入后再同步，重试只处理未对齐的目标；
- 部分完成：查看操作日志中跳过原因（最多 200 项），处理数据后重新预览即可纳入；
- WSL 场景：Windows 对 WSL 的 SQLite Home 只做诊断，写入请进入 WSL 后运行 CLI，不要从 Windows 直接操作 WSL SQLite。
完整故障处理见 docs/README_CLI_ZH.md。
参考资料
- CLI 指南：docs/README_CLI_ZH.md
- 精确 CLI 合同：docs/architecture/contracts/CLI_CONTRACT_ZH.md
- Node Core 架构与 Provider I/O 不变量：docs/architecture/NODE_CORE_ARCHITECTURE_ZH.md
- 工作原理与路径解析：docs/WORKING_PRINCIPLE_ZH.md
- 错误码说明：docs/architecture/contracts/ERROR_CODES_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），仅供参考
