一个面向 Windows 的 Codex 数据备份、恢复和异机合并工具。它可以把 Codex 用户数据、项目文件和会话分别打包，并在更换电脑或 Windows 用户名后进行路径映射、版本比较和项目—会话关联对账。
Important
这是社区维护的非官方工具，与 OpenAI 无隶属或背书关系。Codex 的内部数据结构可能随版本变化；正式还原前请先预演，并保留原始备份。
程序启动后提供两个入口：
- 备份 / 一键还原
- 备份本机 Codex 数据、常见应用数据、项目目录及可选配置。
- 每个数据项独立生成 ZIP，并写入带 SHA256 的
manifest.json。 - 适合原机恢复，或目标路径完全相同的 Windows 环境。
- 项目—会话合并 / 异机还原
- 把另一台 Windows 电脑生成的备份映射到当前 Windows 用户。
- 普通项目文件按版本比较；较新的本机文件不会被旧备份覆盖。
- Codex 会话按稳定会话 ID 和内容追加关系合并，而不是仅比较修改时间。
- 对
state_*.sqlite中的会话索引进行受保护的合并和路径重写。
本项目仅支持 Windows 10/11 x64，不提供其他操作系统版本。
- 备份写入前不会修改源文件。
- 无法读取的锁定文件会记录并跳过，不会导致整个备份直接丢弃。
- 还原前会校验每个 ZIP 的 SHA256。
- 一键还原会先把现有目标移到单独的预恢复保护目录。
- 只有全部现有数据保护成功后才开始解压。
- 中途失败会尽量回滚已经移动或写入的数据。
- 支持 Windows 扩展长路径，避免深层项目和 Git 引用触发
WinError 206。 - 异机还原默认启用 Dry Run，只生成计划和报告，不写入文件。
- 覆盖普通文件前可保存本机旧版本。
- 会话文件或会话索引合并失败时会回滚本次会话写入。
- 数据库表结构不兼容时安全停止，不猜测未知字段。
生成的备份可能包含：
- Codex 登录状态、配置和会话历史；
- 项目源代码、项目名称和绝对路径；
- Git 用户配置；
- SSH 配置和私钥（仅在手动启用 SSH 备份时）；
- 主机名、Windows 用户目录和文件元数据。
不要把备份目录、ZIP、manifest.json、配置 JSON、SQLite、JSONL 或对账报告上传到公开仓库、网盘公开链接或公开 Issue。 本仓库的 .gitignore 会排除常见敏感文件，但不能代替人工检查。
直接运行发布版：
- Windows 10 或 Windows 11，64 位；
- 对要读取和写入的目录拥有权限；
- 正式恢复或会话合并时完全退出 Codex。
从源码运行：
- Python 3.11 或更高版本；
- Python 安装中包含 Tkinter（Windows 官方 Python 安装包默认包含）；
- 运行功能只使用 Python 标准库。
构建 EXE 还需要 PyInstaller。
- 在 GitHub 的 Releases 页面下载
CodexDataTool.exe。 - 可选：使用发布说明中的 SHA256 校验文件。
- 把 EXE 放在普通工具目录中，不要放进准备恢复的项目目录、
.codex或 AppData 目标目录。 - 双击运行。
程序目前没有代码签名证书，Windows SmartScreen 可能显示“未知发布者”。请只从本仓库 Release 下载，并核对 SHA256。
git clone https://github.com/MushGrowth/codex-data-tool-windows.git
cd codex-data-tool-windows
python .\codex_migration_tool.py也可以双击 run_windows.bat。
- 完全退出 Codex。若任务管理器仍有
Codex.exe，等待其结束。 - 启动程序并选择 备份 / 一键还原。
- 在 Backup 页检查自动识别的项目：
%USERPROFILE%\.codex%APPDATA%\Codex%LOCALAPPDATA%\Codex%APPDATA%\OpenAI%LOCALAPPDATA%\OpenAI%USERPROFILE%\Documents\Codex- Git 配置和 SSH 目录默认不启用。
- 使用“添加”把其他项目目录加入列表，例如
D:\Projects\ExampleProject。 - 选择备份根目录。建议使用空间充足且不在项目内部的位置。
- 点击 Start Full Backup。
- 等待日志显示完成，并检查是否出现“跳过锁定文件”。
输出目录类似：
codex-full-backup-YYYYMMDD-HHMMSS\
├─ manifest.json
├─ 01-Codex user data (.codex).zip
├─ 02-Codex AppData Roaming.zip
└─ ...
必须保留整个目录。不能只复制 manifest.json 或其中一个 ZIP。
一键还原适合恢复到备份记录的原始 Windows 路径。更换了电脑或 Windows 用户名时，请使用“项目—会话合并 / 异机还原”。
- 把 EXE 放到所有恢复目标之外。
- 完全退出 Codex。
- 进入 备份 / 一键还原，切换到 Restore 页。
- 选择完整备份目录并点击 Inspect。
- 将“还原前备份目录”设置到短且独立的位置，例如
C:\CodexRestorePreBackups。 - 检查清单后点击 One-click Restore。
还原过程会先保护现有数据，再解压备份。不要把“还原前备份目录”设置到任何还原目标内部，也不要在任务运行时关闭程序或断电。
适用于：
- 从另一台 Windows 电脑迁移到本机；
- 两台电脑的 Windows 用户名不同；
- 本机和备份两边都有更新，需要保留更新的一方；
- 需要把项目文件与其 Codex 会话一起对账。
推荐流程：
- 在旧电脑上完全退出 Codex 并生成完整备份。
- 把整个备份目录复制到新电脑，可使用移动硬盘、SMB 共享或远程桌面磁盘重定向。
- 在新电脑启动工具，选择 项目—会话合并 / 异机还原。
- 选择备份目录并点击 读取并生成映射。
- 逐项检查“备份中的原路径 → 本机目标路径”。标准 Windows 用户目录会自动映射；自定义项目必须人工确认。
- 不需要恢复的项目可取消启用。SSH 数据默认应保持禁用，除非确实需要迁移。
- 保持 Dry Run，先执行预演。
- 检查界面中的项目—会话对账表、日志和
cross_machine_restore_reports。 - 确认结果后，完全退出 Codex，关闭 Dry Run，再正式执行。
- 完成后启动 Codex；如项目路径发生变化，在 Codex 中重新打开本机项目目录。
正式执行成功后，表头会从“待还原文件、待合并会话”自动变成“已还原文件、已合并会话”。两个功能页都可以返回主界面；任务运行期间返回按钮会暂时禁用。
时间容差为 2 秒：
| 情况 | 处理方式 |
|---|---|
| 本机不存在 | 从备份还原 |
| 备份修改时间明显更新 | 备份覆盖本机；可先保护旧文件 |
| 本机修改时间明显更新 | 保留本机，不使用旧备份覆盖 |
| 时间接近且内容完全相同 | 跳过重复文件 |
| 时间接近但内容不同 | 保留本机，并把备份分支保存到 file-conflicts |
文件大小不能证明新旧，所以时间接近时会逐字节比较内容。
普通文件的修改时间规则不适用于会话。工具会读取会话 JSONL 文件名中的稳定会话 ID，并比较完整内容：
| 情况 | 处理方式 |
|---|---|
| 备份独有会话 | 合并到本机 |
| 双方内容完全相同 | 只保留一份 |
| 本机会话是备份会话的完整前缀 | 备份是在同一历史上继续追加，使用备份版本 |
| 备份会话是本机会话的完整前缀 | 本机版本更新，保留本机 |
| 同一会话 ID 但双方分叉 | 不自动覆盖；保留本机，并保存备份分支等待人工确认 |
会话通过 SQLite threads.cwd 关联到映射后的项目路径。正式执行时会更新本机 state_*.sqlite 中兼容的 threads 索引，并把 cwd 和 rollout_path 重写为本机目标路径。JSONL 内的历史记录保持不变。
异机还原会在本机生成 cross_machine_restore_reports，常见文件包括：
cross-machine-restore-*.csv：逐文件决定；session-reconciliation-*.csv：逐会话决定；project-session-summary-*.csv：按项目汇总文件和会话结果；cross-machine-summary-*.json：本次执行的汇总信息。
这些报告可能包含项目名、会话 ID 和绝对路径，只用于本地核查，不应公开上传。
Codex、SQLite 或系统进程正在使用文件时，Windows 可能返回 Permission denied、共享冲突或访问被拒绝。备份会跳过判定为锁定/瞬态的单个文件并在日志和清单中记录。
- 少量缓存、临时文件或 WAL/SHM 被跳过，通常不影响项目源码。
- 会话数据库或关键会话文件被跳过时，备份可能不完整。
- 最稳妥的做法是完全退出 Codex 后重新备份，直到关键数据不再被跳过。
使用最新版工具，并把预恢复保护目录设为短路径，例如 C:\CodexRestorePreBackups。不要把 EXE 放在准备恢复的项目目录内。
通常是文件仍被 Codex、杀毒软件、同步盘或索引服务占用。先退出 Codex，必要时在任务管理器确认进程结束，然后重试。请根据日志中的具体文件判断是否只是缓存，不能只看错误编号。
异机还原不会用明显更旧的备份覆盖本机文件。一键还原则按原机完整恢复处理，不做逐文件的新旧合并。
两个分支可能都包含独有内容，修改时间和大小都不足以证明哪一份正确。工具会保留双方，避免静默丢失会话。
可以。在异机还原映射表中只启用需要的项目，并先 Dry Run。与该项目关联的会话会在对账表中单独显示。
在 Windows PowerShell 中执行：
python -m pip install --upgrade pyinstaller
.\build_windows.ps1输出文件：
dist\CodexDataTool.exe
建议从一个不含个人配置、报告和备份数据的干净源码目录构建。发布前计算 SHA256：
Get-FileHash .\dist\CodexDataTool.exe -Algorithm SHA256codex_migration_tool.py # 主界面和语言选择
codex_backup_restore_tool.py # 完整备份与一键还原
codex_cross_machine_restore.py # 异机文件对账和界面
codex_session_reconcile.py # 会话及 SQLite 索引合并
windows_paths.py # Windows 路径映射工具
localization.py # 中英文界面文本
CodexDataTool.spec # PyInstaller 构建配置
build_windows.ps1 # Windows 构建脚本
run_windows.bat # 源码启动脚本
提交前至少执行：
python -m py_compile .\windows_paths.py .\codex_backup_restore_tool.py .\codex_session_reconcile.py .\codex_cross_machine_restore.py .\codex_migration_tool.py .\localization.py
.\build_windows.ps1涉及还原逻辑的改动应使用临时目录和虚构数据测试，不要直接拿唯一一份真实项目或会话做首次验证。
- 仅支持 Windows 10/11 x64。
- 不是实时同步工具，不会连接远程电脑；备份目录需要先复制到本机可访问位置。
- 依赖 Codex 当前内部文件和 SQLite 结构；结构变化时工具会停止相关合并。
- 未提供自动解决分叉会话的策略。
- EXE 当前未进行商业代码签名。
- 工具无法保证恢复正在写入或已损坏的源文件。
项目使用 MIT License。你可以使用、修改和分发源码，但软件按现状提供，不附带数据恢复保证。进行重要迁移前，请保留至少一份独立、可验证的原始备份。