Codex Sync 跨平台同步工具
在 Windows 和 macOS 之间频繁切换，最令人困扰的莫过于 Codex 对话记录无法自动同步。这款工具专为解决此痛点而生——借助 GitHub 私有仓库与第三方 API，将会话数据、规则、技能等全部迁移至云端。您在一台设备上执行推送，另一台设备拉取即可完成同步，路径自动转换，几乎无需人工干预。若安装过程中遇到疑问，随时咨询身边的 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. 首次推送数据
先关闭 Codex 编辑器，然后执行以下命令：
python ~/.codex/sync.py push
脚本将自动初始化同步仓库，将会话数据安全推送至远程。
4. 在另一台设备拉取数据
python ~/.codex/sync.py pull
命令详解
| 命令 | 功能说明 |
|---|---|
| push | 将会话文件与配置数据推送至 GitHub（自动执行路径转换） |
| pull | 从 GitHub 拉取最新数据至本地 ~/.codex/ 目录 |
| status | 查看本地与远程会话数量对比情况 |
后台自动监控（可选功能）
觉得手动操作不够便捷？codex-watch.py 可运行于后台，自动完成以下任务：
- Codex 启动时自动拉取最新数据
- 会话文件发生变化后，闲置 60 秒自动推送更新
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中排除，无需担心敏感信息泄露。
