Mac 使用 CCSwitch 切换中转站后恢复 Codex 历史记录

这篇笔记记录在 Mac 上使用 CCSwitch 切换 Codex 中转站或模型提供方后，历史对话突然不显示时的排查和恢复方法。

先说结论：历史文件通常仍保存在 Mac 本机，只是切换 Provider 后，当前环境可能无法直接查询旧 Provider 下的线程。

本文使用第三方命令行工具 codex-threadripper 重新扫描和同步本地线程。它不是 OpenAI 官方工具，安装和执行前建议先确认软件来源，并完整备份 ~/.codex。

问题现象

使用 CCSwitch 切换 Codex 的中转站、model_provider 或 base_url 后，可能出现以下情况：

Codex 可以正常启动和回答问题。
新创建的对话可以正常保存。
切换前的历史对话不再显示。
~/.codex 目录仍然存在，磁盘空间也没有明显减少。

这类情况不一定代表历史文件被删除。Codex 的本地线程数据可能带有 Provider、模型来源或环境相关信息；切换配置后，新环境看到的线程集合可能和旧环境不同。

恢复思路

完整流程可以概括为：

备份 ~/.codex
    -> 使用 CCSwitch 切换到目标中转站
    -> 确认 Codex 可以正常运行
    -> 使用 codex-threadripper 扫描并同步线程
    -> 重新打开 Codex
    -> 检查历史记录和工具状态

不要在没有备份的情况下直接修改或删除 Codex 本地数据库。历史文件还在时，通常还有恢复空间；原始数据一旦被覆盖，处理会麻烦很多。

安装 codex-threadripper

codex-threadripper 是用于扫描和处理 Codex 本地历史线程的第三方命令行工具。根据你使用的包管理方式，可以选择 Homebrew 或 npm。

使用 Homebrew 安装

brew tap wangnov/tap
brew install codex-threadripper

使用 npm 全局安装

npm i -g codex-threadripper

安装后先检查命令是否可用：

codex-threadripper --help

如果 Homebrew 或 npm 提示找不到包，说明当前软件源中没有该工具，或者工具名称、仓库地址已经变化。此时不要使用来源不明的二进制文件，先确认项目仓库和发布页面。

Mac 推荐恢复流程

备份 Codex 本地数据

先退出正在运行的 Codex，再执行备份：

cp -R ~/.codex ~/.codex_backup_$(date +%Y%m%d_%H%M%S)

确认备份目录已经生成：

ls -ld ~/.codex_backup_*

备份内容可能包含账户信息、配置和历史对话，不要上传到公开网盘、公共仓库或发送给不可信的人。

使用 CCSwitch 切换目标中转站

在 CCSwitch 中切换到需要使用的目标中转站或模型提供方，然后重新打开 Codex，确认：

Codex 可以正常启动。
当前 Provider 可以正常鉴权。
可以发送一条测试消息并收到回复。

先保证新环境本身可用，再同步历史记录。否则 Provider 配置问题和历史索引问题会混在一起，不容易判断故障位置。

执行线程同步

在 Mac 终端运行：

codex-threadripper sync

如果工具没有自动识别 Codex 数据目录，可以显式指定：

codex-threadripper --codex-home "$HOME/.codex" sync

其中 $HOME/.codex 会在 macOS 上解析为：

/Users/你的用户名/.codex

同步过程中不要同时启动多个 Codex 实例，也不要中途删除 ~/.codex 中的数据库或线程文件。

重新加载 Codex

同步完成后，完全退出并重新启动 Codex，然后从当前版本提供的历史记录或恢复线程入口查看对话。

Codex 不同版本的历史入口可能不同。若某个参数或交互指令不可用，先查看当前安装版本支持的命令：

codex --help

部分版本或界面可能提供历史列表、恢复会话、线程列表或搜索入口，应以当前客户端实际显示为准。

查看同步状态

可以使用第三方工具检查当前线程状态：

codex-threadripper status

如果该版本支持 Provider 分组，状态输出会按 custom、openai 等来源列出线程，便于确认旧记录是否已经被扫描和合并。

如何判断恢复成功

可以从以下几个方面检查：

切换前的历史线程重新出现在 Codex 中。
打开旧线程后，用户消息和 Codex 回复顺序完整。
新 Provider 下可以继续创建和保存对话。
codex-threadripper status 能扫描到预期线程。
重启 Codex 后，恢复的线程仍然可见。

常见问题排查

找不到 codex-threadripper 命令

先检查安装路径：

which codex-threadripper
codex-threadripper --help

如果通过 npm 安装，还需要确认 npm 全局可执行目录已经加入 PATH。

同步后仍然看不到旧对话

按下面顺序检查：

确认同步时使用的是实际 Codex 目录 ~/.codex。
确认执行同步前已经切换到目标 Provider。
完全退出 Codex 后重新启动，而不是只关闭窗口。
使用 status 检查工具是否扫描到旧线程。
检查旧数据是否位于其他 CODEX_HOME 目录或备份目录。
查看同步命令输出中是否有数据库锁、权限或格式不兼容错误。

同步时提示数据库被占用

先退出 Codex 和其他可能访问 ~/.codex 的进程，再重试。不要在数据库正在写入时强制复制或修改索引。

切回旧 Provider 后历史又出现

这通常说明原始历史数据没有丢失，而是不同 Provider 环境下的线程可见范围或索引不同。此时更应该先备份，再决定是否执行同步，而不是删除旧配置。

回滚方法

如果同步后出现异常，先退出 Codex。保留当前异常目录用于排查，然后将备份恢复为 ~/.codex。

恢复前务必确认备份目录名称。下面只是示例：

mv ~/.codex ~/.codex_after_sync
cp -R ~/.codex_backup_20260611_120000 ~/.codex

不要直接照抄示例中的时间戳，应替换为你实际生成的备份目录。

安全提醒

~/.codex 可能包含登录状态、Provider 配置、API Key 引用和对话内容。
不要把完整目录提交到 Git。
不要把数据库文件发送给陌生人排查。
使用第三方线程工具前，先检查来源、安装脚本和发布文件。
每次同步前都保留一份未修改的原始备份。

小结

使用 CCSwitch 切换 Codex 中转站后，历史记录消失通常不等于本地数据被删除，更可能是 Provider 配置变化后旧线程没有被当前环境读取。处理这类问题时，最重要的顺序是：先备份，再切换并验证 Provider，最后同步线程和检查结果。

codex-threadripper 可以作为第三方恢复手段，但命令和包来源可能随版本变化。实际操作时，应先通过 --help 核对当前版本，再对 ~/.codex 做任何写入操作。