Codex Sync
在同一局域网的多台电脑之间同步 Codex 聊天记录和配置。提供命令行与内置 Web 界面。
架构
同步能力分为“通用核心、Codex 语义合并、传输适配器”三层：
HTTP / Web ───────┐
USB / SMB / Relay ├─ SnapshotSource ─ sync::core
│ ├─ 清单、路径与哈希校验
SSH ──────────────┴─ 安全传输包 ──────┼─ 原子读写与冲突策略
└─ sync::codex
├─ rollout 增量去重
├─ SQLite 合并
└─ session_index 修复
sync::core是唯一的文件级同步基础实现。Web/HTTP 只负责网络读取，USB、SMB 和 Relay 只负责目录读写；清单验证、增量判断、冲突保留、哈希验证和原子落盘全部复用核心逻辑。sync::codex是唯一的 Codex 数据语义实现。SSH 只负责调用系统ssh/scp传输安全包，rollout、SQLite 和侧栏索引的合并由该模块统一完成。SnapshotSource是传输来源的 Rust trait。新增 S3、对象存储或其他只读来源时，只需为新类型实现这个 trait 的manifest与read方法；新增共享目录类型可直接复用现有目录适配器。
源码采用 Rust 2018+ 的模块布局：sync.rs/sync/、cli.rs/cli/ 由同名文件声明同名目录中的子模块，不使用 mod.rs。lib.rs 暴露可复用库，main.rs 只负责启动 CLI。
这样传输协议不再各自维护一套同步规则，安全校验和合并行为也不会随适配器增加而分叉。
快速开始
编辑 ~/.config/codex-sync/config.toml，把 shared_key 改成一个随机长字符串；每台电脑使用相同密钥。随后运行：
shared_key 至少需要 32 个字符。建议使用密码管理器生成的随机值；init 会在 Unix 系统将配置文件权限设为仅当前用户可读写。默认单文件上限为 256 MiB、单次清单上限为 100,000 个文件；可在配置中按需调整：
= 268435456
= 100000
打开 http://localhost:8787，在页面中输入共享密钥（仅保存于当前浏览器会话）。也可以使用命令行：
U 盘离线中转
在电脑 A 上导出（macOS 示例）：
把 U 盘插到电脑 B，查看并导入：
如果 U 盘中有多台电脑的快照，usb list 会显示每个快照的具体目录，导入时指定该目录即可。导入会验证 BLAKE3 哈希；同名但内容不同的文件默认保存为冲突副本。需要明确覆盖时使用 usb import PATH --overwrite。
SMB 服务器中转
Codex Sync 使用操作系统已经挂载的 SMB 目录，不保存服务器用户名或密码。先通过系统连接共享：
- macOS：访达 → 前往 → 连接服务器，输入
smb://服务器/codex-sync，通常挂载到/Volumes/codex-sync。 - Windows：在资源管理器映射网络驱动器，例如
Z:。 - Linux：用桌面文件管理器挂载，或将共享挂载到
/mnt/codex-sync。
电脑 A 推送快照：
电脑 B 查看并拉取：
Windows 示例：
codex-sync.exe smb push Z:\
codex-sync.exe smb pull Z:\
共享中有多个设备快照时，先通过 smb list 找到目标快照的完整路径，再将它传给 smb pull。默认保留冲突副本；明确覆盖时添加 --overwrite。SMB 快照和 U 盘快照使用相同的开放目录格式，可以相互复制。
其他中转方式
relay 支持任何在操作系统中表现为普通目录的中转服务，包括：
- NFS、AFP 或 NAS 挂载目录
- WebDAV 挂载盘
- Syncthing、Resilio Sync 等点对点同步目录
- Dropbox、OneDrive、iCloud Drive、Google Drive 等桌面同步目录
- 虚拟机共享目录、远程开发共享目录
通用用法：
# 电脑 A 发布快照
# 电脑 B 查看及获取
例如使用 Syncthing：先让两台电脑同步同一个 CodexRelay 文件夹，再分别运行：
例如使用 Windows OneDrive：
codex-sync.exe relay push "$env:OneDrive\CodexRelay"
codex-sync.exe relay pull "$env:OneDrive\CodexRelay"
使用云同步目录时，请等待云盘客户端完成上传或下载后再执行 pull。清单采用最后写入的原子替换方式，未完成的快照不会被识别为可导入快照。
合并 CC-Switch 多账号记录
Codex Sync 可以把本机 CC-Switch 不同供应商产生的历史记录统一归入当前登录的 Codex 账号。先预览：
确认数量后，关闭 Codex 和 CC-Switch，再执行：
合并会同时更新会话 JSONL 的 model_provider 和 state_5.sqlite 的记录桶。执行前自动备份到 ~/.codex/codex-sync-backups/cc-switch-merge-时间戳，该目录默认不会参与设备同步。此操作不读取、复制或修改 API Key、Token、auth.json 和供应商认证配置。
修复本机多 provider / model 历史
如果切换 API、provider、模型或登录方式后，本机历史文件还在但 Codex 侧栏不再显示，可以使用不依赖 CC-Switch 的 history 命令。先预览：
history doctor 是只读诊断命令，会检查 SQLite quick_check、非法会话 JSONL、缺失或重复的 session_meta、孤立或缺失的 rollout、重复/缺失/残留的侧栏索引。它默认永远不修改数据。
只有侧栏索引存在可安全重建的问题时，才可执行：
普通 --apply 不修改 SQLite、rollout 或 provider/model，只重建 session_index.jsonl。命令持有 SQLite 写锁，先保存原索引，在同目录写入并 fsync 临时文件后原子替换，随即复检；任何错误都会原子恢复原索引。非法 JSONL 和重复 session_meta 只会报告，不会被冒险自动修改。
缺失 rollout 已经在备份中定位并人工确认时，可以显式恢复：
恢复前会验证来源是普通文件、大小受限、每行 JSON 合法、恰好包含一条 session_meta、线程 ID 和文件名均与数据库中缺失的 rollout_path 一致，并拒绝目录穿越或符号链接。目标 rollout 与索引分别使用原子替换，失败时删除新目标并恢复原索引。正式执行前仍建议完全退出 Codex 和 CC-Switch，避免应用在修复完成后用内存中的旧状态再次覆盖索引。
对于已经停止写入、但混入多条 session_meta 的单个 rollout，可逐个执行：
命令只保留线程数据库中该 rollout_path 对应 ID 的元数据行，其他事件行按原字节顺序保留。每次只处理一个文件，修改前保存原文件，提交前重新比较源字节，使用同步落盘后的原子替换；验证或提交失败时恢复原文件。正在写入的当前任务必须等 Codex 完全退出后再处理。
确认待归并数量后执行：
该命令会把 state_5.sqlite 的线程归属和会话 JSONL 的 session_meta 统一到当前 config.toml 中的 model_provider / model，并补齐 session_index.jsonl 缺少的侧栏条目。使用 ChatGPT 登录且没有显式配置 model_provider 时，采用 Codex 内置的 openai provider。修改前会在线备份数据库、侧栏索引和会话文件，因此 Codex 正在运行时也会等待数据库写锁；若仍繁忙则安全失败，不会跳过备份强行写入。
手动备份和恢复：
恢复默认也只预览，并且正式恢复前会再创建一份 pre-history-restore 安全备份。本功能的设计参考了 GODGOD126/codex-history-sync-tool，并在 Rust CLI 中扩展为 macOS、Linux 和 Windows 通用实现。
默认同步方向
“把本机记录同步到某个目标”始终表示单向的“本机 → 目标”。目标端只作为写入位置，不会自动读取、下载或合并目标端已有的 Codex 记录。只有明确执行 pull、import 或提出从远端恢复时，才会把远端数据带回本机。
SSH 单向同步并合并
本机与远端都安装 codex-sync 后，只需运行：
lty 可以是 ~/.ssh/config 中的主机别名，也可以是 user@host。该命令固定执行“本机 → 远端”：
- 只从本机
~/.codex提取会话、归档会话、附件、索引和 SQLite 线程记录。 - 不读取或下载远端已有聊天记录。
- 使用系统
ssh/scp，沿用现有 SSH Agent、密钥和主机配置。 - 上传后由远端
codex-sync校验 BLAKE3 清单，再合并进远端~/.codex。 - 默认进行增量合并：只追加本机新增记录，保留远端已有记录，且绝不把远端记录下载回本机。
- 同名 JSONL 会话会按事件行去重合并；同名附件或二进制文件仍保留远端版本并报告冲突。
- 每个 rollout 始终只保留一条
session_meta；数据库合并后按线程 ID 自动重建session_index.jsonl，避免记录已入库但侧栏缺失。 - 仅在明确需要让远端完全等同于本机时，使用
codex-sync ssh push HOST --mirror；远端独有记录会先备份再移出活动历史。 - 导入的会话自动归入远端当前
model_provider。 - 修改前备份远端数据库和索引到
~/.codex/codex-sync-backups/sync-import-时间戳。 - 合并完成后自动删除两端临时传输包。
如果远端尚未安装：
同步策略与安全
- 默认同步
~/.codex，排除auth.json、凭据、日志、缓存和临时文件。 - 所有 API（包括状态、发现和 Web 拉取）均要求共享密钥认证；密钥不会经节点发现广播或写入 U 盘快照。
- LAN 与离线导入均校验清单路径、文件数量、文件大小和 BLAKE3 哈希；下载写入使用同步落盘后的原子替换，并拒绝写入符号链接。
- SMB 账号和密码由操作系统管理，不会写入 Codex Sync 配置或快照。
- 默认只拉取。遇到同名但内容不同的文件时，远端版本保存为
.conflict-节点名，不会覆盖本地内容。 pull --overwrite会覆盖不同内容的本地文件，使用前请自行备份。- 服务默认监听
0.0.0.0:8787，请只在可信局域网使用，并通过系统防火墙限制访问。当前 LAN API 使用共享密钥而非 TLS；跨不可信网络时请使用 SSH、VPN 或受保护的中转目录。
当前范围
项目提供生产使用的安全基线：受限数据范围、配置权限、端到端完整性校验、冲突保留、原子发布、SSH 备份/合并，以及 macOS、Linux、Windows CI 门禁。自动后台双向同步、设备审批、TLS 终止与系统服务安装仍需按部署环境单独配置。
许可证
本项目采用 MIT License 开源。