frr.dev

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
title: "Codex CLI 没有 worktrees（教你手动实现！）"
date: 2026-03-11T23:45:00+01:00
draft: false
slug: "codex-cli-worktrees-shoudong-duogongneng"
slug_en: "codex-cli-worktrees-manual-parallelism"
description: "Codex CLI 没有 --worktree 和 --tmux，但通过手动创建 git worktree 和一些小技巧，也能实现真正的并行操作。本教程详细讲解，并揭露你可能遇到的 bug。"
tags: ["codex", "openai", "git", "worktrees", "代理", "效率"]
categories: ["工具"]

translation:
  hash: ""
  last_translated: ""
  notes: |
    - "montártelo": 口语化表达，意为 "自己设置" 或 "自己动手搞定"。
    - "te la pegas": 口语化表达，意为 "失败了" 或 "碰壁了"。
    - "ñapa": 修补，草草处理的对策/临时解决方案。术语不带贬义，而是略带亲切含义。
    - "currar": 西班牙口语，意为 "工作"。
    - "ir tirando": 口语化表达，意为 "勉强过得去" 或 "凑合着过"。
    - "el ajo": 意为 "大蒜"，但在短语 "meterse en el ajo" 指 "参与其中" / "深入其中"。
    - "tela marinera": 惊叹语，意为 "了不起" 或 "不简单"。

social:
  publish: true
  scheduled_date: 2026-03-14
  platforms: ["twitter", "linkedin"]
  excerpt: "Codex CLI 没有 --worktree 或 --tmux 来实现并行操作。但通过手动 worktree 和解决共享会话 bug，就能实现真正的并行操作。本教程手把手教你。"

wordpress:
  publish: true
  categories: [1]
  tags: ["codex", "openai", "git", "worktrees", "效率"]

video:
  generate: false
  style: "educational"
---

如果你读过我之前写的 [关于 Claude Code 中 worktrees 的文章](/zh/posts/claude-code-worktrees-parallel-agents-tips/)，你应该知道这个功能的核心就是一个小小的参数：`--worktree`。执行这个参数之后，每个代理都能在一个隔离的代码仓库副本中运行。每次启动一个代理程序，就在独立的目录中操作。三个代理同时跑也互不干扰，仿佛魔术一般。

现在打开 Codex CLI，想找一下等效的参数，结果发现它根本不存在。

