Codex 中文手册

简体中文

繁體中文

简体中文

繁體中文

外观

交流群即将上线

工作树 ​

本页是 OpenAI 官方文档 的中文镜像，译文由官方维护。以官方页面为准。

工作树让 Codex 能够在同一个项目中运行多个彼此独立、互不干扰的聊天。代码仓库、工作树和命令始终保留在包含该项目的计算机或远程开发环境中。您可以直接在 ChatGPT 桌面应用中工作，也可以使用 ChatGPT 移动应用中的远程功能，在已连接的计算机上发起、指导、审批和审查工作树聊天。

对于 Git 代码仓库，计划任务可以在专用后台工作树中运行，以免与您正在进行的工作发生冲突。对于未纳入版本控制的项目，计划任务直接在项目目录中运行。您也可以手动在工作树中发起聊天，并使用移交功能在本地与工作树之间移动聊天。

工作树不会在您的手机本地运行。使用远程功能时，移动应用会控制已连接计算机上的 Codex，或该计算机使用的远程开发环境中的 Codex；代码仓库和工作树仍保留在相应环境中。下文针对桌面应用的说明适用于已连接的计算机。

什么是工作树 ​

工作树仅适用于 Git 代码仓库中的项目，因为其底层使用Git 工作树。工作树可让您为代码仓库创建第二份副本，即“检出”。每个工作树都拥有代码仓库中每个文件的独立副本，但所有工作树共享与提交、分支等相关的元数据，即 .git 文件夹。因此，您可以并行检出和处理多个分支。

术语 ​

  • 本地检出：您创建的代码仓库。在 ChatGPT 桌面应用中，有时简称为 本地 。
  • 工作树：在 ChatGPT 桌面应用中基于您的本地检出创建的Git 工作树。
  • 移交：在本地与工作树之间移动聊天的流程。Codex 会处理在两者之间安全移动工作内容所需的 Git 操作。

为什么要使用工作树 ​

  1. 与 Codex 并行工作，而不会影响您当前的本地设置。
  2. 在您专注于前台工作时，将后台工作排入队列。
  3. 等您准备好检查、测试或更直接地协作时，再将聊天移至本地。

入门 ​

使用工作树需要 Git 代码仓库。请确保您选择的项目位于 Git 代码仓库中。

  1. 选择“工作树”

    在新建聊天视图中，选择编辑器下方的 工作树 。 您也可以选择本地环境，为工作树运行设置脚本。

  2. 选择起始分支

    在编辑器下方，选择工作树所基于的 Git 分支。它可以是您的 main / master 分支、功能分支，也可以是包含未暂存本地更改的当前分支。

  3. 提交提示

    提交提示后，Codex 会根据您选择的分支创建 Git 工作树。默认情况下，Codex 在“分离 HEAD”状态下工作。

  4. 选择继续工作的位置

    准备好后，您可以直接在工作树中继续工作，也可以将聊天移交到本地检出。移交到本地或从本地移出时，聊天 和 代码都会随之移动，以便您在另一个检出中继续工作。

在本地与工作树之间工作 ​

工作树的使用体验与本地检出非常相似，区别在于它们在工作流程中所处的位置。您可以将本地视为前台，将工作树视为后台。移交功能可让您在两者之间移动聊天。

在底层，移交功能会处理在两个检出之间安全移动工作内容所需的 Git 操作。这一点很重要，因为 Git 只允许同一分支在同一时间于一个位置检出。如果您在工作树中检出某个分支，就 无法 同时在本地检出中检出该分支，反之亦然。

实际操作中，常见的方式有两种：

  1. 仅在工作树中工作。如果您可以直接在工作树中验证更改，这种方式最合适，例如您已经通过本地环境设置脚本安装了依赖项和工具。
  2. 将聊天移交到本地。如果您希望将聊天移至前台，请使用这种方式，例如您希望在惯用的 IDE 中检查更改，或您的应用只能运行一个实例。

选项 1：在工作树中工作 ​

如果您希望只在工作树中处理这些更改，请使用聊天标题栏中的 在此创建分支 按钮，将工作树转换为分支。

接下来，您可以提交更改、将分支推送到远程代码仓库，并在 GitHub 上创建 Pull Request。

您可以使用标题栏中的“打开”按钮在 IDE 中打开工作树、使用集成终端，或在工作树目录中执行其他任何所需操作。

请注意，如果您在工作树中创建分支，就无法在任何其他工作树中检出该分支，包括您的本地检出。

选项 2：将聊天移交到本地 ​

如果您希望将聊天移至前台，请在聊天标题栏中选择 移交 ，然后将其移至 本地。

当您想在惯用的 IDE 窗口中查看更改、运行现有的开发服务器，或在日常使用的同一环境中验证工作成果时，这种方式非常合适。

Codex 会处理在工作树与本地检出之间安全移动聊天所需的 Git 步骤。

每个聊天始终关联同一个工作树。如果您稍后将聊天移交回工作树，Codex 会将其移回同一个后台环境，让您从上次中断的位置继续。

您也可以反向操作。如果您已在本地工作并希望腾出前台，请使用 移交 功能将聊天移至工作树。当您希望 Codex 继续在后台工作，而自己在本地转去处理其他事务时，此功能很有用。

由于移交使用 Git 操作，您的 .gitignore 文件中列出的任何文件都不会随聊天一起移动，除非 Codex 使用 .worktreeinclude 将这些文件复制到本地托管工作树中。

