基于 CC Switch 的 Codex 会话同步工具
用于 Codex 聊天记录同步、Codex 历史会话同步、Codex 会话记录同步 的 Windows 小工具。它可以在使用 cc-switch 切换官方 / 中转 provider 时，尽量保持同一套本地 Codex 会话历史可见。
English: A Windows helper for Codex session history sync, Codex chat history sync, and keeping local Codex conversations visible when switching providers with cc-switch.
新版 Codex 兼容性修复（2026-11-06）
旧版脚本根据 rollout 文件名截取线程 ID，可能把新版分页会话的元数据写成无效 ID，并重建错误索引，造成 failed to read session metadata 或“无法加载消息”。本版移除了所有 rollout、SQLite 会话状态和会话索引改写代码，仅同步 provider 配置。更新后重新运行安装脚本以替换后台 watcher 使用的脚本。
本工具不再修复历史数据，也不保证切换官方/中转后所有旧 provider 的会话都可见。已经发生的元数据损坏需要从匹配的切换前备份恢复，见 故障排查。
本次更新目标
本次更新主要解决 cc-switch 切换 Codex provider 后的状态残留问题：
- 修复同步窗口偶尔未真正执行，导致历史记录没有完成同步。
- 防止旧 provider 配置将当前 GPT-5.6 模型回退为 GPT-5.5 / GPT-5.4。
- 修复 Codex Desktop 使用过期登录缓存后出现的
401 Unauthorized / token_expired。
- 区分官方与中转 provider，避免模型配置和登录状态互相覆盖。
- 兼容新版 Codex Desktop 的
ChatGPT.exe 进程和 MSIX 启动方式。
更新后的自动流程为：检测 provider 变化 → 关闭 Codex → 按 provider 类型清理必要缓存 → 同步 provider 配置 → 重新启动 Codex。
关键词
如果你在搜索这些问题，这个工具可能适用：
- Codex 聊天记录同步
- Codex 历史会话同步
- Codex 会话记录同步
- Codex conversations / sessions / history sync
- cc-switch 切换中转后 Codex 历史丢失
- Codex 切换 provider 后历史会话不可见
解决什么问题
Codex 的本地历史会同时依赖 rollout 文件、state_5.sqlite 和 session_index.jsonl。使用 cc-switch 切换不同 Codex provider 后，历史可能因为 model_provider 不一致而分裂或不可见。
这个工具会：
- 监听 cc-switch 的当前 Codex provider 变化。
- 运行时扫描 cc-switch 中现有的 Codex provider：官方 OpenAI 保持
openai，其余中转统一写成 ccs。
- 保留 Codex 原生会话存储，不改写 rollout、SQLite 会话状态或会话索引。
- 保留当前 Codex 顶层模型默认值，避免 cc-switch 旧 provider 配置把
gpt-5.6-* 回退成旧模型。
- 切到中转 provider 时清理会导致
token_expired 的 Codex Desktop 过期 web 登录缓存。
- 删除会覆盖
auth.json 的用户级 CODEX_API_KEY 环境变量。
- 切换后弹出一个简洁进度窗口。
- 成功后自动启动 Codex。
- 每天首次同步前自动备份关键状态。
支持范围
- Windows
- OpenAI Codex Desktop / Codex CLI
- cc-switch
- PowerShell 5.1+
- Python 可用，且能运行标准库
sqlite3
安装
在仓库根目录运行：
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1
安装脚本会：
- 复制核心脚本到
$env:CODEX_HOME，默认 ~\.codex
- 创建 Windows 启动项
Codex History Sync.lnk
- 启动后台 watcher
- 备份安装前的相关状态到
~\.codex\history-sync-tool-backups\install_<timestamp>
使用
安装后正常使用 cc-switch。点击某个 Codex provider 的“启用”后：
- watcher 检测到 provider 变化；
- 弹出同步进度窗口；
- 自动关闭正在运行的 Codex，避免旧 provider / 旧 token 状态残留；
- 如果目标是中转 provider，清理 Codex Desktop 过期 web 登录缓存；
- 自动同步 provider 配置；
- 同步完成后自动启动 Codex。
手动同步：
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$env:CODEX_HOME\sync-codex-history.ps1"
手动运行 UI 包装脚本时仍会询问是否关闭 Codex：
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$env:CODEX_HOME\run-codex-history-sync-ui.ps1"
恢复 / 卸载
只停用工具，不恢复数据库：
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\restore.ps1
恢复最近一次安装备份：
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\restore.ps1 -RestoreLatestBackup
恢复数据库前脚本会要求输入 RESTORE 确认。
风险说明
日常切换会修改以下配置或缓存：
config.toml- cc-switch 的 Codex provider 配置
- Codex Desktop 的 Chromium web 登录缓存（仅中转 provider 自动切换时）
- 用户级
CODEX_API_KEY 环境变量覆盖项
它不会上传任何数据，也不会把你的会话同步到云端。所有处理都在本机完成。
注意：
- 中转的配置标识统一为
ccs；历史会话中的原始 provider 和线程 ID 保持不变。
- 自动切换 provider 时会关闭 Codex，正在运行的任务可能会被中断。
- 配置、cc-switch 数据库和 web 缓存备份可能包含凭据，只保存在本机，不应上传或分享。
- 直接切换到官方的途径登陆可能会导致官方的会话丢失
- 不要把自己的
.codex、.cc-switch、备份、auth.json、SQLite 数据库提交到 GitHub。
不包含什么
- 不修改 cc-switch 本体。
- 不提供健康检查脚本。
- 不清理 Codex 的
logs_2.sqlite 运行日志。
- 不处理跨设备同步。
License
MIT
评论