一套Codex配置，多台电脑安全复用：codex-profile-sync开源

如果你只在一台电脑上使用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将整个同步过程分成三层：

1. 公开的同步引擎：也就是本项目本身，包含代码、文档与测试；
2. 私有的Source Bundle：只保存你主动选择的可移植配置；
3. 本机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时遇到的问题和希望支持的场景。