Codex通过第三方API实现跨平台对话同步

Codex Sync

在 Windows 和 macOS 之间频繁切换，最令人头疼的就是 Codex 对话记录无法跨平台同步。这个工具正是为此而生——通过 GitHub 私有仓库，配合第三方 API，将会话数据、规则、技能等全部迁移。在一台设备上执行 push，另一台设备上执行 pull，路径自动转换，几乎无需手动干预。如果安装过程中遇到问题，随时咨询身边的 AI 即可解决。

工作原理

  Windows                         macOS
┌──────────┐                  ┌──────────┐
│ ~/.codex │ ── push ──> GitHub <── pull ── │ ~/.codex │
│ sessions │                  │ sessions │
│ rules/   │                  │ rules/   │
│ skills/  │                  │ skills/  │
│ ...      │                  │ ...      │
└──────────┘                  └──────────┘

同步范围非常直接：.gitignore 中未排除的所有文件都会被同步，包括 sessions、rules、skills、plugins 等。但有几类文件完全不会涉及——auth.json、config.toml 这类敏感文件，以及 *.sqlite 等大型文件，都在黑名单中。

跨平台路径如何处理？借助 pathmap.conf。例如，Windows 下的 D:\working 与 macOS 下的 /Users/.../working，工具会自动进行转换，确保会话文件中的项目路径不会混乱。

快速开始

1. 环境要求

• Python 3.8+
• Git
• pip install pathspec（如需后台监控，还需安装 pip install watchdog）
• 一个用于存放同步数据的 GitHub 私有仓库（建议命名为 codex-sync）

2. 一次性配置（两台设备均需执行）

# 将本仓库克隆到 ~/.codex/
cd ~/.codex
git clone https://github.com/YOUR_USERNAME/codex-sync-tools.git tools
# 或直接复制以下文件：
#   sync.py, codex-watch.py, pathmap.conf.example, home.gitignore

# 复制并配置 gitignore，将不想同步的文件或文件夹添加进去
.gitignore

# 配置路径映射
cp pathmap.conf.example pathmap.conf
# 编辑 pathmap.conf，填写你的项目路径

# 编辑 sync.py：将 SYNC_REPO 改为你的私有同步仓库地址

3. 首次 Push

先关闭 Codex，然后执行：

python ~/.codex/sync.py push

脚本会自动初始化同步仓库，将会话数据推送至远程。

4. 在另一台设备上 Pull

python ~/.codex/sync.py pull

命令

命令	作用
push	将会话和文件复制到 GitHub（自动路径转换）
pull	从 GitHub 拉取到本地 ~/.codex/
status	查看本地与远程会话数量对比

后台监控（可选）

如果觉得手动操作繁琐，codex-watch.py 可以后台运行，自动完成以下操作：

• Codex 启动时自动 pull
• 会话文件变更后闲置 60 秒自动 push

pip install watchdog
python ~/.codex/codex-watch.py

Windows 上：将 codex-watch.vbs（请先修改内部路径）放入 shell:startup。macOS 上：通过 launchd 启动。

文件说明

文件	用途
sync.py	主同步脚本（push/pull/status）
codex-watch.py	后台自动同步监控（可选）
codex-watch.vbs	Windows 静默启动器
pathmap.conf.example	跨平台路径映射模板
home.gitignore	~/.codex/ 的 .gitignore 模板

路径映射

pathmap.conf 用于定义 Windows 和 macOS 之间的项目路径对应关系，格式如下：

# name = WindowsPath | macOSPath
working = D:\working | /Users/name/working
learning = C:\learning | /Users/name/learning

只有在此处列出的项目才会触发路径转换，与项目无关的对话不受影响。

注意事项

• push/pull 前务必关闭 Codex，避免文件锁冲突。本地使用期间，打开 Codex 不影响正常使用，但不可同时进行对话，否则可能导致记录丢失。
• 确保已安装 watchdog、pathspec 等脚本依赖的库，否则代码无法正常运行。
• 同步仓库必须设为私有——你的对话数据仅属于你自己。
• auth.json、config.toml 以及 SQLite 数据库已包含在 .gitignore 中，无需担心泄露。