文章目录
- 1. 它解决了什么问题？
- 2. 为什么不直接同步整个`.codex`目录？
- 3. 我比较看重的几个特性
- 3.1 应用前先看计划
- 3.2 不随意覆盖本机文件
- 3.3 同时支持通用配置与平台差异
- 3.4 写入失败可以恢复
- 3.5 边界明确
- 4. 快速开始
- 5. 它适合谁？
- 6. 当前状态
- 7. 总结
如果你只在一台电脑上使用Codex，配置通常不是一个问题。
但使用一段时间之后，情况会慢慢发生变化：你配置了常用的MCP Server，安装了插件，针对不同任务维护了Named Profiles，又积累了一批自己的Skills。此时换到另一台电脑，面对一个“全新”的Codex，往往需要重新寻找配置、修改路径、安装工具，再回忆一遍当初是怎么调好的。
更麻烦的是，macOS上的配置不能原样搬到Windows，服务器上的环境又和个人电脑不同。直接复制~/.codex看似省事，却可能把Token、OAuth状态、历史记录、缓存和本机路径一起带走；直接用Git覆盖配置，则可能破坏目标机器上原本正常工作的环境。
我想要的其实很简单：
维护一份自己的Codex配置，在macOS、Windows和Linux上都能使用；应用前可以先看改了什么，遇到本机修改不直接覆盖，隐私和运行时状态仍然留在本地。
为此，我开源了：codex-profile-sync。
它是一个面向Codex的跨平台配置同步工具，可以将一份私有、可移植的Codex Profile安全地应用到不同电脑。目前支持macOS、Windows和Linux。
项目地址：https://github.com/GreenLv/codex-profile-sync
当前状态：Alpha；最新版本见 GitHub Releases
1. 它解决了什么问题？
codex-profile-sync主要面向下面这类场景：
- 办公电脑和个人电脑都在使用Codex；
- 同时使用macOS、Windows或Linux；
- 已经维护了自己的MCP配置、插件偏好、Named Profiles或Skills；
- 希望用私有Git仓库保存个人配置，但不想把隐私数据一起上传；
- 不希望同步工具静默覆盖本机已有配置；
- 每次换电脑或重装环境，都不想从头配置一遍。
使用它之后，你只需要维护一份私有的Source Bundle。不同设备拉取这份Bundle后，先预览变更，再应用到本机即可。
私有Source Bundle │ ├────► macOS ├────► Windows └────► Linux其中既可以保存三端通用的配置，也可以单独保存不同操作系统上的路径和命令差异。
2. 为什么不直接同步整个.codex目录？
Codex的本地目录中，不只有我们主动编写的配置，还包含登录状态、会话、历史记录、日志、缓存、Memories以及其他机器生成内容。
这些数据并不适合被整体复制，更不适合直接提交到GitHub。
因此，codex-profile-sync将整个同步过程分成三层：
- 公开的同步引擎：也就是本项目本身，包含代码、文档与测试；
- 私有的Source Bundle：只保存你主动选择的可移植配置；
- 本机Codex状态：登录信息、历史记录、缓存等内容始终留在当前机器。
简单来说：
它不是把你的整个Codex目录上传到云端，而是只管理你明确指定的那部分配置。
目前可以同步的内容包括：
$CODEX_HOME/config.toml中明确声明的配置项；- 用于不同任务的Codex Named Profiles；
$HOME/.agents/skills下的用户Skills（可选，默认关闭）。
Token、OAuth状态、会话历史、日志、数据库、缓存、Memories和插件缓存等运行时数据，都不在管理范围内。
3. 我比较看重的几个特性
3.1 应用前先看计划
工具不会直接修改配置。每次同步都可以先运行plan，查看哪些内容将被创建、更新或删除，以及是否存在冲突。
codex-profile-sync plan--source"$HOME/private-codex-profile"对于配置同步，我更希望“先知道会发生什么”，而不是执行完成之后再检查有没有出问题。
3.2 不随意覆盖本机文件
如果目标机器上存在一个同名文件，但它并不属于当前Profile，工具会拒绝覆盖。
如果某个已同步文件后来被本机修改，下一次更新也会转为冲突，交给用户确认，而不是用源端版本静默替换。
3.3 同时支持通用配置与平台差异
macOS、Windows和Linux可以共享同一份通用配置，同时分别维护少量平台Overlay。
例如，一个MCP Server的配置逻辑三端相同，只有Python或可执行文件路径不同，那么只需要在平台配置中记录路径差异，不必维护三份完整配置。
3.4 写入失败可以恢复
应用配置时，已有文件会先备份，写入采用原子替换。若多文件应用中途失败，工具会尝试恢复已经修改的目标文件。
此外，符号链接、路径逃逸和受保护的Codex运行时配置也会被拒绝。
3.5 边界明确
codex-profile-sync只负责将已经存在于本机的Source Bundle应用到Codex环境。它不会自动执行git pull或git push，不会安装插件、完成MCP登录，也不会发起网络请求。
Git负责在设备间传递你的私有配置；codex-profile-sync负责安全地把这些配置应用到本机。两者的职责是分开的。
4. 快速开始
项目需要Python 3.11或更高版本。
首先从PyPI安装：
pipxinstallcodex-profile-sync或者使用uv：
uv toolinstallcodex-profile-sync然后，在公开引擎仓库之外创建自己的私有Source Bundle：
codex-profile-sync init"$HOME/private-codex-profile"根据需要修改其中的通用配置、平台配置、Profiles和Skills。修改完成后，依次执行：
codex-profile-sync plan--source"$HOME/private-codex-profile"codex-profile-sync apply--source"$HOME/private-codex-profile"codex-profile-sync doctor--source"$HOME/private-codex-profile"这三个命令分别用于：
plan：预览变化与冲突，不修改文件；apply：确认后应用配置；doctor：检查当前机器是否已经与Source Bundle保持一致。
如果希望在多台电脑间共享配置，可以自行将private-codex-profile放入一个私有Git仓库。在另一台机器上拉取后，重新运行plan → apply → doctor即可。
关于Source Bundle格式、平台Overlay和配置允许列表的完整说明，可以参见项目的中文README。
5. 它适合谁？
如果你刚刚开始使用Codex，只有一台电脑和几行简单配置，那么可能暂时不需要这个项目。
但如果你已经开始积累自己的Codex工作流，尤其是下面这些内容：
- 多个MCP Server；
- 针对不同任务的Named Profiles；
- 自己编写或长期维护的Skills；
- macOS、Windows和Linux之间不同的命令路径；
- 一套希望长期保存、持续演进的个人Codex环境；
那么codex-profile-sync可以帮你把这些内容从“散落在不同电脑上的手工配置”，变成一套可以审查、迁移和恢复的个人配置资产。
6. 当前状态
codex-profile-sync目前处于Alpha阶段，已发布到PyPI，并已经实现基础配置、Named Profiles和可选Skills的跨平台应用，以及变更预览、冲突检测、备份与失败恢复。
Source Bundle Schema已经进行版本化。在1.0之前，CLI还可能继续增加安全且向后兼容的检查。
我希望这个项目保持轻量和克制：不尝试接管完整的Codex运行时，只把“个人配置如何安全地跨设备复用”这件事做好。
7. 总结
codex-profile-sync的核心思路可以概括为一句话：
使用公开的同步引擎，管理一份私有的Codex Source Bundle，只将用户明确声明的配置安全地应用到当前机器。
如果你也在多台设备上使用Codex，或者已经积累了自己的Profiles、MCP配置与Skills，欢迎试用：
GitHub：GreenLv/codex-profile-sync
如果这个项目对你有帮助，欢迎点一个Star、提交Issue或参与改进。也欢迎分享你在多设备使用Codex时遇到的问题和希望支持的场景。
