MemoryLake
返回全部文章
Tutorial2026 年 11 月 13 日·12 分钟阅读

什么是 Codex Worktree?新 Worktree 的初始内容、归档对话为何会删除它,以及如何恢复 Codex 保存的快照 (2026)

你启动了一个 Codex 对话,在编辑器下方选择了 Worktree 而不是 Local,让它在后台运行,而你继续在自己的检出副本中工作。一切进展顺利。几周后,你打开一个较旧的对话,发现它处理的文件已不在磁盘上。Codex 提示恢复某些内容。发生了什么?

OpenAI 文档中的两点解释了原因。Worktree 被设计为临时性的:“默认情况下,对话使用 Codex 管理的 worktree。这些被设计为轻量级且可丢弃的。” 并且它们会按照你可能未注意到的计划进行清理:“默认情况下,Codex 保留最近的 15 个 Codex 管理的 worktree。”

工作成果并不一定丢失了。“在删除 Codex 管理的 worktree 之前,Codex 会保存该工作区的快照。”

本指南涵盖了什么是 Codex worktree、如何在其中启动对话、新 worktree 的初始内容及排除内容、Handoff 如何在 Local 和 worktree 之间移动对话、Codex 何时删除 worktree、如何恢复 worktree、worktree 的存放位置,以及 worktree 不保存的内容。

什么是 Codex worktree

OpenAI 的文档开篇就说明了其目的:“Worktree 让 Codex 能够在同一个项目中运行多个独立的对话,而互不干扰。”

在底层,Codex worktree 就是一个 Git worktree。“Worktree 仅适用于属于 Git 仓库的项目,因为它们在底层使用 Git worktree。” 文档解释了这意味着什么:“每个 worktree 都有仓库中每个文件的独立副本,但它们共享关于 commit、branch 等相同的元数据(.git 文件夹)。”

ChatGPT 桌面应用使用三个术语:

  • Local 是你自己的检出副本,即你创建的仓库。
  • Worktree 是应用从你的本地检出副本创建的 Git worktree。
  • Handoff 是在 Local 和 worktree 之间移动对话的流程。

OpenAI 建议将其视为前台和后台:“你可以将 Local 视为前台,将 Worktree 视为后台。”

仓库和 worktree 保留在存放项目的机器上。“Worktree 不会在手机上本地运行。” ChatGPT 移动应用可以启动、引导、批准和审查 worktree 对话,但它是通过控制连接的电脑上的 Codex 来实现的。

如何在 worktree 中启动对话

步骤很简短:

  1. 在新对话视图中,在编辑器下方选择 Worktree。可选地选择一个本地环境来运行设置脚本。
  2. 在编辑器下方,选择作为 worktree 基础的 Git branch。
  3. 提交你的提示词。Codex 会从该 branch 创建 worktree。
  4. 准备就绪后,继续在 worktree 上工作,或将对话 handoff 到 Local。

项目必须位于 Git 仓库中。

新 worktree 的初始内容

Worktree 不是一个空文件夹。OpenAI 的文档准确描述了 Codex 在其中放入的内容。

该 branch 的最新 commit。 “初始 commit 是启动对话时所选 branch 的 HEAD commit。”

你的未提交更改(如果你选择的 branch 包含这些更改)。 “如果你选择了一个包含本地更改的 branch,Codex 也会将未提交的更改应用到 worktree。”

所有已追踪文件。 “本地 Codex 管理的 worktree 从 Git 检出开始,因此已追踪文件已经存在。”

没有自己的 branch。 “Worktree 不会作为 branch 检出。” 它处于分离 HEAD 状态,文档给出了原因:“这让 Codex 可以创建多个 worktree 而不会污染你的 branch。”

你的本地指令覆盖。 Codex 会自动复制一个被忽略的文件。“Codex 会自动将忽略的 AGENTS.override.md 复制到本地管理的 worktree 中,因此你不需要在 .worktreeinclude 中列出它。” 如果你在该文件中保留了给 Codex 的个人指令,它们在 worktree 中也会存在。

