本教程共 32 篇 · 第 29 篇 · 更新于 2026-07-26 · 约 13 分钟阅读

29. Git 工作树与 GitHub 集成

本节目标：搞懂 Worktrees 工作树的并行隔离机制和 Handoff 交接，以及 GitHub 集成—@codex review 审 PR、自动审查、@codex fix 改代码、AGENTS.md 定审查规则、本地 /review 自查。

前面讲的那些活，基本都在一个线程里折腾。但现实里你常需要同时干几件互不相干的事—一个修 bug、一个加功能、一个补测试。如果都在同一个项目目录里改，几个 Codex 抢同一份文件，后写的盖前写的，越并行越乱。Worktrees 就是来解决这个的。

Worktrees 是什么

Worktree（工作树）是 Git 的一个功能，让同一个仓库创建多个工作目录。Codex 对它提供了原生支持。每个 worktree 有完整文件副本，但共享提交、分支等 .git 元数据，所以能并行检出和处理多个分支。

打个比方，一个病人的病历本只有一份原件，三个科室医生要同时给意见，全挤在那一本上写，笔迹必然打架。Worktree 干的就是给每个医生发一份病历副本去写，各写各的，最后汇总进原件。

什么场景该上 Worktree：

两个不相干的模块同时推：一个修 bug、一个加功能，各开一个 Worktree 线程，谁也碰不到谁
手头改了一半没提交，突然想试另一个方案：开个 Worktree 试，原件纹丝不动，试砸了直接扔
让 Codex 后台跑一个大重构，前台继续干别的：甩进 worktree 后台跑

Note

Worktree 只在 Git 仓库里能用，底层就是 git 的 worktree 能力。它只在桌面 App 的 Codex 中可用，CLI 里没有对应开关。

在桌面 App 里建 Worktree 线程

四步就能建出来：

新线程时，模式从默认的 Local 切到 Worktree
选起始分支—可以是 main、某个功能分支，也可以是当前分支连带未暂存的本地改动
提交指令，Codex 基于你选的分支创建 git worktree 并在里头开工
干完决定去留—留在 worktree 接着干，或 Handoff 交接回 Local

Warning

Codex 建出的 worktree 默认处在 detached HEAD（游离头指针） 状态，不在任何分支上。这样能建好几个 worktree 而不污染你的分支列表。想正经提交推送，先点线程头部的 Create branch here 把它转成分支。

铁规：同一分支不能两处检出

这是最容易栽跟头的一条。Git 有一硬规矩：一个分支，同一时间只能在一个工作树里被检出。

你在某个 worktree 上检出了 feature/a，本地原件就不能同时也检出 feature/a。硬要两处检出，git 会甩你一个错：

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

为什么有这条限制？一个分支名代表「这棵工作树当前是什么状态」的唯一答案。要是允许两处同时检出、同时往里提交，到底听谁的就乱套了—可能丢提交、可能索引打架。

Tip

想把活挪到本地，别硬怼分支，用 Handoff。临时想看看，在 worktree 上改检出另一个分支，把目标分支腾出来。

Handoff：前后台双向搬

Handoff（交接）把线程在 Local（前台）和 Worktree（后台）之间双向搬，Codex 替你处理底层那些 git 操作。

两个方向各对应一条常见路径：

Worktree -> Local（后台端到前台）：点线程头部的 Hand off，选移到 Local。当你想用日常那套熟悉环境来验收—在常用 IDE 里读 diff、跑只能开一个实例的开发服务器时用。

Local -> Worktree（前台甩到后台）：反过来也行。想腾出前台去忙别的，用 Handoff 把线程挪进 worktree，让 Codex 后台继续跑。

Note

每个线程始终绑着同一个 worktree。你把它 Handoff 回 Local，过会儿又想丢回后台，Codex 会把它送回原来那个 worktree，接着上次的进度干。

Warning

Handoff 用的是 Git 操作，任何在 .gitignore 里的文件都不会随线程一起搬过去。.env、本地缓存这些没被 git 跟踪的东西，Handoff 不会带着走。

setup 脚本：让新 worktree 装备齐全

Worktree 是一份全新检出，没进 git 的依赖、配置、本地文件一开始都没有。最典型的坑：新 worktree 一跑，node_modules 不在、.env 不在，活儿直接卡住。

