Codex做长任务时，经常会出现一种很现实的情况：

一开始只是想让它：

在当前项目里改几个文件。

所以直接从Local开始。

但任务做到一半以后，范围越来越大：

读取项目
↓
修改几个文件
↓
发现还要继续重构
↓
测试时间越来越长
↓
不想影响当前本地开发

这时候很多人会想到：

能不能把这个任务直接切到Worktree继续？

现在Codex已经支持 Handoff：把一个正在运行或已有上下文的Chat，在Local和Worktree之间移动，同时处理对应的Git工作状态。官方对Handoff的定义就是：在Local和Worktree之间移动Chat以及它的工作。

这听起来非常方便。

但真正使用时，最容易出现的误区是：

既然Thread过去了，那所有本地状态应该也完全一样。

其实不是。

真正需要分清的是：

Thread Context
≠
Git State
≠
Runtime Environment

Handoff真正考验的是：

Context、Code State和Environment能不能保持一致。

---

一、先理解：为什么做到一半才会想切Worktree？

Local最大的优势就是直接。

当前项目可能已经：

依赖安装完成；

环境变量配置好；

数据库正在运行；

本地服务全部启动。

所以小任务直接在Local做非常自然。

但任务一旦变长，就容易出现问题。

比如你自己同时还在：

修改 frontend

而Codex正在：

修改 backend

两边都在同一个Working Tree里。

如果Codex继续扩大修改范围，就可能出现：

未提交修改互相混在一起；

测试结果受到当前本地状态影响；

Agent修改文件与你手工修改冲突；

Diff越来越难Review。

Worktree的价值就在于：

把Agent执行状态从当前Local Workspace隔离出去。

Codex App本身就把Worktree用于多任务和多Agent隔离，让Agent可以在同一Repository的独立工作副本上推进任务，而不直接碰开发者当前的本地Git状态。

---

二、第一个坑：Thread过去了，不代表“你脑子里的本地状态”全过去了

这是最容易混淆的地方。

假设当前Local里存在：

Commit A
+
3个未提交修改
+
当前Thread Context

你告诉Codex：

切到Worktree继续。

很多人会自然理解成：

Local当前整个世界
↓
完整复制
↓
Worktree

但真正需要检查的是：

Git到底移动了哪些状态。

因为Thread里知道：

你为什么改；

当前Goal是什么；

已经做过哪些分析。

这些属于：

Conversation Context

而文件系统里真正存在什么，则属于：

Git / Workspace State

两者不是同一种状态。

所以Handoff以后第一件事，不应该是直接继续改代码。

而是先重新确认：

当前Branch
当前Revision
Working Tree状态
Changed Files

也就是说：

先确认Code State，再相信Conversation State。

---

三、为什么Context对了，代码仍然可能错？

假设Thread里已经形成结论：

auth.ts已经修改完成，下一步跑Integration Test。

但Worktree切换以后，如果对应代码状态没有你预期的修改，

Agent就可能出现一种很危险的情况：

Conversation:
“文件已经改过”

但：

Filesystem:
“文件还是旧的”

于是Agent继续执行测试，

失败以后又重新分析。

这时候你会感觉：

Codex怎么突然失忆了？

其实不一定是模型失忆。

更可能是：

Context State和Repository State发生了错位。

所以Handoff之后最好执行一次：

Context Check
+
Git Check

确认：

Agent认为自己做过什么，

和Repository实际存在什么，

完全一致。

---

四、第二个坑：未提交修改是Handoff里最危险的状态

如果Local非常干净：

git status
→ clean

Handoff通常更容易理解。

但真实开发环境经常不是这样。

可能存在：

modified: auth.ts
modified: user.ts
untracked: debug.log

其中有些文件是：

你自己改的。

有些是：

Codex刚改的。

还有些甚至只是：

临时调试文件。

这时候最关键的问题变成：

哪些修改属于这个Agent任务？

如果没有先划分清楚，