你的设置脚本安装的任何内容。 如果你选择了本地环境,其设置脚本会运行。OpenAI 解释了这为何重要:“由于 worktree 在与本地对话不同的目录中运行,你的项目可能未完全设置,并且可能缺少未检入仓库的依赖项或文件。” 以及:“当 Codex 在新对话开始时创建新 worktree 时,设置脚本会自动运行。”

新 worktree 排除的内容

从 Git 检出开始的另一面是,除非你另有说明,否则 Git 忽略的任何内容都会被留下。

默认情况下忽略的文件。 OpenAI 的示例包括 .env 文件和 secrets 文件。要带上特定的文件,请在仓库根目录添加一个 .worktreeinclude 文件,并列出要复制的路径或模式。文档明确了限制:“Codex 仅复制匹配 .worktreeinclude 的忽略文件;它不会复制 Git 未追踪的其他本地文件。”

包含列表中的已追踪文件。 “不要列出已追踪文件。” 它们已经存在了。

符号链接和现有文件。 “Codex 会跳过源符号链接,并且不会覆盖新检出中已存在的文件。”

其他类型的 worktree。 包含行为具有适用范围:“此行为适用于本地 ChatGPT 桌面应用管理的 worktree,不适用于远程 worktree 或你从命令行自行创建的 Git worktree。”

已安装的依赖项。 除非设置脚本安装了它们,否则全新的 worktree 可能没有你的 node_modules 或构建输出。这就是本地环境设置脚本的作用。

在 Local 和 worktree 之间移动对话

Handoff 可以在任一方向移动对话及其代码。OpenAI 的文档称:“向 Local 或从 Local 进行 Handoff 会移动你的对话 以及 代码,以便你可以在另一个检出副本中继续。”

两个细节使 Handoff 可预测:

  • 对话保留其 worktree。 “每个对话随着时间的推移保留相同的关联 worktree。如果你稍后将对话交回给 worktree,Codex 会将其返回到同一个后台环境,以便你可以从上次中断的地方继续。”
  • 忽略的文件不会随之移动。 “由于 Handoff 使用 Git 操作,除非 Codex 通过 .worktreeinclude 将其复制到本地管理的 worktree 中,否则 .gitignore 文件中的任何文件都不会随对话移动。”

我们在关于 Codex Handoff 中随对话移动的内容 的指南中详细介绍了 Handoff,包括在你的电脑和远程主机之间随对话移动的内容。

容易让人困惑的 branch 规则

Git 有一条 Codex 无法绕过的规则。文档用粗体标出:“Git 仅允许一个 branch 一次只能在一个地方检出。”

当你将 worktree 转换为 branch 时,这一点就会显现出来。如果你在 worktree 上选择“在此创建 branch”,然后尝试在本地检出副本中检出该 branch,Git 会拒绝并报错,提示该 branch 已被 worktree 使用。

OpenAI 的建议:“如果你计划在本地检出该 branch,请使用 Handoff 将对话移动到 Local,而不是尝试在两个地方同时检出同一个 branch。”

Codex 何时删除 worktree

Worktree 占用空间。“Worktree 可能会占用大量磁盘空间。每个 worktree 都有自己的一套仓库文件、依赖项、构建缓存等。” 因此桌面应用限制了保留的数量。

默认限制。 “默认情况下,Codex 保留最近的 15 个 Codex 管理的 worktree。如果你希望自行管理磁盘使用情况,可以在设置中更改此限制或关闭自动删除。”

删除发生的时间。 文档列出了两个触发因素:

  • 你归档了关联的对话。
  • Codex 需要删除较旧的 worktree 以保持在配置的限制内。

第一个因素很容易被忽视。归档对话听起来像是整理侧边栏,但对于带有 Codex 管理的 worktree 的对话,它也会删除该 worktree。Codex 中的归档还有其他影响,我们在 Codex agent 命令中心以及归档和删除的作用 指南中对此进行了介绍。

受保护的内容。 如果置顶对话与 Codex 管理的 worktree 绑定,或者对话仍在进行中,则不会自动删除这些 worktree。