Local environment 的 setup 脚本解决这个问题。Codex 每次为新线程创建 worktree 时自动跑一遍，把依赖装好：

# .codex/setup.sh（新建 worktree 时自动跑）
npm install
npm run build

配置存在项目根目录的 .codex 文件夹里，可以提交进 git 跟队友共享—配一次，全队的 worktree 都自动装备齐全。

如果有些被 git 忽略的本地文件必须带进 worktree（比如 .env），在仓库根目录加一个 .worktreeinclude：

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

Codex 会把匹配这些模式的被忽略文件复制到托管工作树里。

工作树清理

每个 worktree 都有自己的仓库文件、依赖、构建缓存，开十几个硬盘肉眼可见地瘪。Codex 会帮你把数量控制在合理范围。

Codex 把 worktree 建在 $CODEX_HOME/worktrees 下统一管理（默认 ~/.codex/worktrees）。默认保留最近 15 个托管 worktree，上限可在设置里改，也能关掉自动删除自己管。

不会被自动删的：有置顶聊天绑着、聊天仍在进行中、是永久 worktree。

会被自动删的：你归档了关联聊天、Codex 为维持上限需要删更老的。

Tip

删之前 Codex 会保存工作快照。重新打开一个工作树已被删的聊天，界面会提供恢复选项。临时活用默认的托管 worktree 就行（用完即弃），想要长期稳定的环境从项目三点菜单建永久 worktree。

GitHub 集成：@codex review

Codex 与 GitHub 深度集成，在 PR 评论里 @ 它一下，它像不会累的队友，扫一遍 diff，按你仓库里定的规矩把高优先级风险挑出来挂在 PR 上。

前提条件

有 Codex Cloud 订阅（Plus、Pro、Business 等付费套餐）
在 chatgpt.com/codex 的设置里给仓库开启 Code review
授权 Codex 访问你的仓库

手动触发审查

在 PR 评论里打：

@codex review

Codex 的响应节奏：

先给你的评论加个眼睛反应—表示收到，开始看了
在云端拉起任务，读这个 PR 的 diff
像队友一样在 PR 上发一条 code review，把问题逐条挂在对应代码行

Note

在 GitHub 里，Codex 只标记 P0 和 P1 级别的问题，让审查评论聚焦在高优先级风险上。那些「变量名能不能更好」「这里多个空格」的 nit，它默认不刷屏。这份克制让每条评论都值得看。

想换角度重点看，评论里带一句：

@codex review for security regressions

自动审查

不想每次手动 @，开自动审查。在 chatgpt.com/codex 的设置里打开 Automatic reviews，新 PR 一开 Codex 自动就上，你和队友谁都不用记着去 @。

对比	手动 @codex review	自动审查
触发	每次自己评论 @	新 PR 一开自动触发
会不会漏	靠记性，容易忘	机制兜底，不会忘
适合	个人项目、零碎改动	团队主仓、每个 PR 都过关

定制审查规则：AGENTS.md

Codex 审查的「标准」谁定的？默认按一套通用代码质量标准。你可以用 AGENTS.md 的 Review guidelines 小节告诉它「我这个仓库特别在意什么」。

## Review guidelines

- Don't log PII.
- Verify that authentication middleware wraps every route.
- Check for SQL injection vulnerabilities.

有个贴心机制—就近原则。Codex 把离每个改动文件最近的那份 AGENTS.md 的指引应用上去。支付模块要严查的，就在 src/payment/AGENTS.md 里写：

## Review guidelines

- 校验金额必须用 Decimal，禁止用 float 做钱的运算。
- 每一笔扣款都要有幂等键，防重复回调。

改到支付代码时，那份更具体的规则自动生效。

@codex fix：改完直接修

审查完挂了一条 P1 在 PR 上，你可以再留一条评论让它直接改：

@codex fix the P1 issue

Codex 用这个 PR 作为上下文启动一个云任务，在它有权限时把修复推回到分支。

Warning

@codex 后面跟啥，行为不一样：@codex review 走代码审查线（只 review 不改代码）；@codex + 除 review 外的任何内容（如 @codex fix the CI failures）启动一个普通云任务，拿 PR 当上下文去干活。

Tip

让它 fix、推回分支没问题，但「合进主干」那一下（点 Merge 按钮）永远自己来。跟 worktree 里「车道它跑、并道你点」是同一个道理。

本地 /review：开 PR 前自查