Handoff就可能把：

Task State

和：

Developer State

混在一起。

所以任务开始扩大时，真正稳的做法是先建立一个：

Handoff Boundary

例如明确：

Agent Changes:
auth.ts
session.ts

Human Changes:
frontend/login.tsx

先知道：

哪些修改必须跟任务走。

---

五、为什么Worktree特别适合“任务升级”场景？

Worktree真正有价值的场景，不只是：

一开始就知道我要并行。

还有一种就是：

Task Escalation。

例如最开始：

Small Bug

后来逐渐变成：

Bug
↓
Root Cause
↓
Cross-module Change
↓
Long-running Tests
↓
Refactor

这时候任务性质已经改变。

原来的Local执行方式可能不再合适。

于是Handoff相当于：

Local Exploration
↓
Task Becomes Larger
↓
Worktree Execution

这是一个非常合理的升级路径。

官方也明确支持手动在Worktree上启动Thread，以及通过Handoff在Local和Worktree之间移动已有Thread。

---

六、第三个坑：Worktree有代码，不代表有完整运行环境

这个坑和Git关系不大，

但实际最常见。

Local里项目能正常运行，是因为你可能已经有：

node_modules
.env
Python venv
Local DB
Generated Files
Cached Dependencies

创建新的Worktree以后，

最容易出现：

Code Exists

但：

Runtime Missing

于是Agent刚切过去就遇到：

依赖不存在；

环境变量找不到；

本地服务连不上；

测试不能跑。

很多人这时候会误判：

Handoff失败了。

实际上Thread和Git可能都正常。

失败的是：

Environment Recreation。

所以Handoff后第二层必须检查：

Git State
↓
Environment State

而不是只看文件有没有过去。

---

七、Environment为什么必须显式化？

如果一个项目只有在某个开发者电脑上：

“神奇地可以运行”

那它对Agent非常不友好。

真正适合Handoff的项目最好能够：

Setup
↓
Install
↓
Run
↓
Verify

都有明确入口。

例如：

./scripts/setup
./scripts/test
./scripts/verify

这样Agent切换Worktree以后，

可以自己恢复环境。

否则每一次Worktree都需要：

人工解释。

这实际上又回到了前面讲过的Harness Engineering：

环境越可重复，Agent越容易迁移。

---

八、第四个坑：Handoff以后继续使用旧假设

假设Local阶段Agent已经判断：

问题来自数据库查询。

于是切Worktree继续。

但切过去以后，代码Revision发生变化。

比如：

主Branch刚刚合并了一个新Commit。

现在Repository状态已经不是之前分析时的状态。

但Agent仍然按照旧结论继续：

Old Evidence
↓
New Code State

这非常危险。

因为很多Agent判断实际上都依赖：

Specific Revision

所以Handoff后最好确认：

Base Revision

是否仍然一致。

如果代码已经发生明显变化，

应该重新运行关键验证，

而不是直接继承所有旧结论。

---

九、Thread Context不是永远正确，它也有“有效版本”

可以把一个Agent判断理解成：

Decision
=
Context
+
Code State
+
Evidence

一旦Code State改变，

Decision本身就可能需要重新验证。

例如：

Local阶段：

Commit A
↓
Root Cause = X

Handoff以后：

Commit C

中间可能已经修改相关代码。

这时候不能简单认为：

Root Cause仍然 = X

所以真正稳的Thread Handoff应该有一个：

Context Revalidation。

不是把上下文全部推翻，

而是检查：

哪些结论仍然成立？

---

十、第五个坑：Handoff以后没有重新定义“谁拥有当前Workspace”

这是多Agent场景里最容易失控的一点。

例如：

Agent A原本在Local。

Handoff到Worktree以后继续工作。

但你自己仍然在Local修改同一个Feature。

同时Agent B又开了另一个Worktree。

现在系统可能变成：

Local
→ Human

Worktree A
→ Agent A

