CC Switch 切换 OpenAI Official 与第三方 API 后 Codex 历史消失？完整双向恢复与无缝切换手册

CC Switch 中 OpenAI Official 与第三方 API 双向切换Codex 历史记录与请求兼容操作手册适用场景Windows 本地 Codex Desktop / ChatGPT Desktop通过 CC Switch 在 OpenAI Official 与第三方 API、中转站或自定义 provider 之间切换。本文基于 2026-07-30 的一次真实修复和后续协议兼容故障整理。最终成功同步 SQLite 190 条、JSONL 190 个共恢复并统一 193 条本地会话数据库完整性检查结果为ok。随后又定位了第三方 API 返回非官方响应对象 ID导致旧任务切回官方 API 后无法继续对话的问题。1. 先说结论切换 API 后侧栏历史突然消失很多时候不是消息被删除而是同一批本地会话被不同的model_provider分成了几组。但“侧栏历史可见”和“同一任务能被另一家 API 继续执行”是两个不同问题历史可见性问题由 SQLite、JSONL 中的model_provider和rollout_path决定使用 Provider Sync 处理。请求/响应协议连续性问题第三方虽然接受 Codex 的 Responses 请求却可能返回不符合 OpenAI Responses 约定的对象 ID导致切回官方 API 后续聊失败。本次真实错误为[ApiIdParam] [input[9].id] [invalid_id_prefix] Invalid input[9].id: item_.... Expected an ID that begins with rs.这不是历史消失也不是 Provider Sync 失败而是第三方写进本地 JSONL 的 reasoning 对象使用了通用item_ID。官方 API 恢复该任务时要求 reasoning ID 以rs_开头因此拒绝整个请求。要做到双向切换时历史记录始终可见有两条路线长期推荐两个 CC Switch profile 使用同一个稳定 provider ID。OpenAI Official 使用 Codex 内置openai。第三方 API 也使用内置openai仅通过顶层openai_base_url改变接口地址。只有第三方接口和认证方式兼容 Codex 内置 OpenAI provider且 CC Switch 不会覆盖该配置时才能采用。通用稳妥CC Switch 切换后把本地历史同步到当前真实 provider。如果官方 profile 是openai就同步到openai。如果第三方 profile 是custom、ccswitch、code-switch或其他 ID就同步到那个实际 ID。每次必须先 DryRun、确认警告为 0再正式同步。本文重点推荐第二条处理历史可见性第三方响应兼容性则优先使用 CC Switch 的“需要本地路由映射”让 CC Switch 把第三方 Chat Completions 响应重建成 Codex 所需的 Responses 形态。2. 现象常见表现包括CC Switch 切到 OpenAI Official 后项目名称还在但历史任务全部或大部分消失。从官方切回第三方 API 后只能看到第三方期间创建的任务。切换后只显示刚刚新建的一条会话。sessions下的 JSONL 文件仍然存在但 Codex 侧栏不显示。不同登录方式看到的是两套历史记录。SQLite 中能查到会话但当前界面仍为空。这些症状不能直接证明数据已经丢失。应先检查 provider 元数据和rollout_path不要删除数据库或覆盖会话目录。3. 根因provider 元数据分裂本次故障中SQLite 曾同时出现cc-switch-official custom openai切回 OpenAI Official 后当前配置没有显式写model_provider。根据 Codex 官方配置参考model_provider的默认值是内置的openai新任务也确实以openai写入数据库。旧任务仍标记为custom或cc-switch-official因此侧栏看起来像“历史记录丢了”。本地会话至少要关注两处 provider 元数据state_版本.sqlite └─ threads.model_provider sessions / archived_sessions └─ JSONL 首行 session_meta.payload.model_provider只修改 SQLite、不修改 JSONL或只修改 JSONL、不修改 SQLite都可能造成后续重建、索引和显示不一致。此外还要检查threads.rollout_path它必须指向当前CODEX_HOME下实际存在的 JSONL。如果数据库还指向迁移前的旧磁盘或旧用户目录即使 provider 正确修复工具也应停止操作。说明Codex 官方文档公开说明了model_provider、openai_base_url、CODEX_HOME等配置含义但没有把 Desktop 侧栏的全部内部过滤和 SQLite schema 承诺为稳定公共接口。本文关于历史可见性的结论来自本机实测以及社区项目的交叉验证未来 Codex 版本可能调整内部结构。3.1 第二类根因第三方响应对象 ID 不兼容本机出错的第三方 profile 已经配置wire_api responses requires_openai_auth true也就是说Codex 发出的请求本来就是 Responses API。问题不在“请求格式没有设置成官方格式”而在第三方服务返回的 Responses 对象不规范。本机正常官方响应和异常第三方响应的对比如下对象类型官方响应中观察到的 ID 前缀异常第三方返回reasoningrs_item_assistant messagemsg_item_function callfc_item_custom tool callctc_item_本次共在 5 个会话文件中发现 141 个通用item_响应对象其中包括reasoning 46 assistant message 39 function call 12 custom tool call 44其中 46 个异常 reasoning 均没有可用于安全重建的encrypted_content。因此不能简单把item_批量替换成rs_ID 可能还被后续工具调用、响应引用或服务端状态关联机械改前缀只能改变表象不能证明语义关系仍然正确。3.2 为什么 Provider Sync 不能修复这个错误Provider Sync 只负责同步threads.model_provider session_meta.payload.model_provider它不会、也不应该改写每条response_item的正文和对象 ID。因此Provider Sync 可以让 193 条历史重新出现在侧栏。Provider Sync 不能让已经污染的旧任务重新满足官方 Responses API 的对象约束。这两类修复必须分别处理不能把“历史可见”误认为“跨服务继续请求一定兼容”。4. 准备工作4.1 使用正确的 CODEX_HOMECodex 官方文档说明本地状态保存在CODEX_HOME默认是%USERPROFILE%\.codex但 CC Switch、多实例配置或自定义安装可能使用其他目录。必须确认当前 Codex 实例真正读取的是哪一个目录。【本地 Windows PowerShell】目的查看当前进程和用户级环境变量是否设置了CODEX_HOME。执行目录任意目录。[Environment]::GetEnvironmentVariable(CODEX_HOME,Process)[Environment]::GetEnvironmentVariable(CODEX_HOME,User)正常输出输出一个实际存在的.codex目录或两行均为空此时通常使用%USERPROFILE%\.codex。停止条件找到了多个.codex但无法确认当前实例使用哪个。config.toml、sessions和state_版本.sqlite分别位于不同目录。不要凭印象选择旧目录。操作错CODEX_HOME可能得到“工具提示成功但 Codex 仍看不到历史”的假象。4.2 下载实际使用的修复工具本文实测使用pipabcc/codex-history-session-recovery实测版本v1.2.0许可证MIT License它会同步SQLite 的threads.model_providersessions和archived_sessions中有效 JSONL 首行的 provider并提供Codex 进程检测DryRunSQLite 完整性检查WAL/SHM 一致性快照JSONL 首行备份事务写入失败回滚完成报告从 GitHub 下载发布包后完整解压确保以下文件在同一目录provider-sync.bat provider-sync.ps1 README.md不要只下载来历不明的 BAT也不要直接在压缩包预览窗口运行。4.3 完全退出 Codex正确顺序是完全退出 Codex/ChatGPT Desktop → 确认托盘与后台进程退出 → 在 CC Switch 启用目标配置 → 暂时不要重新启动 Codex → 检查真实 provider → DryRun → 正式同步 → 启动 CodexProvider Sync 会在检测到以下相关进程时拒绝写入ChatGPT codex codex-code-mode-host codex-plus-plus-manager这是正常安全保护。不要为了省一步而强行绕过。5. 每次切换后的标准操作以下示例使用占位路径CODEX_HOME 工具目录 STATE_DB执行前必须替换成自己机器上的绝对路径例如D:\CodexData\.codex D:\Tools\codex-history-session-recovery D:\CodexData\.codex\state_5.sqlite第一步在 CC Switch 中启用目标 profile目标可以是OpenAI Official第三方 API中转站自定义 provider启用后不要只看 CC Switch 卡片名称。卡片名称是给人看的Codex 实际使用的是生成到config.toml中的 provider ID。第二步读取真实 provider【本地 Windows PowerShell】目的读取切换后 Codex 实际配置中的model_provider。执行目录任意目录。Select-String-LiteralPathCODEX_HOME\config.toml-Pattern^\s*model_provider\s*-Encoding UTF8可能输出model_provider custom或model_provider cc-switch-official也可能没有任何输出。判断规则有输出使用引号中的实际值。没有输出Codex 官方默认 provider 是openai。不要根据“OpenAI Official”按钮名称猜成cc-switch-official。本次真实修复中旧说明曾按历史行为推测为cc-switch-official但切换后的实际配置没有显式 provider新任务写入值是openai。最终同步目标必须以当前配置为准。第三步DryRun假设上一步确认目标为openai。【本地 Windows PowerShell】目的只读盘点需要修改的数据库记录和 JSONL不写入数据、不创建持久备份。执行目录工具目录。Set-Location-LiteralPath工具目录.\provider-sync.bat -DryRun -NonInteractive -TargetProvider openai -CodexHomeCODEX_HOME-StateDbPathSTATE_DB正常输出应同时满足RESULT|success|0|db数量|jsonl数量|backup 警告/跳过项0 当前为 DryRun不会写入 Codex 数据或创建持久备份。停止条件RESULT|failed警告/跳过项不为 0JSONL 缺失rollout_path越出会话目录SQLite 完整性检查失败盘点期间数据库、WAL 或 SHM 发生变化修改数量明显不符合预期如果目标 provider 是custom只替换-TargetProvider custom其他参数保持不变。第四步正式同步DryRun 成功且警告为 0 后去掉-DryRun。【本地 Windows PowerShell】目的创建安全备份后把 SQLite 与 JSONL provider 同步到当前目标值。执行目录工具目录。Set-Location-LiteralPath工具目录.\provider-sync.bat -NonInteractive -TargetProvider openai -CodexHomeCODEX_HOME-StateDbPathSTATE_DB正常输出RESULT|success|0|db修改数|jsonl修改数|backup备份目录备份默认位于CODEX_HOME\backups\provider-sync-bat\时间戳-随机标识\停止条件退出码不是 0。显示回滚未完成。完整性检查失败。工具提示不要启动 Codex。第五步重新启动 Codex 并验证正式同步成功后再启动 Codex。检查原有项目与任务是否重新出现。活动会话和归档会话是否完整。新建任务是否仍能正常保存。再次重启后历史是否仍存在。6. 双向切换速查表切换方向当前config.toml的实际 providerProvider Sync 目标第三方 → OpenAI Official没有显式值使用默认值openai第三方 → OpenAI Officialmodel_provider cc-switch-officialcc-switch-officialOpenAI Official → 第三方model_provider customcustomOpenAI Official → 第三方model_provider ccswitchccswitch任意方向其他实际 ID原样使用该 ID最短流程退出 Codex → CC Switch 启用目标配置 → 读取 config.toml 的真实 provider → DryRun 到该 provider → 确认 success 且 warnings0 → 正式 Provider Sync → 启动 Codex7. 第三方响应格式兼容使用 CC Switch 本地路由7.1 适用判断先编辑第三方 profile检查其真实上游能力上游原生、完整支持 OpenAI Responses API并能返回规范对象 ID可直接使用不必转换。上游只支持 Chat Completions或者虽然声称支持 Responses、实测却生成通用item_ID开启“需要本地路由映射”。本次异常 profile 的wire_api responses已经正确单纯重复设置wire_api无法解决问题。需要改变的是上游处理路径让 CC Switch 接收 Codex 的 Responses 请求转换成第三方 Chat Completions 请求再把第三方响应重建成 Responses 形态。数据流如下Codex Responses 请求 → CC Switch 127.0.0.1:15721/v1 → 转换为第三方 /v1/chat/completions → 第三方返回 Chat/SSE → CC Switch 重建 reasoning、message、tool call 等 Responses 对象 → Codex 写入本地 JSONL7.2 CC Switch 3.18 设置以出错的第三方 profile 为例编辑第三方 provider。开启“需要本地路由映射”Needs Local Routing。上游格式设为 OpenAI Chat Completions对应的内部元数据通常是{apiFormat:openai_chat}在模型映射中确认 Codex 模型名能够映射到第三方真实模型名。打开“设置 → 路由 → 本地路由”开启本地路由主开关在“路由已启用”中开启 Codex默认地址保持127.0.0.1:15721除非端口冲突。如果需要频繁往返官方和第三方再打开“设置 → Codex 应用增强 → 切换第三方供应商时保留官方认证”。切换 provider 后完全重启 Codex使模型目录和 provider 配置重新加载。不要在 CC Switch 和 Codex 正在运行时直接编辑cc-switch.db。界面设置会同时维护 provider 元数据、本地路由状态、live 配置和备份只改 SQLite 的meta.apiFormat并不能自动启动代理或完成 Codex 接管。7.3 双向切换顺序OpenAI Official → 第三方 API确认第三方支持 /v1/chat/completions → 开启本地路由主开关和 Codex 路由 → 启用已勾选“需要本地路由映射”的第三方 profile → 完全重启 Codex → 新建测试任务验证 → 如 provider ID 改变再按第 5 节执行 Provider Sync第三方 API → OpenAI Official完全退出 Codex → 关闭 Codex 本地路由接管 → 启用 OpenAI Official → 检查 config.toml 的真实 provider → 必要时执行 Provider Sync → 启动 CodexCC Switch 官方指南不建议把 OpenAI Official 流量经由第三方本地路由接管。切回官方前先关闭 Codex 路由既能减少配置混淆也避免把官方认证流量错误送入第三方代理路径。7.4 上线前验证不要直接在重要旧任务中测试。先创建一个不含敏感信息的新任务至少验证CC Switch 请求日志出现目标第三方 provider。实际上游路径是/v1/chat/completions而不是继续直通/v1/responses。流式输出、reasoning、普通文本和工具调用都能完成。完全重启 Codex 后该测试任务仍能继续。切回 OpenAI Official 后该任务不会再出现invalid_id_prefix。如果第三方不支持/v1/chat/completions常见结果是 404此时应关闭本地路由映射联系服务商修复 Responses 实现或更换真正兼容的上游。CC Switch 转换器本身也可能存在特定 payload 的兼容边界因此测试通过只能证明当前模型和工具组合可用不能视为对所有请求的永久保证。8. 真正“无需每次同步”的长期方案Codex 官方配置参考说明model_provider默认值是openai。openai是内置保留 provider ID不能通过[model_providers.openai]覆盖。openai_base_url可以修改内置openaiprovider 的 Base URL。因此在兼容条件满足时可以让官方和第三方 profile 都使用同一个 provider IDOpenAI Official profilemodel_provider openai不要保留第三方的openai_base_url https://第三方地址/v1第三方 API profilemodel_provider openai openai_base_url https://第三方地址/v1不要创建[model_providers.openai]因为openai是内置保留 ID。这个方案的适用条件必须同时满足第三方接口兼容 Codex 当前使用的 OpenAI Responses API。第三方认证可以由内置openaiprovider 正常完成。CC Switch profile 支持持久保存这组配置。每次点击“启用”后CC Switch 不会把 provider ID 改回custom等其他值。官方 profile 会移除第三方openai_base_url不会把官方请求继续发往第三方地址。如果任一条件不满足继续使用“切换后 Provider Sync”方案。不要为了统一 provider 而复制 OAuth token、API key 或auth.json。9. 本次真实案例9.1 切换后的状态切到 OpenAI Official 后config.toml 没有显式 model_provider 新任务 openaiDryRun 前数据库分布cc-switch-official 4 custom 186 openai 3 总计 193DryRun目标 provideropenai 预计修改数据库记录190 预计修改 JSONL 文件190 警告/跳过项0 RESULT|success|0正式同步数据库更新190 JSONL 更新190 RESULT|success|0同步后openai 活动会话162 openai 归档会话31 总计193 SQLite integrity_checkok历史记录重新出现在 Codex 侧栏。9.2 这次踩过的坑坑 1根据 CC Switch 卡片名猜 provider旧记录曾经出现cc-switch-official但这一次 OpenAI Official 实际使用的是默认openai。经验始终读取当前 config.toml没有显式值时按官方默认 openai 处理。坑 2自动化脚本只识别英文警告字段第一次自动任务中Provider Sync 的 DryRun 已成功且显示警告/跳过项0但外层脚本只查找英文warnings0因此安全停止没有进行正式写入。这不是数据修复失败而是外层自动化误判。经验人工操作应同时检查 DryRun 摘要和RESULT|success|0。自动化不要只匹配本地化界面文本。正式阶段优先解析工具输出的结构化CONFIRM|...|warnings0和RESULT|...。保护条件不满足时应停止不能“默认继续”。坑 3Codex 运行时修改数据库SQLite 可能同时存在 WAL/SHM运行中复制或覆盖主数据库会产生不一致风险。经验完全退出 Codex 后再盘点、备份和写入。坑 4只改 SQLite如果 JSONL 首行仍保留旧 provider后续索引重建可能再次出现分裂。经验SQLite 和 JSONL provider 必须一起同步。坑 5操作了旧 CODEX_HOME多实例或迁盘后旧目录可能仍然存在看起来结构也完整。经验先确认当前实例使用的 CODEX_HOME再执行任何修复。10. 常见错误处理10.1 检测到 Codex 相关进程完全退出Codex DesktopChatGPT DesktopCodex CLICodex系统托盘中的相关进程不要使用强制参数绕过。10.2 rollout path 越出会话目录说明 SQLite 的threads.rollout_path可能仍指向旧磁盘、旧用户目录或不存在的 JSONL。处理原则不要立即同步 provider。按线程 ID 在当前CODEX_HOME中定位真实 JSONL。先备份数据库。只修复能够一一对应的路径。再运行 Provider Sync DryRun。本文所用仓库提供了repair-rollout-paths.ps1但它涉及具体的新旧路径映射。必须先运行诊断模式确认所有映射都可解释后才允许-Apply。10.3 DryRun 成功但侧栏仍为空依次检查是否操作了当前实例真正使用的CODEX_HOME。正式同步是否真的执行而不是只完成 DryRun。当前配置 provider 是否与 SQLite、JSONL 一致。会话是否全部被标记为归档。rollout_path是否真实存在。是否完全重启了 Codex。如果 JSONL 存在但 SQLite 或索引缺失可考虑aisspire/codexSessionManager许可证MIT License用途预览、备份恢复、修复 SQLite/JSONL/index 不一致不要直接删除state_版本.sqlite期待 Codex 自动重建。10.4 CC Switch 再次覆盖 config.toml这是 profile 重新生成配置的结果。可选处理在 CC Switch profile 中修正生成配置。如果当前版本无法固定 provider ID则每次切换后运行 Provider Sync。不要只手改当前config.toml因为下次点击“启用”可能再次被覆盖。11. 发布日志或截图前的脱敏清单不要公开auth.jsonAPI keyBearer tokenOAuth token未脱敏的config.toml完整 SQLite 数据库WAL/SHMJSONL 会话文件Provider Sync 备份包含用户名、项目路径、线程 ID 的完整日志CC Switch profile 数据库或导出包可以公开provider 计数修改数量integrity_check ok已脱敏的 Base URL 示例不含密钥的命令模板工具版本与公开仓库链接12. 开源项目、引用与许可证说明12.1 CC Switch项目farion1231/cc-switch用途管理并切换 Codex、Claude Code 等工具的 provider/profile在本地路由模式下完成 Responses 与 Chat Completions 的协议转换。许可证MIT License。官方仓库声明的官方网站ccswitch.io本文使用的功能说明添加 Codex 供应商本地路由实战在 Codex 中使用 DeepSeek功能来源CC Switch v3.16.0 Release NotesCC Switch 文档说明“需要本地路由映射”会把 Codex 的 Responses 请求转换为上游 Chat Completions并把流式响应、reasoning 和工具调用重建成 Responses 形态。本文只讨论该开源项目的配置切换与协议转换行为不为任何第三方 API 或中转服务背书。12.2 Codex 历史记录 / 会话恢复工具项目pipabcc/codex-history-session-recovery用途同步 SQLite 和 JSONL 中的model_provider。许可证MIT License。本文实际使用版本v1.2.0。本次 190 条 SQLite、190 个 JSONL 的正式同步由该工具完成。如复制、修改或再发布源码应保留项目 MIT License 中要求保留的版权和许可声明。12.3 Codex Session Merge Fix项目yanyan1115/codex-session-merge-fix用途提供model_provider分裂、统一使用openai和openai_base_url的早期排查思路。本文引用范围问题定位思路和配置方向不直接复制其修复脚本。许可证说明截至本文整理时本地检出的仓库根目录未发现独立LICENSE文件。公开可读不等于可以任意复制、修改和再发布源码如需复用代码应先向原作者确认授权。12.4 Codex Session Manager项目aisspire/codexSessionManager用途会话查看、备份恢复、数据库修复和路径修复。许可证MIT License。本文定位Provider Sync 无法解决 JSONL 缺失、SQLite/index 不一致时的可选辅助工具。13. OpenAI 官方资料Codex Configuration Referencemodel_provider默认值为openai。openai、ollama、lmstudio是内置保留 provider ID。openai_base_url用于覆盖内置openaiprovider 的 Base URL。Codex Advanced ConfigurationCodex 状态保存在CODEX_HOME。如果只是让内置 OpenAI provider 指向代理应使用顶层openai_base_url不要定义[model_providers.openai]。Codex Authentication本地 Codex 支持使用 ChatGPT 登录也支持 API key 登录。认证方式与 provider 元数据是相关但不同的层面不要为了统一历史而混用或复制认证文件。Responses APIOutput item 事件Responses 输出由带类型和 ID 的 item 组成。本文的rs_、msg_、fc_、ctc_对照来自本机官方响应实测不要把本地观察到的所有内部前缀当作永远不变的公共兼容承诺。14. 免责声明本文不是 OpenAI、CC Switch 或任何第三方 API 服务的官方文档。Provider Sync 和其他会话修复工具均为社区项目。本文只能恢复“本地文件仍存在、但因元数据或索引不一致而不可见”的会话不能从云端找回已经删除或从未保存到本机的数据。Codex 内部 SQLite schema 和 Desktop 过滤行为可能随版本变化。操作前必须备份并优先使用带 DryRun、完整性检查和回滚机制的工具。第三方 API 存在隐私、稳定性、计费、模型真实性和合规风险请自行评估不要上传敏感项目与凭据。15. 一句话总结历史是否显示统一 SQLite 与 JSONL 的 model_provider并保证 rollout_path 有效。 任务能否跨 API 继续还要保证第三方返回兼容的 Responses 对象。 第三方 Responses 实现不规范时使用 CC Switch 本地路由将 Chat Completions 响应重建为 Responses 切回 OpenAI Official 前关闭 Codex 本地路由必要时再执行 Provider Sync。