codex-provider-manager

用于管理 Codex Desktop 本地历史中的 model_provider 元数据，解决切换 provider 后旧会话在 UI 里不可见的问题。

npm: codex-provider-manager

现在支持什么

• recover：统一 state_*.sqlite 和 sessions / archived_sessions 里的 provider 元数据
• sync：recover 的显式别名，适合脚本和命令记忆
• status：只读扫描当前配置、数据库分布、会话文件分布
• switch <provider>：修改 config.toml 的 model_provider，并同步本地历史
• restore：基于最近一次或指定 manifest 回退数据库和会话元数据
• prune-backups：清理旧 manifest 和不再被保留 manifest 引用的备份文件
• 自动发现最新的 state_*.sqlite，不再写死 state_5.sqlite
• 写入失败时回滚数据库事务；switch 失败时回滚 config.toml
• 检测 SQLite sidecar / lock 文件，避免在 Codex Desktop 仍在运行时直接修改数据
• status 在数据库缺失、被占用或损坏时也会继续输出诊断信息
• recover / switch 会跳过明显处于 busy 状态的会话文件，并在结果里标出来
• --pretty 终端友好输出，默认仍保持 JSON

修改范围

• SQLite：threads.model_provider
• 会话文件首行：session_meta.payload.model_provider
• 配置文件：config.toml 根级 model_provider

默认会扫描两个目录：

• <codex-home>/sessions
• <codex-home>/archived_sessions

安装

npm install -g codex-provider-manager

或直接使用：

npx codex-provider-manager --help

快速开始

先看现状：

npx codex-provider-manager status

先做只读预演：

npx codex-provider-manager --dry-run

确认后执行修复：

npx codex-provider-manager

也可以显式使用 sync 别名：

npx codex-provider-manager sync

直接切换到新 provider 并同步历史：

npx codex-provider-manager switch cliproxyapi

回退到最近一次修复前的状态：

npx codex-provider-manager restore

清理旧备份，只保留最新 3 份 manifest：

npx codex-provider-manager prune-backups --keep 3

常用命令

查看状态：

codex-provider-manager status

用更适合终端直接阅读的输出：

codex-provider-manager status --pretty

显式执行一次同步：

codex-provider-manager sync

如果你要操作的不是默认 CODEX_HOME / 用户主目录下的 .codex，再显式传路径：

codex-provider-manager status --codex-home "D:\\backup\\.codex"

仅迁移指定来源 provider：

codex-provider-manager --source-provider openai --source-provider OpenAI

连数据库里 archived = 1 的线程一起更新：

codex-provider-manager --include-archived

只改配置，不同步历史：

codex-provider-manager switch azure --config-only

从指定 manifest 回退：

codex-provider-manager restore --manifest-path "D:\\tmp\\provider-unify-session-meta-20260427-010203.json"

自定义 manifest 输出路径：

codex-provider-manager --manifest-path "D:\\tmp\\codex-provider-manager-manifest.json"

参数

通用路径参数

• --codex-home <path>：Codex 数据目录；如果传入的不是 .codex，会自动补成 .../.codex
• --config <path>：config.toml 路径
• --state-db <path>：状态库路径；未传时自动选择 <codex-home> 下最新的 state_*.sqlite
• --sessions-dir <path>：sessions 目录路径
• --archived-sessions-dir <path>：archived_sessions 目录路径

recover / 默认命令

• --target-provider <provider>：目标 provider；未传时从 config.toml 读取
• --source-provider <provider>：只迁移这些来源 provider；可重复传入
• --include-archived：数据库里 archived = 1 的线程也一起更新
• --dry-run：只输出统计，不落盘
• --no-backup：执行修改时不备份状态库
• --manifest-path <path>：自定义 manifest 输出路径
• --force：忽略 SQLite sidecar / lock 文件预警，强制执行

sync

• 与 recover / 默认命令完全等价
• 只是更贴近 codex-provider-sync / codex-switch 一类工具的命令习惯

switch <provider>

• <provider>：要切换到的目标 provider
• --source-provider <provider>：只同步指定来源 provider
• --include-archived：数据库归档线程也一起改
• --no-backup：不备份状态库
• --manifest-path <path>：自定义同步 manifest 输出路径
• --config-only：只修改 config.toml
• --force：忽略 SQLite sidecar / lock 文件预警，强制执行

restore

• --manifest-path <path>：指定要回退的 manifest；未传时自动选择 <codex-home> 下最新的一份
• --dry-run：只输出回退计划，不落盘
• --no-backup：回退前不额外备份当前状态库
• --force：忽略 SQLite sidecar / lock 文件预警，强制执行

prune-backups

• --keep <count>：保留最新多少份 manifest；默认 3
• --dry-run：只输出清理计划，不删除文件

--pretty

• 所有命令都支持 --pretty
• 不传时仍输出 JSON，适合脚本和自动化
• 传入后输出面向人的摘要视图，适合终端手动执行

输出

所有命令都输出 JSON；传 --pretty 时输出终端友好的摘要视图。

• status：当前配置 provider、候选 provider、数据库 provider 分布、sessions / archived_sessions 分布、安全预警、一致性检查，以及数据库不可读 / 不存在时的诊断
• recover / sync：目标 provider、命中数、更新数、被跳过的 busy 会话文件、备份路径、manifest 路径
• switch：旧 provider、新 provider、配置是否更新，以及一次 recover 结果
• restore：使用的 manifest、源备份路径、当前状态备份路径、恢复的 session 文件数
• prune-backups：找到的 manifest / 备份数量、保留项、删除项

风险说明

• 这个工具修的是本地元数据兼容性，不是恢复已删除历史
• 它不会合并不同机器、不同账号、不同 CODEX_HOME 的数据
• 默认会备份状态库，但首次操作前仍建议手动备份整个 .codex
• 如果看到 lock / sidecar 预警，优先先退出 Codex Desktop，再执行恢复或切换

开发

npm install
npm run build
npm test