Worktree B
→ Agent B

这本身没有问题。

问题在于：

三边有没有修改相同Contract。

比如：

Human改API Schema；

Agent A改Service；

Agent B改SDK。

虽然Git状态隔离了，

但架构状态并没有隔离。

所以Worktree只能解决：

File Conflict

不能自动解决：

Decision Conflict

这也是为什么Worktree并不等于任务协调系统。

---

十一、Handoff以后必须重新明确Task Ownership

例如切到Worktree以后，可以重新建立：

Current Owner:
Agent A

Scope:
backend/auth

Do Not Touch:
frontend/
shared-sdk/

同时Local：

Human Scope:
frontend/login

如果还有第二个Agent：

Agent B Scope:
tests/

于是：

Workspace Isolation
+
Task Isolation

才真正成立。

只做前者不做后者，

还是会发生：

Semantic Conflict。

---

十二、一个比较稳的Local → Worktree Handoff流程

如果任务做到一半需要切，

我建议不要直接一句：

切过去继续。

而是按照下面顺序。

第一步：Checkpoint当前Goal

先让当前Thread明确：

Goal
Current Progress
Next Step
Remaining Risk

例如：

Goal:
修复登录401

Done:
已确认Token不是Root Cause

Current:
Session refresh逻辑

Next:
修改 + Integration Test

这样Context先被压缩一次。

---

第二步：检查Git状态

确认：

Branch
Revision
Modified Files
Untracked Files

特别是：

哪些修改是Agent产生的？

哪些是自己产生的？

---

第三步：执行Handoff

把Chat和任务移动到Worktree。

官方目前把这套过程称为Handoff，并由Codex处理把工作在Local和Worktree之间移动所需要的Git操作。

---

第四步：重新确认Worktree状态

不要马上改。

先检查：

Current Revision
Changed Files
Expected Diff

确保：

Conversation State
=
Code State

---

第五步：恢复Environment

检查：

Dependencies
Environment Variables
Services
Database
Test Setup

确保新的Worktree能真正运行。

---

第六步：重新跑一个最小Verification

比如：

Targeted Test

不要立刻跑整个Suite。

先确认：

当前代码和环境仍然符合之前的判断。

---

第七步：继续Long Task

确认无误以后才进入：

Implement
↓
Test
↓
Verify

---

十三、反向Handoff：Worktree做完以后回Local也有坑

Handoff并不只是：

Local
→
Worktree

还可能是：

Worktree
→
Local

例如Agent已经完成大部分工作。

你准备回到本地主Workspace：

手工调整；

最终Review；

Commit。

这时候同样需要先确认：

Local有没有在任务期间产生新的修改。

否则：

Worktree Changes
+
New Local Changes

合并时仍然可能产生冲突。

所以反向Handoff同样需要：

State Reconciliation

而不是：

Agent做完了，直接搬回来。

---

十四、为什么“Thread Handoff”比“重新开一个Worktree任务”更有价值？

最直接的原因是：

保留Decision History。

如果重新开一个完全新的Task，

Agent需要重新知道：

Bug是什么；

已经排除了什么；

为什么选择当前方案；

哪些方法已经失败。

例如：

Attempt 1
失败

Attempt 2
确认不是DB

Decision
修改Session

这些属于：

Task Context。

Handoff保留的价值就在这里：

不需要从零再建立任务理解。

官方也明确把Local ↔ Worktree Handoff描述成：移动一个Active Chat，同时保留它的Context。

所以：

New Thread
=
重新建立任务认知

而：

Handoff
=
保留认知，切换执行环境

这就是两者最大的差别。

---

十五、什么时候不要Handoff，直接开新Thread反而更好？

如果任务已经发生根本变化。

比如原来：

修Bug。

做到一半发现：

其实应该重写整个认证体系。

这时候即使可以Handoff，

也不一定应该继续沿用原Thread。

因为原Thread里大量Context都是：

Bug Fix Context

