把代码与 Codex 会话同步到远程主机继续开发

用 Codex 这类编程 Agent 干活，最怕的不是换机器，而是换机器之后 Agent 失忆。SSH 配好、代码拷过去，听起来随时可以在远程主机上继续开发，但真正开工你会发现：Codex 的会话历史全部留在本地的 ~/.codex 目录里，远程一侧的 Agent 对你们之前聊过什么、改到哪里一无所知，只能从头再讲一遍需求。

有一个名为 sync-and-connect 的 Codex 技能包专门补上这一环，随包附带 sync.py 与 pull.py 两个脚本。它的核心主张是：代码和 Agent 记忆应当作为两类资产一起迁移，缺一不可。

一、三方同步：代码、记忆、交接

这套方案把「远程继续开发」拆成三件事：

1. 代码同步：rsync 增量传输项目目录到远程主机；
2. 记忆同步：把 ~/.codex 里的会话数据一并送过去，远程 Agent 因此"记得"你们做过什么；
3. 桌面端交接：生成一条 codex:// 深链，点开就能在 Codex 桌面应用里接管远程工作区。

前两件由 sync.py 一次完成，pull.py 负责反向搬回。整套流程只依赖本地 rsync 与 OpenSSH，远程主机不需要额外安装任何服务。

二、开工前的三样东西

• 远程主机的 SSH 别名已写入 ~/.ssh/config，裸敲 ssh 别名 能直接连上；
• 本地装有 rsync；
• 装好 Codex 桌面应用。

如果 SSH 还没配通，请先停下来配置 ~/.ssh/config，这套流程默认连接已就绪，不负责从零建连。

三、四步走完同步

第一步：收集两个输入

一是本地项目的绝对路径；二是远程目的地，写成 别名:远程目录 的形式。别名必须是 ~/.ssh/config 里已有的 Host；只给别名不给路径时，默认送到 ~/projects/项目名 下。

第二步：先跑 dry-run

python3 sync.py 本地项目 别名:远程目录 --dry-run

正式传输前务必先预览。dry-run 会告诉你有多少文件要移动、排除了什么，node_modules 或超大文件意外混进传输清单这类"惊喜"就靠这一步暴露。确认无误再继续。

第三步：正式同步

python3 sync.py 本地项目 别名:远程目录

同一条命令去掉 --dry-run。它会顺序执行两次 rsync：第一趟把项目代码送到远程目录，增量传输，排除 node_modules、.git 的 packfile 和各类构建产物；第二趟把 ~/.codex 的会话数据送到远程同名目录，包括会话历史、线程索引、命令历史和已安装技能，但绝不碰 auth.json 与 config.toml。跑完输出一份 JSON 摘要。

注意中途不要打断。经验法则是：第一趟失败就停下排查；只有第二趟失败也无妨，代码已经到位，只是远程 Agent 暂时没有记忆。

第四步：远程验证

ssh 别名 "ls 远程目录 | head -20 && ls ~/.codex/sessions/ | head -5"

远程目录为空或不存在，说明同步失败，回到第三步重来。

四、深链交接给桌面端

同步完成后，技能包会让你生成一条这样的 Markdown 链接：

[在 Codex 中打开远程目录](codex://settings/connections/ssh/add?name=别名&path=远程目录)

点开会直接进入 Codex 桌面应用的添加 SSH 主机流程，别名与路径都已预填。链接失效就手动操作：Codex App，Settings，Connections，Add SSH Host，选中别名与远程目录。此后在远程打开工作区，Agent 能接着本地的话头继续干活。

五、干完活，反向拉回

python3 pull.py 别名:远程目录 本地项目

在远程干完活想把成果带回家时，方向反过来即可。pull.py 把远程改过的代码与远程新建的会话一起拉回本地 ~/.codex。会话同步是追加式的，不会删除远端已有的对话，两边可以放心交替使用。

六、同步范围与两条红线

会同步的：项目源代码、.git 的 refs 与 HEAD（保留分支状态）、sessions/ 全部会话历史、session_index.jsonl 线程索引、history.jsonl 命令历史、AGENTS.md 项目级指令、已安装的 skills/。

被排除的：node_modules、.git/objects/pack、dist、build 等构建产物，.venv、__pycache__、日志与缓存，这些都可以再生，不值得传输。

两条红线值得记住：其一，auth.json 与 config.toml 是机器专属的敏感文件，任何方向都不会同步；其二，运行中的 SQLite 状态库不拷贝，在途数据复制出来容易损坏。

七、几点提醒

• rsync 是增量的，同步命令可以反复执行，只有变更过的文件会再传输；
• 远程主机若是不同的操作系统或 CPU 架构，项目里的编译产物在远端跑不起来，需要重新构建；
• 只给别名时默认送到 ~/projects/项目名，想换位置就写全 别名:路径。

结语

远程开发的门槛早已不是连通性，而是上下文的迁移。把 Agent 的会话历史当作和代码同等级别的资产来同步，是这套方案最值得借鉴的思路：换的是机器，不变的是记忆。