Codex Sync

在同一局域网的多台电脑之间同步 Codex 聊天记录和配置。提供命令行与内置 Web 界面。

快速开始

cargo build --release
./target/release/codex-sync init

编辑 ~/.config/codex-sync/config.toml，把 shared_key 改成一个随机长字符串；每台电脑使用相同密钥。随后运行：

./target/release/codex-sync serve

shared_key 至少需要 32 个字符。建议使用密码管理器生成的随机值；init 会在 Unix 系统将配置文件权限设为仅当前用户可读写。默认单文件上限为 256 MiB、单次清单上限为 100,000 个文件；可在配置中按需调整：

max_file_size_bytes = 268435456
max_files = 100000

打开 http://localhost:8787，在页面中输入共享密钥（仅保存于当前浏览器会话）。也可以使用命令行：

codex-sync peers
codex-sync pull 192.168.1.20:8787
codex-sync status

U 盘离线中转

在电脑 A 上导出（macOS 示例）：

codex-sync usb export /Volumes/MYUSB

把 U 盘插到电脑 B，查看并导入：

codex-sync usb list /Volumes/MYUSB
codex-sync usb import /Volumes/MYUSB

如果 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 推送快照：

codex-sync smb push /Volumes/codex-sync

电脑 B 查看并拉取：

codex-sync smb list /Volumes/codex-sync
codex-sync smb pull /Volumes/codex-sync

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 发布快照
codex-sync relay push /path/to/shared-folder

# 电脑 B 查看及获取
codex-sync relay list /path/to/shared-folder
codex-sync relay pull /path/to/shared-folder

例如使用 Syncthing：先让两台电脑同步同一个 CodexRelay 文件夹，再分别运行：

codex-sync relay push ~/Sync/CodexRelay
codex-sync relay pull ~/Sync/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-sync cc-switch status
codex-sync cc-switch merge

确认数量后，关闭 Codex 和 CC-Switch，再执行：

codex-sync cc-switch merge --apply

合并会同时更新会话 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 命令。先预览：

codex-sync history status
codex-sync history merge

确认待归并数量后执行：

codex-sync history merge --apply

该命令会把 state_5.sqlite 的线程归属和会话 JSONL 的 session_meta 统一到当前 config.toml 中的 model_provider / model，并补齐 session_index.jsonl 缺少的侧栏条目。使用 ChatGPT 登录且没有显式配置 model_provider 时，采用 Codex 内置的 openai provider。修改前会在线备份数据库、侧栏索引和会话文件，因此 Codex 正在运行时也会等待数据库写锁；若仍繁忙则安全失败，不会跳过备份强行写入。

手动备份和恢复：

codex-sync history backup
codex-sync history restore ~/.codex/codex-sync-backups/history-merge-时间戳
codex-sync history restore ~/.codex/codex-sync-backups/history-merge-时间戳 --apply

恢复默认也只预览，并且正式恢复前会再创建一份 pre-history-restore 安全备份。本功能的设计参考了 GODGOD126/codex-history-sync-tool，并在 Rust CLI 中扩展为 macOS、Linux 和 Windows 通用实现。

默认同步方向

“把本机记录同步到某个目标”始终表示单向的“本机 → 目标”。目标端只作为写入位置，不会自动读取、下载或合并目标端已有的 Codex 记录。只有明确执行 pull、import 或提出从远端恢复时，才会把远端数据带回本机。

SSH 单向同步并合并

本机与远端都安装 codex-sync 后，只需运行：

codex-sync ssh push lty

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/ssh-import-时间戳。
• 合并完成后自动删除两端临时传输包。

如果远端尚未安装：

ssh lty 'cargo install codex-sync'

同步策略与安全

• 默认同步 ~/.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 开源。