没有 `--worktree`。没有 `--tmux`。也没有支持自定义代理的 `isolation: worktree` 参数。而且，尽管[issue #12862](https://github.com/openai/codex/issues/12862) 在 GitHub 上已经开了很久，并且已经有人在 fork 中实现了这些功能，但官方始终没有合并代码。到目前为止，Codex CLI 还是无法原生支持多个代理并行操作。

这是否意味着无法使用 Codex 实现并行工作？答案是否定的。这只是意味着你需要自己动手 “折腾” 一下。而这件事说穿了，不过是几个 git 命令和一些预防措施。

## 计划：手动 worktrees + 每个目录运行一个 Codex

整体思路跟 Claude Code 中的方法类似，只是没有自动化功能。简单来说，就是你自己创建 worktree，自己启动代理程序，事情完了也需要自己清理。这工作听上去有点人工，但它确实管用。

```bash
# 从你的主仓库目录开始
cd ~/code/mi-proyecto

# 为每个任务创建一个 worktree
git worktree add ../mi-proyecto-feat-auth -b feature/auth
git worktree add ../mi-proyecto-fix-tests -b fix/tests-rotos
git worktree add ../mi-proyecto-refactor -b chore/refactor-db

现在你有四个目录：一个主目录和三个 worktree，每个 worktree 都是相互独立的。每个 worktree 拥有自己的分支、暂存区 (staging area) 和 HEAD，但共享仓库的元数据（.git/ 目录），其他一切隔离。

接下来，在每个 worktree 运行一个 Codex：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 终端 1
cd ../mi-proyecto-feat-auth
codex --approval-mode never --sandbox workspace-write \
  "实现 JWT 鉴权中间件，编写测试代码。"

# 终端 2
cd ../mi-proyecto-fix-tests
codex --approval-mode never --sandbox workspace-write \
  "运行测试套件，修复所有失败的测试，一直重复直到全部通过。"

# 终端 3
cd ../mi-proyecto-refactor
codex --approval-mode never --sandbox workspace-write \
  "重构数据库模块以使用连接池功能。"

三个代理，三个任务，它们互不干扰。每个 Codex 只看到自己对应的 worktree，并且只操作相应的分支。

需要注意的 bug：共享会话问题

接下来是任何官方教程都没告诉你的内容。有一个已知 bug (#11435) 存在于 Codex CLI 中：所有实例默认使用同一个会话目录 ~/.codex/。如果同时启动多个 Codex，实例会意外载入其它实例的上下文，导致会话数据混乱。

简单来说：修测试的代理会突然以为自己在做鉴权中间件，因为它读了另一个实例的会话数据。这种情况可能导致严重的执行错误。

解决办法是强制让每个代理实例使用一个单独的会话目录：

1
2
3
4
5
6
7
8
# 终端 1
CODEX_HOME=~/.codex-session-1 codex --approval-mode never --sandbox workspace-write "..."

# 终端 2
CODEX_HOME=~/.codex-session-2 codex --approval-mode never --sandbox workspace-write "..."

# 终端 3
CODEX_HOME=~/.codex-session-3 codex --approval-mode never --sandbox workspace-write "..."

如果在你的版本中 CODEX_HOME 变量不起作用（因为不同版本中这个变量名可能有所变动），可以采取更直接的办法：分别在每个 worktree 中创建一个单独的 config.toml 文件：

1
2
3
# 在每个 worktree 目录内执行
mkdir .codex
cp ~/.codex/config.toml .codex/config.toml

虽然这不优雅，更像一个“补丁”，但它确实管用。在官方解决 issue #12862 的问题之前，这是为数不多的靠谱方法。

略微自动化：脚本封装

如果你经常需要这样操作，可以写个脚本自动化这整个流程，减少手动出错的几率：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
#!/usr/bin/env bash
# codex-worktree.sh — 在独立的 worktree 上启动 Codex
set -euo pipefail

BRANCH="$1"
PROMPT="$2"
REPO_NAME=$(basename "$(pwd)")
WORKTREE_DIR="../${REPO_NAME}-${BRANCH//\//-}"
SESSION_DIR="$HOME/.codex-session-$$"

# 创建 worktree
git worktree add "$WORKTREE_DIR" -b "$BRANCH" 2>/dev/null || \
  git worktree add "$WORKTREE_DIR" "$BRANCH"

echo "→ Worktree: $WORKTREE_DIR"
echo "→ Session:  $SESSION_DIR"
echo "→ Branch:   $BRANCH"

# 使用独立会话目录启动 Codex
cd "$WORKTREE_DIR"
CODEX_HOME="$SESSION_DIR" codex \
  --approval-mode never \
  --sandbox workspace-write \
  "$PROMPT"

# 清理会话数据（worktree 保留供后续检查）
rm -rf "$SESSION_DIR"
echo "✓ 会话清理完成。Worktree 在 $WORKTREE_DIR 中，可用于后续检查与合并。"

使用方式：

1
2
./codex-worktree.sh feature/auth "实现 JWT 鉴权中间件并编写相关测试"
./codex-worktree.sh fix/tests "修复所有失败的测试"

每次调用脚本都会创建一个 worktree 和一个独立的会话目录，运行 Codex，然后在完成后清理会话数据。worktree 保留，以供稍后进行成果检查与合并。

使用 tmux：实现视觉化并行操作

如果你希望实时看到多个代理的工作情况，可以考虑使用 tmux：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# 创建一个三分屏的 tmux 会话
tmux new-session -d -s codex-parallel

# 面板 1：鉴权模块
tmux send-keys -t codex-parallel \
  "cd ../mi-proyecto-feat-auth && codex --approval-mode never --sandbox workspace-write '实现鉴权代码'" Enter

# 面板 2：修复测试
tmux split-window -h -t codex-parallel
tmux send-keys -t codex-parallel \
  "cd ../mi-proyecto-fix-tests && codex --approval-mode never --sandbox workspace-write '修复所有失败的测试用例'" Enter

# 面板 3：重构
tmux split-window -v -t codex-parallel
tmux send-keys -t codex-parallel \
  "cd ../mi-proyecto-refactor && codex --approval-mode never --sandbox workspace-write '重构数据库模块支持连接池'" Enter

# 接入 tmux 会话
tmux attach -t codex-parallel

三个面板，三个代理。虽然并不是 claude --worktree --tmux 那样一键完成，但效果一样棒。

社区工具帮助你完成

如果手动实现这一切让你觉得太累，有些社区工具已经帮我们解决了这些问题：

parallel-code：支持在分离的 worktree 中自动运行 Claude Code、Codex 和 Gemini CLI。你只需提供任务和代理类型，其余让工具帮你处理。

ccmanager：能够更高级地管理多个代理会话，同时实现 worktree 隔离。支持多种代理 CLI 工具。

这类工具虽然非官方发布，但填补了 OpenAI 的这一功能空缺。

桌面版 Codex App 已拥有（但 CLI 版还不行）

需要注意的是，桌面版 Codex 应用（2026 年 3 月发布） 已经支持原生 worktree 功能。当你创建一个新的“讨论线程”（thread）时，可以选择“Worktree 模式”。在这种模式下，自动化任务会在后台的独立 worktree 中运行。

但是，这个桌面版需要你在本地运行完整的应用。如果你是在服务器、CI 容器中工作，或者单纯更喜欢用终端，那么桌面版对你来说就没用。而 CLI 版目前还没提供相应功能。

这就像是 Git 的 GUI 工具有 worktree 功能，但命令行版本却没有。非常荒唐，但事实就是这样。

对比分析表

功能	Claude Code	Codex CLI	Codex CLI + 手动 worktrees
创建 worktree	`--worktree`（1 参数）	不支持	`git worktree add`（手动）
并行会话	`--tmux`（1 参数）	Bug #11435	tmux 手动操作 + 会话隔离
代理隔离	`isolation: worktree`	不支持	用脚本封装
自动清理	支持	不适用	手动清理（`git worktree remove`）
合并回主分支	自动完成	不适用	使用标准的 `git merge`

Claude Code 已经让 worktrees 变得完全自动化，几乎成了一个用户无感的底层细节。而在 Codex CLI 中，worktrees 则是你需要亲手设置才能使用的额外工具。

这种手动工作方式可行吗？是的。与自动化原生支持一样吗？并不一样。自动与手动之间的差距，就像自动挡与手动挡之间的差别。两种方式都能带你到达目的地，但当你用手动挡时，双手也得一直“忙碌”。

期待 issue #12862 被解决的那一天

目前来看，已经有很多用户在推动这个问题，Issue 页面中也有了不少的反馈和非官方实现。最终还是会迎来问题解决的一天。

在这之前，手动 worktrees 依然有效。虽然不够优雅，也不会自动化，但它仍然能让 Codex CLI 实现真正的并行工作——只需几个 git 命令、一些 tmux 操作, 再加上对会话共享 bug (#11435) 的足够小心，就万事俱备了。

至于为什么 Claude Code 几个月前就已经解决了这个问题，而 Codex 至今没有改进？唉，有时候，后起者的优势就在于能够抄别人的成功经验。但你得先愿意这样做。

需要注意的 bug：共享会话问题#

略微自动化：脚本封装#

使用 tmux：实现视觉化并行操作#

社区工具帮助你完成#

桌面版 Codex App 已拥有（但 CLI 版还不行）#

对比分析表#

期待 issue #12862 被解决的那一天#