Codex History Migrator：给 Codex 本地历史做一次优雅搬家

如果你经常使用 Codex，本地 .codex 目录里会慢慢积累大量会话历史。问题也随之出现：换电脑后历史怎么带走？切换 model_provider 后，旧线程为什么像“消失”了一样？想整理、归档、导出部分历史，又不想手动翻 SQLite 和 JSONL 文件怎么办？

这就是我做 Codex History Migrator 的原因。

项目地址：qiufengawa/codex-history-migrator

它是什么？

Codex History Migrator 是一个基于 Rust + egui/eframe 编写的轻量级跨平台桌面工具，用来迁移、同步和管理 Codex 本地历史数据。

它主要解决三件事：

历史迁移：把一台机器上的 Codex 聊天历史导出成迁移包，再导入到另一台机器。
Provider 同步：当 config.toml 里的 model_provider 改变后，把旧线程统一同步到当前 Provider。
历史管理：筛选、预览、归档、恢复、删除或选择性导出本地会话。

简单说，它是一个给 Codex 本地历史准备的“搬家 + 整理 + 修复可见性”的桌面工具。

为什么需要它？

Codex 的本地历史并不是一个单独的文本文件，而是分散在 .codex 目录中的数据库、会话文件和索引文件里。手动迁移很容易漏文件，也容易遇到路径不一致、线程不可见、Provider 分散等问题。

Codex History Migrator 把这些细节封装成图形界面操作，让普通用户也可以比较安心地完成迁移。

核心功能

支持 Windows、macOS、Linux
自动识别本机 .codex 目录
扫描本地历史并显示统计信息
导出完整迁移包
导入迁移包到目标 .codex
导入前可自动备份，默认开启
检查当前 Provider 与历史线程分布
一键同步旧线程到当前 Provider
支持恢复最近一次 Provider 同步备份
支持会话筛选、预览、归档、取消归档
支持选择性导出、删除到回收站、恢复和清理回收站

它不会迁移什么？

为了保持工具轻量、安全、可控，本项目不会迁移这些内容：

登录状态
API Token 或密钥
桌面端账号数据库
插件安装状态
MCP 注册配置
与聊天历史无关的本地缓存

也就是说，它专注于“聊天历史迁移”，不会碰你的敏感凭据。

如何使用？

方式一：下载 Release

打开项目的 Release 页面：

https://github.com/qiufengawa/codex-history-migrator/releases

根据系统下载对应安装包：

Windows：.exe
macOS：.zip 或 .dmg
Linux：.tar.gz 或 .AppImage

截至本文编写时，最新版本是 v1.1.1。

方式二：从源码运行

如果你已经安装 Rust，可以直接从源码运行：

git clone https://github.com/qiufengawa/codex-history-migrator.git
cd codex-history-migrator
cargo run --release

本地编译：

cargo build --release

Windows 下产物默认位于：

target\release\codex-history-migrator.exe

典型使用流程

1. 迁移 Codex 历史

在旧电脑上打开工具。
确认工具识别到正确的 .codex 目录。
在概览页点击扫描。
切换到导出页，生成迁移包。
把迁移包复制到新电脑。
在新电脑打开工具，选择迁移包并导入。
建议保持“导入前自动备份”开启。

2. 统一 Provider 历史

如果你切换过 model_provider，可能会发现部分旧历史分散在不同 Provider 名称下。

这时可以：

打开同步页。
查看当前 Provider 和线程分布。
点击一键同步到当前 Provider。
如有问题，可以恢复最近一次同步备份。

3. 管理历史会话

管理页适合用来整理长期积累的历史：

按关键词搜索标题、路径、线程 ID、Provider、模型
查看会话详情和预览内容
批量归档或取消归档
选择部分会话单独导出
删除到回收站
从回收站恢复或彻底清理

安全设计

这个工具没有把“能跑”作为唯一目标，而是额外处理了不少迁移场景里的风险：

导入前校验迁移包结构
使用 SHA-256 校验文件完整性
拒绝压缩包路径穿越
只导出 .codex/sessions 和 .codex/archived_sessions 下的会话文件
导入和 Provider 同步前都支持备份

对于本地历史迁移工具来说，这些细节非常重要。因为一旦写坏数据库或会话索引，恢复成本会很高。

项目技术栈

Rust
egui / eframe
rusqlite
serde / serde_json
zip
sha2
walkdir
GitHub Actions 跨平台构建

整体上，它不是一个复杂的大型系统，而是一个目标非常明确的桌面工具：让 Codex 本地历史迁移这件事变得可见、可控、可回滚。

总结

Codex History Migrator 适合这些用户：

想把 Codex 历史从旧电脑迁移到新电脑
经常切换不同 Codex 环境
修改过 model_provider 后发现历史分散
想整理、归档、选择性导出本地会话
希望用 GUI 完成迁移，而不是手动操作 SQLite 和 JSONL 文件

如果你也在重度使用 Codex，并且希望本地历史能更容易迁移和整理，可以试试这个项目。

项目地址：

https://github.com/qiufengawa/codex-history-migrator

Release 下载：