较旧的永久 worktree。 “在早期版本中创建的永久 worktree 仍然可用,并受到自动清理的保护。你无法再从项目菜单创建永久 worktree。”

如何恢复已删除的 worktree

删除 worktree 不会删除对话。OpenAI 的 FAQ 称:“即使底层的 worktree 目录被删除,对话仍可保留在你的历史记录中。”

并且工作成果会先被保存:“在删除 Codex 管理的 worktree 之前,Codex 会保存该工作区的快照。如果你在 worktree 被删除后打开对话,你将看到恢复它的选项。”

因此恢复路径很简单:打开对话并选择恢复选项。

文档没有说明快照保留多长时间,或者快照是否包含通过 .worktreeinclude 复制的忽略文件。如果 worktree 中包含你无法重新创建的内容,例如本地 secret 或生成的文件,请保留自己的副本,而不要依赖快照。

Worktree 的存放位置

“Codex 在 $CODEX_HOME/worktrees 中创建 worktree。” 你可以更改该位置。OpenAI 的 FAQ 建议打开 Settings,然后选择 Worktrees,更改 Worktree root。

如果你的主驱动器空间较小,或者你想将 worktree 放在更快的磁盘上,这很有用。当你手动清理磁盘空间时,了解这一点也很重要。对置顶和进行中对话的保护以及快照步骤是针对 Codex 自身清理的文档说明,而不是针对你自行删除的文件夹。

用于计划任务的 worktree

Worktree 不仅适用于你自行启动的对话。“对于 Git 仓库,计划任务可以在专用的后台 worktree 上运行,这样它们就不会与你正在进行的工作冲突。”

非版本控制项目的工作方式不同:“在非版本控制的项目中,计划任务直接在项目目录中运行。”

Worktree 不保存的内容

Worktree 保存文件。附加到它的对话保存交流内容。两者都不是为了保存从一个对话延续到下一个对话的推理过程:为什么要选择这种方法、哪些替代方案失败了,以及代码正在等待什么。

Worktree 在设计上是可丢弃的。当一个 worktree 被删除时,快照会保留其中的工作成果。在此过程中做出的决策存在于该对话的交流中,一旦有了几十个对话,这些决策就很容易丢失。

人们首先尝试的操作

归档旧对话以进行清理。 对于带有 Codex 管理的 worktree 的对话,归档会删除 worktree。

期望在新 worktree 中看到 .env 文件。 除非匹配 .worktreeinclude,否则不会复制忽略的文件。

在本地检出 worktree 的 branch。 Git 允许 branch 一次在一个地方。请改用 Handoff。

手动删除 worktree 文件夹。 快照步骤是针对 Codex 自身清理的文档说明,而不是针对你自行删除的文件夹。

假设对话随 worktree 一起消失。 对话可以保留在历史记录中,你可以从对话中恢复 worktree。

解决方案:使用 worktree 而不丢失工作成果

第 1 步:设置新 worktree 所需的内容

为依赖项添加本地环境设置脚本,并为 worktree 需要的忽略文件添加 .worktreeinclude 文件。

第 2 步:保护你会回访的对话

置顶你想要保留其 worktree 的对话,或者在设置中提高限制。

第 3 步:恢复而不是重做

如果 worktree 被删除了,在重新开始之前,打开对话并使用恢复选项。

第 4 步:写下推理过程

将 worktree 更改背后的决策(例如方法和排除的方案)保留在对话之外。

在 MemoryLake 中设置

Worktree 是进行并行工作的理想场所,Codex 在清理前会小心保存它。这些工作背后的决策是下一个对话(在新的 worktree 或 Local 中)需要继承的内容,而无需重新询问。

MemoryLake 是此类项目上下文(如决策、约束和约定)的记忆层,保存在你维护的一个地方,并可供你连接的助手(如 ChatGPT、Claude Code 和 Codex)使用。

你用自己的语言亲自编写条目。不会从你的 worktree、快照、Codex 对话、.worktreeinclude 或 AGENTS.override.md 文件、Codex 记忆或任何供应商的存储中读取、写入或删除任何内容。Worktree、Handoff 和清理工作的方式与 OpenAI 描述的一致。