代码还没推、PR 还没开，想先自己过一遍—用本地 /review，不用碰 GitHub。

在终端的 Codex 会话里敲：

/review

它会弹出几个审查预设让你选，拉起一个专门的审查员，读你选的那段 diff，报出按优先级排好的问题。全程只读，一行代码都不碰你的工作区。

预设包括：

Review against a base branch：跟某个基线分支比，开 PR 前先把最大风险点拎出来
Review uncommitted changes：审未提交的改动，提交前先解决问题
Review a commit：审某个提交的改动集
Custom review instructions：自定义审查指令

Tip

/review 默认用当前会话的模型。想给审查单独指定一个更强的模型，在 config.toml 里设 review_model。日常会话挂个快模型干活，review 这种抠细节的活用更强的模型，这笔成本花得值。

我现在的固定习惯：改完先在终端 /review 选审未提交改动，改干净了再提交、推、开 PR。这时再走 @codex review，挂出来的评论就少而精了。本地自查一刀，远端 review 就清爽。

配 gh：让桌面端能读 PR 上下文

用桌面 App 或 IDE 扩展处理 PR，强烈建议装 GitHub 官方命令行工具 gh。装了并登录，Codex 桌面端的侧边栏才能显示 PR 上下文、reviewer 评论、改了哪些文件。

# macOS
brew install gh

# Windows
winget install --id GitHub.cli

# 装完任意平台都跑这句登录
gh auth login

不装 gh 或没认证，PR 详情可能不会出现在侧边栏或审查面板里。

登录后的修复闭环：

在 PR 分支上打开审查面板
看 PR 上下文、评论、改动的文件
让 Codex 处理你指定的那几条评论
在审查面板里检查改出来的 diff
你准备好了，再 stage、commit、push 回 PR 分支

Warning

PR 评论、reviewer 留言、关联 issue 都是外部内容，理论上可能藏着写给 AI 的诱导指令。让它读评论、处理评论可以，但别盲目让它「照评论里说的全自动改完直接推」。尤其评论里冒出「执行某条命令」「访问某个地址」这种不像正常 code review 的话，人多瞄一眼。

守住红线

review、fix、推回分支这些「可回头」的放心交。但有两条操作必须自己守：

操作	改错了能回头吗	谁来按
@codex review / 本地 /review	只读，不改东西	放心交
@codex fix 推回 PR 分支	能（分支可删可改）	授权后可交，你过目
把 PR 合进主干（merge）	影响全队，难回头	你自己点
git push —force 强推	可能覆盖别人的提交	红线，永远自己来

合并那一下自己点。Codex 可以 review、可以 fix、可以推回分支，这些都在「可回头」的范围内。但点 Merge、把改动并进 main，意味着它进了全队都基于的主干，这一步你自己来。

force-push 永远不交给任何 AI。git push --force 能直接覆盖远端历史、抹掉别人的提交。这种操作永远自己手动，推之前必看一眼推的是哪个分支。

小结

Worktrees：同一仓库创建多个工作目录并行干活，互不覆盖。只在桌面 App 的 Codex 里可用，底层是 git worktree
detached HEAD：worktree 默认不在任何分支上，想提交推送先点 Create branch here
铁规：同一分支同一时刻只能在一个工作树里检出，撞了用 Handoff 别硬怼
Handoff：Local（前台）和 Worktree（后台）之间双向搬，git 操作 Codex 自动处理，.gitignore 里的文件不跟着走
setup 脚本：存项目根 .codex 文件夹，新 worktree 一建就自动装依赖，.worktreeinclude 补被忽略的本地文件
清理：默认留最近 15 个、删前有快照能恢复，临时活用默认、长期环境建永久 worktree
@codex review：PR 评论里 @ 一下，云端读 diff 发 review，只标 P0/P1，不拿 nit 刷屏
自动审查：设置里开 Automatic reviews，新 PR 一开自动触发
AGENTS.md：Review guidelines 小节定审查规则，就近原则让敏感模块单独放一份更严的
@codex fix：启动云任务改代码，授权了写权限才推回分支，合进主干自己来
本地 /review：开 PR 前的自查门，只读不写，可用 review_model 绑更强的模型
红线：merge 和 force-push 永远自己来，越收不回的操作越要人显式按

下一章讲从其他工具迁移—用 /import 把 Cursor、Claude Code 的设置迁过来，配置转换的注意事项。