发布日期：2026-10-28 资料核验：2026-10-28；面向Codex桌面端管理的本地工作树，按钮名称沿用OpenAI Docs英文标识

Codex桌面端的Worktree功能会为任务创建独立的Git工作目录，让多个会话并行处理同一项目。根据2026年10月核验的OpenAI官方文档，排查应从应用里的失败位置开始：创建前检查所选项目与起始分支，工作树已有但会话卡住时查看批准状态和日志，项目运行失败时补齐本地环境。分支占用可按需要通过Hand off移回Local，正常清理的受管工作树则可重新打开原会话查看恢复选项。本文以桌面界面操作为主，说明环境设置、文件复制和恢复功能的适用范围。

在Codex桌面端点了Worktree，任务却没正常开始；或者工作树已经打开，项目仍然运行失败。这两种现象需要检查的地方不同。

先看界面停在哪里：工作树尚未创建、会话没有启动，还是会话已经能用但项目跑不起来。 detached HEAD则是桌面端新工作树的默认正常状态，本身不代表报错。

点Worktree就失败：先检查项目和起始分支

桌面端创建工作树，需要当前项目位于Git仓库中，并有可用的起始提交。

按官方创建流程，在应用里重新核对这几个位置：

  1. 确认当前项目目录。 选中的应是目标Git仓库中的项目。如果加入的是多个仓库的共同父文件夹，改为打开实际仓库目录。

  2. 新建会话，在输入框下选择Worktree。 再检查下方选择的起始分支是否符合这次任务。

  3. 按需选择本地环境，再提交任务。 选择Local environment是可选步骤，没有选择并不自动等于创建失败。

刚建立的仓库如果还没有提交，应先用变更面板审阅文件、完成首次提交，再使用工作树。已有仓库则要核对所选起点，不能把所有失败都归为“没初始化Git”。

只有界面信息不足时，才打开项目对应的集成终端辅助检查：

git rev-parse --show-toplevel
git rev-parse --verify 'HEAD^{commit}'
git status --short --branch

第一条确认当前目录属于哪个仓库，第二条检查当前HEAD是否能解析为提交，第三条查看分支和改动。它们不替代应用中的起始分支选择；每条输出应单独阅读。

创建时若选择了带本地改动的当前分支，现行官方文档说明未提交改动也可以应用到工作树。因此，“必须先提交全部改动”不是所有任务的前提。

工作树已有，但会话卡住：检查批准状态，再试小任务

目录创建成功不等于会话已经正常启动；这时应先检查桌面应用的会话状态。

先看是否有等待批准的操作，再打开集成终端执行git status，确认基本命令能否运行。终端卡住时，官方指南建议关闭终端面板后重新打开，再尝试基本命令。

接着用一个更小的新会话验证，例如只要求读取README并返回一句摘要。这样有助于区分原任务与会话普遍无法启动的问题，但一次成功不能证明原故障已修复。

若仍持续卡住，等其他活动会话完成后再重启桌面应用。No local environment selected只能作为上下文：官方把环境选择列为可选项，不能凭这一行日志就判断会话失败原因。

会话能用，项目却跑不起来：在桌面设置里配置环境

新工作树是另一个目录，本地项目已有的依赖、构建产物和被忽略配置不一定在这里齐全。

在桌面应用的设置中配置Local environments，把仓库实际需要的安装或构建流程写入setup script。随后新建工作树时选择对应环境，检查脚本是否执行成功，再运行项目。

依赖安装要沿用项目的锁文件和包管理器，不必为工作树另换一套流程。官方说明，setup script在新会话创建新工作树时运行；给已有工作树新增配置，不代表它已自动重跑。

共享环境配置位于项目根的.codex目录。单仓有多个项目时，应用应打开包含相应配置的项目目录。

如果缺的是项目已经忽略的.env.local等本地文件，可以在仓库根创建.worktreeinclude，按需列出路径：

# .worktreeinclude
.env.local

这里写文件路径，不写密钥值。它用于新建本地受管工作树时复制匹配的忽略文件；已有工作树仍需单独补齐配置。

复制规则也有限制：不会复制其他普通未跟踪文件，会跳过源符号链接，且不覆盖目标已有文件。补齐依赖和配置后，在实际工作树中运行仓库规定的最小测试，确认环境修正在这里生效。

提示分支被占用：用Hand off把任务带回Local

若准备在本地检出分支时遇到already used by worktree，应从桌面端的交接流程处理。

同一分支不能同时在两个工作树中检出。想把当前工作带回日常本地目录验证，可以在会话顶部点击Hand off，选择Local，由应用处理移动会话和代码所需的Git步骤。

如果希望两边继续并行，使用不同分支。留在工作树继续开发时，可通过会话顶部的Create branch here创建分支；也可以先保留默认的detached HEAD状态。

这类冲突不需要靠强制删除工作树解决。交接前先确认当前任务和改动，再按需要选择工作位置。

工作树目录不见了：重新打开原会话，查看恢复选项

如果是桌面应用正常清理的受管工作树，官方说明应用会先保存快照，重新打开原会话时提供恢复选项。

若原会话已归档，可以先在Settings中找到Archived chats，取消归档后重新打开，再查看工作树状态。

这项说明针对应用管理的清理流程，不能据此保证手动删除任意目录后都能恢复。先保留会话记录并检查应用提供的选项，比直接清空工作树目录更有利于继续排查。

如果仍无法恢复或启动，反馈时提供桌面应用版本、操作系统、错误原文和界面停留位置。终端里的codex --version可能来自另装的CLI，不能代替桌面应用版本。

macOS应用日志可按官方文档在~/Library/Logs/com.openai.codex/YYYY/MM/DD查看。分享相关片段前检查敏感信息，不必上传完整认证文件。

依据OpenAI Docs，Codex桌面端工作树排错应围绕项目选择、会话状态、本地环境和交接恢复操作展开。本文信息截至2026年10月28日，已核对官方界面流程，并验证所用Git查询命令；未复现特定桌面应用故障，未操作用户的实际工作树。

参考资料

相关文章

七牛云产品