高级详情 ​

Codex 管理的工作树与永久工作树 ​

默认情况下，聊天使用 Codex 管理的工作树。这类工作树设计为轻量且可随时丢弃。Codex 管理的工作树通常专用于一个聊天；如果您稍后将该聊天移交回来，Codex 会让它回到同一个工作树。

如果您需要长期存在的环境，请通过侧边栏中项目的三点菜单创建永久工作树。这样会创建一个新的永久工作树，并将其作为独立项目。永久工作树不会被自动删除，而且您可以从同一个工作树发起多个聊天。

Codex 如何为您管理工作树 ​

Codex 在 $CODEX_HOME/worktrees 中创建工作树。起始提交是您发起聊天时所选分支的 HEAD 提交。如果您选择的分支包含本地更改，Codex 也会将未提交的更改应用到工作树。工作树不是以分支形式检出，而是处于分离 HEAD状态。这样，Codex 就可以创建多个工作树，而不会弄乱您的分支。

将已忽略的本地文件复制到托管工作树中 ​

由 Codex 管理的本地工作树以 Git 检出为起点，因此已经包含受跟踪的文件。如果您的代码仓库忽略了新工作树所需的本地设置文件，请在代码仓库根目录添加 .worktreeinclude 文件，并列出需要复制的已忽略路径或 .gitignore 风格的匹配模式，以便 Codex 在创建托管工作树时复制相应文件。

此功能适用于 Git 有意忽略的文件，例如 .env、.env.local 或 config/secrets.json。Codex 只会复制与 .worktreeinclude 匹配的已忽略文件；不会复制 Git 未跟踪的其他本地文件。请勿列出已跟踪的文件。

Codex 会自动将被忽略的 AGENTS.override.md 复制到本地托管工作树中，因此您无需在 .worktreeinclude 中列出它。

text
# .worktreeinclude
.env
.env.local
config/secrets.json

Codex 会跳过源符号链接，也不会覆盖新检出中已有的文件。此行为适用于由 ChatGPT 桌面应用管理的本地工作树，不适用于远程工作树，也不适用于您通过命令行自行创建的 Git 工作树。

分支限制 ​

假设 Codex 已在某个工作树中完成一些工作，您选择使用 在此创建分支在该工作树中创建 feature/a 分支。现在，您想在本地检出中试用该分支。如果尝试检出它，您会收到以下错误：

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

要解决此问题，您需要在该工作树中检出其他分支，而不是 feature/a。

如果您计划在本地检出该分支，请使用移交功能将聊天移至本地，而不要尝试同时在两处检出同一个分支。

Git 不允许同时在多个工作树中检出同一分支，因为分支表示一个单一可变引用（refs/heads/<name>），其含义是某个工作树的“当前检出状态”。

当分支被检出时，Git 会将其 HEAD 视为归该工作树所有，并要求提交、重置、变基和合并等操作以明确、串行的方式推进该引用。如果允许多个工作树同时检出同一分支，就会因无法确定由哪个工作树的操作更新分支引用而产生歧义和竞态条件，进而可能导致提交丢失、索引不一致或冲突解决方式不明确。

Git 通过强制规定每个分支只能在一个工作树中检出，确保每个分支只有一个权威的工作副本，同时仍允许其他工作树通过分离的 HEAD 或独立分支安全地引用相同的提交。

工作树清理 ​

工作树可能占用大量磁盘空间。每个工作树都有各自的代码仓库文件、依赖项、构建缓存等。因此，ChatGPT 桌面应用会尽量将工作树数量控制在合理范围内。

默认情况下，Codex 会保留最近的 15 个由 Codex 管理的工作树。如果您希望自行管理磁盘使用情况，可以在设置中更改这一上限或关闭自动删除。

Codex 会尽量避免删除仍需保留的工作树。出现以下情况时，由 Codex 管理的工作树不会被自动删除：

  • 有已置顶的聊天与该工作树关联
  • 关联的聊天仍在进行中
  • 该工作树是永久工作树

在以下情况下，由 Codex 管理的工作树会被自动删除：

  • 您归档关联的聊天
  • Codex 需要删除较旧的工作树，以使工作树数量不超过您配置的上限

在删除由 Codex 管理的工作树之前，Codex 会保存其中工作内容的快照。如果您在工作树被删除后打开关联的聊天，就会看到恢复该工作树的选项。

常见问题 ​

可以。默认情况下，Codex 会在 $CODEX_HOME/worktrees 下 创建由 Codex 管理的工作树。要选择其他位置，请打开 设置 > 工作树 ，然后更改 工作树根目录。

可以。使用聊天标题栏中的 移交 ，即可在您的本地 检出与工作树之间移动聊天。Codex 会执行所需的 Git 操作，以便在不同环境之间安全地移动 聊天。如果您之后将聊天移交回工作树， Codex 会将其移回原先关联的同一个工作树。

即使底层工作树目录被删除，聊天仍可保留在您的历史记录中。对于由 Codex 管理的工作树，Codex 会在删除工作树前保存快照；如果您重新打开关联的聊天，Codex 会提供恢复该工作树的选项。永久工作树不会因您归档关联的聊天而被自动删除。

非官方社区教程 · 「官方文档」区为 learn.chatgpt.com 中文原文镜像 · 以官方页面为准

Copyright © 2026 Codex 中文手册