而新任务已经变成：

Architecture Rewrite

此时更合理的是：

New Goal
↓
New Thread
↓
Worktree

所以判断标准不是：

能不能Handoff？

而是：

Goal还是不是同一个Goal？

---

十六、什么时候最适合Handoff？

最适合的是：

Goal没变

仍然完成原来的任务。

Context仍然有价值

前面的调查、Decision都值得保留。

Execution Environment需要变化

比如：

从Local转到隔离环境。

Task Scope扩大

但没有变成另一项工程。

可以简单记成：

Same Goal
+
Different Workspace
=
Handoff

如果：

Different Goal

优先考虑：

New Thread

---

十七、Thread和Workspace应该被理解成两个独立维度

这是理解Codex长任务非常重要的一步。

很多人以前会把：

Chat
=
Workspace

绑定在一起。

但现在随着Worktree和Handoff出现，

更合理的结构是：

Thread
=
Task Context

Workspace
=
Execution State

于是同一个Thread可以：

Local
↓
Worktree

任务认知继续存在。

但执行环境发生变化。

这其实代表Agent工具正在从：

Chat-centric

逐渐走向：

Task-centric。

---

十八、Handoff真正解决的是“Task Continuity”

如果每一次换环境都需要：

重新解释；

重新定位；

重新分析，

Agent做长任务的效率会很低。

真正成熟的Agent系统需要：

Task
↓
Environment A
↓
Environment B
↓
Environment C

但：

Goal
Decision
Progress
Evidence

能够继续存在。

这就是：

Task Continuity。

而Handoff正是朝这个方向发展的能力。

---

十九、可以建立一份最小Handoff Checklist

以后Local做到一半想切Worktree，先检查这7项：

1. Goal

还是同一个任务吗？

2. Checkpoint

当前做到哪里？

3. Git State

有哪些未提交修改？

4. Ownership

哪些改动属于Agent，哪些属于自己？

5. Revision

切换前后代码版本是否一致？

6. Environment

新Worktree能不能运行？

7. Verification

Handoff后有没有重新验证关键假设？

完整链路：

Checkpoint
↓
Git State
↓
Handoff
↓
State Check
↓
Environment
↓
Verification
↓
Continue

比一句：

切过去继续。

可靠得多。

---

二十、真正成熟的Agent工程，不应该把Workspace当成“聊天附件”

随着Codex支持多个Agent、独立Thread、Worktree以及Handoff，Workspace正在变成真正的：

Execution Resource。

Codex App本身已经把不同Agent放在独立Thread中，并利用Worktree让多个Agent在同一Repository上并行工作而尽量避免直接冲突。

这时候整个结构越来越接近：

Task Context
↓
Thread
↓
Workspace
↓
Git State
↓
Runtime
↓
Verification

而不是过去简单的：

Chat
↓
Code

---

最后

Local任务做到一半以后切Worktree，

真正危险的不是：

Codex会不会帮你切过去。

而是：

你有没有分清Thread Context、Git State和Runtime Environment。

Handoff真正应该保持的是：

Goal
Decision
Progress

但切换以后仍然必须重新确认：

Revision
Diff
Environment
Verification

所以正确理解不是：

Handoff
=
完整复制当前世界

而应该是：

Handoff
=
保持Task Continuity
+
切换Execution Environment

真正稳定的流程应该是：

Local Exploration
↓
Checkpoint
↓
Handoff
↓
Worktree Isolation
↓
State Revalidation
↓
Continue Execution
↓
Verified Result

当Codex开始承担越来越长的工程任务以后，

开发者真正需要管理的，也不再只是：

一个Chat有没有上下文。

而是：

同一个Task在不同Workspace之间移动以后，Context、Code和Environment还能不能保持一致。

这才是Thread Handoff真正值得理解的地方。

持续更新Codex、大模型开发相关技术内容。
长期使用各类代码大模型，整理了稳定的AI会员订阅渠道。