CodexWorktree 使用教程

📖 项目简介

这是 OpenAI 开源的 Codex 命令行里自带的能力：给每个任务签出一份独立的 Git 工作目录。仓库还是同一个，不用把项目复制三遍。截至 2026-10-09，GitHub 上约 12.8 万星，协议是 Apache-2.0。

它用的就是 Git 自带的 worktree。每个任务一条分支、一份目录，三边同时改，合回去之前谁也碰不到谁的文件。

0.154.0（2026-09-09）先以实验功能上线，会话里输入 /worktree，或启动时加上 --worktree。0.156.0（2026-09-22）起默认开启，任务面板里也能直接新建。0.162.0（2026-10-08）起，在任务面板按 P 可以把最急的任务钉在置顶组。

📎 相关链接与下载地址（点击展开）

仓库：openai/codex
0.156.0（默认开启）：rust-v0.156.0
0.162.0（任务置顶）：rust-v0.162.0
命令行参数：Codex CLI reference
更多教程：关注公众号 / 抖音 / 视频号「IT小圈」

✨ 核心亮点

🌿

一份目录干一件事

每个任务签出自己的工作目录，不改你正在看的那份代码。

⚡

三个任务一起跑

修登录、改主题、补测试可以同时开工，不用排队。

📌

最急的按 P 置顶

0.162.0 起，任务面板里按 P，把它钉在置顶组。

📦

不用复制三份项目

共用同一个仓库，只是多签出几份工作目录。

🧩 它能做什么、输出什么

项目	说明
输入	一句任务，或会话里的 /worktree
适用类型	已经是 Git 仓库的本地项目。不是 Git 仓库用不了。
输出	一条新分支 + 一份独立工作目录，任务在那份目录里改
语言 / 兼容	跟仓库语言无关。Windows、macOS、Linux 都能开。
规格 / 容量	0.156.0 起默认开启。同时开几份目录没有单独的个数上限，磁盘够就能多开。

🖥️ 环境要求

环境	建议配置
操作系统	Windows、macOS、Linux。0.154.0 起 Windows 也可以挂后台服务。
运行环境	Codex CLI 0.156.0 或更新。用 npm 安装时需要本机有 Node。
硬件	不需要显卡。占的是磁盘：每份工作目录是一份检出，不是把整个 .git 再复制一遍。
低配方案	一次只开两个任务也行。目录多了就删掉已经合并的那份。
关键依赖	Git。项目必须已经是一个仓库，并且你在仓库目录里启动。

🚀 如何使用

💡

先把命令行升到 0.156.0 或更新，进一个 Git 仓库，用 --worktree 或 /worktree 给任务分目录。

安装命令行

本机有 Node 时，用下面这一条安装。装完看版本，至少要 0.156.0。

                        bash
                        npm install -g @openai/codex
codex --version
                    

进入你的仓库

到项目根目录。这里必须已经是 Git 仓库，否则分不出独立目录。仓库地址在页面底部的折叠链接里，GitHub 搜索 openai codex 也能找到。

                        bash
                        cd 你的项目目录
git status
                    

给一个任务分一份目录

启动时直接带上，或进了会话再输入斜杠命令。0.156.0 之前要先打开实验开关，0.156.0 起不用了。

                        bash
                        codex --worktree
                    

                        会话里
                        /worktree
                    

常用入口：

入口	作用
`--worktree`	启动时就分一份独立工作目录。0.154.0 加入，0.156.0 起默认可用。
`/worktree`	已经在会话里时用。可以新开、接着当前会话分出去，或浏览已有的目录。
按 `P`	0.162.0 起，在任务面板把这个任务钉到置顶组。

再开第二个、第三个

每个任务各走一次。比如修登录、加深色模式、补测试，各一份目录。最急的那个在任务面板按 P 置顶，干完一个看一个的改动，确认后再合回主分支。

                        bash
                        codex --worktree
codex --worktree
codex --worktree
                    

结合 Codex 使用

这就是 Codex 自己的功能，不用再装插件，也不用另接一套工具。在仓库里直接说「同时开三个任务」，让它各自走 /worktree。

✅

三份目录同时改，合回去之前互不影响。

🎯 典型应用场景

🔐

修一个报错

登录页的 bug 单独一份目录，不影响你正在写的功能。

🌙

改一套界面

深色模式放在另一条分支，改坏了删掉这份目录就行。

🧪

补测试

测试任务和功能任务分开，避免它顺手改了同一份实现。

👀

先看再合

每个任务干完，单独看它的改动，确认后再合回主分支。

📌

先做最急的

三个一起跑的时候，按 P 把马上要看的那个钉在上面。

🌿

试一条不敢合的路

不确定的改法放在独立目录里试，主目录保持能跑。

📈 和另外两种做法比

做法	结果
一个会话里排队干三件事	后一件会碰到前一件正在改的文件。
把整个项目复制三份	能隔开，但磁盘和同步都重，三份仓库还会分叉。
worktree	共用一个仓库，每份只是一次检出。0.156.0 起默认就能用。

🧠

隔离靠的是 Git 的工作目录，不是再装一个插件。合回去仍然走你原来的分支。

❓ 常见问题

Q: 和我自己敲 git worktree add 有什么区别？

目录还是 Git 的工作目录。差别是 Codex 把创建、切过去干活、之后再找回来，收进了 /worktree 和任务面板，不用你先记一串参数。

Q: 不是 Git 仓库能不能用？

不能。先在项目里完成第一次提交，再开。

Q: 我还没提交的改动会跟着过去吗？

新建时可以选择从哪条分支起，也可以选择带不带当前还没提交的改动。拿不准就留在原目录，让新任务从已提交的版本开始。

Q: 三个任务还是改了同一个文件怎么办？

各自的目录里不会打架。合回同一条分支时，Git 仍可能提示冲突，那个时候再处理。

Q: 提示找不到 worktree？

先看 codex --version。低于 0.156.0 时这个功能还不是默认开启的，升级到 0.156.0 或更新再试。

Q: Windows 能用吗？

能。0.154.0 起 Windows 会话也可以挂后台服务。仍然要先装好 Git。

Q: 按 P 没有置顶？

置顶是 0.162.0 才加的，而且要在任务面板里按。会话输入框里按 P 不会置顶。

Q: 可以商用吗？

仓库协议是 Apache-2.0，按这个协议使用即可。