第 1 步:创建 API key

登录并从控制面板生成一个 key。像对待任何其他凭据一样将其存储在仓库之外,不要将其添加到 .worktreeinclude。

MemoryLake 控制台显示 API keys 屏幕,在此创建并复制新 key 以供 agent 使用
MemoryLake 控制台显示 API keys 屏幕,在此创建并复制新 key 以供 agent 使用

第 2 步:上传你的第一条记忆

从你在解决方案第 4 步中写下的内容开始:每项工作的处理方法、尝试过的替代方案以及塑造它的约束条件。每个条目一个决策。

MemoryLake 工作区显示上传的第一批文档,列出每个文件成为可搜索记忆的过程
MemoryLake 工作区显示上传的第一批文档,列出每个文件成为可搜索记忆的过程

第 3 步:连接你的 AI 和 agent

连接 Codex 和你使用的任何其他助手。在全新 worktree 中的新对话,或 handoff 到 Local 的对话,都可以利用相同的决策。

MemoryLake 集成屏幕列出了可以连接到记忆层的 AI 客户端和 agent 框架
MemoryLake 集成屏幕列出了可以连接到记忆层的 AI 客户端和 agent 框架

这在实践中改变了什么

第一个区别是清理不再对你的推理过程构成风险。Worktree 可以被归档和删除,而其背后的决策仍然被记录在案。

第二个区别是并行对话的启动速度更快。每个新的 worktree 对话都可以利用项目已确定的决策,而不是重新发现它们。

第三个区别是跨工具的连续性。Claude Code 或在同一个仓库上工作的另一个助手可以使用相同的条目。

Codex worktree 最佳实践

将 worktree 用于后台工作。 将 Local 留给你正在积极测试的内容。

添加设置脚本。 除非有程序安装,否则新 worktree 可能没有依赖项。

在 .worktreeinclude 中列出忽略的文件。 仅复制匹配的忽略文件。

置顶你会回访的内容。 置顶的对话会保留其 worktree。

谨慎归档。 归档会删除对话的 Codex 管理的 worktree。

恢复而不是重做。 Codex 在删除管理的 worktree 之前会保存快照。

将“为什么”保留在别处。 Worktree 保存文件,而不是理由。

结论

Codex worktree 是 ChatGPT 桌面应用创建的 Git worktree,以便对话可以在后台运行而不触及你的本地检出副本。它从你选择的 branch 的 HEAD commit 开始,包含你的未提交更改(如果该 branch 包含这些更改),拥有每个已追踪文件,并仅复制你在 .worktreeinclude 中列出的忽略文件以及 AGENTS.override.md。

Codex 默认保留最近的 15 个管理的 worktree,并在你归档对话时删除该对话的 worktree。置顶和进行中的对话受到保护,在删除管理的 worktree 之前,Codex 会保存一个你可以从对话中恢复的快照。将工作背后的推理过程保存在下一个对话可以读取的地方。

常见问题

什么是 Codex 中的 worktree?

它是 ChatGPT 桌面应用从你的本地检出副本创建的 Git worktree,以便 Codex 对话可以并行工作而不会干扰你的其他对话。

为什么我的 Codex worktree 消失了?

当你归档关联的对话时,或者当 Codex 需要保持在限制范围内(默认 15 个)时,它会删除管理的 worktree。

我可以恢复已删除的 Codex worktree 吗?

可以。Codex 在删除管理的 worktree 之前会保存快照,当你打开对话时,你会看到恢复它的选项。

为什么我的 .env 文件不在 worktree 中?

除非忽略文件匹配仓库根目录下 .worktreeinclude 中的模式,否则不会被复制。

Codex 将 worktree 存储在哪里?

默认在 $CODEX_HOME/worktrees。你可以在 Settings 下的 Worktrees 中更改 Worktree root。

为什么我不能在本地检出 worktree 的 branch?

Git 允许一个 branch 一次只能在一个地方检出。请改用 Handoff 将对话移动到 Local。

归档 Codex 对话会删除其 worktree 吗?

是的。归档关联的对话是删除 Codex 管理的 worktree 的触发因素之一。