Worktrees 与 Handoff

Worktree 是同一 Git 仓库的另一个 checkout。文件副本独立，提交与分支元数据共享，适合让多个聊天分别工作。项目必须属于 Git 仓库；手机只是控制连接主机，worktree 不在手机上执行。

创建隔离任务

1. 在桌面应用新聊天的输入框下选择 Worktree。
2. 选择起始分支；也可选择包含当前未提交改动的起始状态。
3. 按需选择本地环境运行初始化脚本。
4. 发送任务，Codex 建立默认处于 detached HEAD 的 checkout。

可以留在 worktree 验证，也可以用 Hand off 把聊天和代码移到 Local。需要保留为分支时，在聊天标题栏选择 Create branch here。

避免分支占用冲突

Git 不允许同一分支同时在两个 worktree checkout。若出现 already used by worktree，检查该分支在哪个 checkout 使用；不要直接重复 checkout。希望回到本地主目录继续时，可使用 Handoff。

同一聊天后续再交回 Worktree，会回到关联的后台环境。一般情况下，Git 忽略文件不随 Git 操作移动。

复制必要的忽略文件

本地托管 worktree 可以在仓库根的 .worktreeinclude 中列出需复制的忽略文件或 .gitignore 风格模式，例如：

.env
.env.local
config/secrets.json

只复制既被 Git 忽略、又匹配列表的文件；不应列入已跟踪文件。Codex 跳过源符号链接，不覆盖新 checkout 中已有文件。被忽略的 AGENTS.override.md 会自动复制，无需列入。

这项行为限本地桌面应用创建的托管 worktree，不适用于远程 worktree 或自己用 Git 创建的 worktree。复制本地配置时要确认它确实应供后台任务使用。

位置、清理与恢复

默认根目录是 $CODEX_HOME/worktrees，可以在 Settings > Worktrees > Worktree root 修改。官方默认保留最近 15 个托管 worktree，可调整数量或关闭自动删除。

关联置顶聊天、仍在运行的聊天或永久 worktree 不会自动删除。归档关联聊天或超出保留数量会触发托管 worktree 清理；删除前保存快照，再次打开聊天时可恢复。永久 worktree 作为独立项目保留，不随聊天归档自动删除。