codex-team

Codex 团队

负责人负责协调，Codex Agent 负责执行。每个 Agent 只处理一项明确的任务。团队负责人会在启动 Agent 之前避免文件冲突——协调者本身就是锁管理器。

对于 Claude 运行时的功能兼容性（agents/hooks/worktree/settings），当此技能回退到 /swarm 时，请使用共享契约 skills/shared/references/claude-code-latest-features.md；该契约在本地镜像为 references/claude-code-latest-features.md。

适用场景

• 你有 2 项或更多任务（错误修复、实现、重构）
• 任务范围明确，指令清晰
• 你希望 Codex 执行任务时具有可预测的隔离性
• 你可能使用 Claude 或 Codex 运行时（技能会自动选择后端）

不适用场景： 任务需要紧密的共享状态协调。对于依赖关系繁多的分波次编排，请使用 /swarm。

后端选择（必须）

按以下顺序选择后端：

1. spawn_agent 可用 -> Codex 实验性子 Agent（首选）
2. Codex CLI 可用 -> 通过 Bash 使用 Codex CLI（codex exec ...）
3. skill 工具为只读（OpenCode） -> OpenCode 子 Agent——task(subagent_type="general", prompt="<task prompt>")
4. 以上均不适用 -> 回退到 /swarm

执行前检查（仅限 CLI 后端）

# REQUIRED before spawning with Codex CLI backend
if ! which codex > /dev/null 2>&1; then
  echo "Codex CLI not found. Install: npm i -g @openai/codex"
  # Fallback: use /swarm
fi

# Model availability test (uses the user's configured Codex default)
if ! codex exec --full-auto -C "$(pwd)" "echo ok" > /dev/null 2>&1; then
  echo "Default Codex model unavailable. Falling back to /swarm."
fi

标准命令

codex exec --full-auto -C "$(pwd)" -o <output-file> "<prompt>"

使用用户默认的 Codex 模型。只有在有意指定某个模型时，才在 -C 前添加 -m "<model>"。

标志顺序：--full-auto -> -C -> -o -> 提示词（只有在覆盖默认模型时，才在 -C 前插入 -m）。

有效标志： --full-auto、-m、-C、-o、--json、--output-schema、--add-dir、-s

不要使用： -q、--quiet（不存在）

跨项目任务

当任务涉及多个仓库/目录时，使用 --add-dir 授予访问权限：

codex exec --full-auto -C "$(pwd)" --add-dir /path/to/other/repo -o output.md "prompt"

--add-dir 标志可重复使用，以添加多个目录。

进度监控（可选）

添加 --json，将 JSONL 事件流式输出到 stdout，以便实时监控：

codex exec --full-auto --json -C "$(pwd)" -o output.md "prompt" 2>/dev/null

关键事件：

• turn.started / turn.completed — 跟踪进度
• turn.completed 包含 token usage 字段
• 60 秒内没有事件 → Agent 可能已卡住

沙箱级别

使用 -s 控制沙箱：

级别	标志	使用场景
只读	-s read-only	评审者、审查者（无需写入文件）
工作区写入	-s workspace-write	与 --full-auto 搭配时的默认设置
完全访问	-s danger-full-access	仅限已由外部沙箱隔离的环境

对于代码审查和分析任务，优先使用 -s read-only，而不是 --full-auto。

执行

步骤 1：定义任务

将工作拆分为明确的任务。每项任务对应一个 Codex Agent（除非合并处理）。

对于需要可互换的工作者、文件预留、会话邮件、重复执行或基于 tmux 协调的多 Agent 工作，请在派发之前阅读 references/fungible-agent-coordination.md。

步骤 2：分析文件目标（必需）

启动 Agent 之前，确定每项任务将编辑哪些文件。 Codex Agent 以无头模式运行——无法协商锁，也无法等待轮次。所有冲突防范都必须在此处完成。

针对每项任务，列出目标文件。然后采用适当的策略：

文件重叠情况	策略	操作
所有任务都涉及同一文件	合并	将所有修复合并为一个 Agent 处理
部分任务涉及相同文件	多波次	涉及共享文件的任务按波次顺序执行
没有重叠	并行	一次性启动所有 Agent

# Decision logic (team lead performs this mentally):

tasks = [
  {name: "fix spec_path",    files: ["cmd/zeus.go"]},
  {name: "remove beads field", files: ["cmd/zeus.go"]},
  {name: "fix dispatch counter", files: ["cmd/zeus.go"]},
]

# All touch zeus.go → MERGE into 1 agent

tasks = [
  {name: "fix auth bug",     files: ["pkg/auth.go"]},
  {name: "add rate limiting", files: ["pkg/auth.go", "pkg/middleware.go"]},
  {name: "update config",    files: ["internal/config.go"]},
]

# Task 1 and 2 share auth.go → MULTI-WAVE (1+3 parallel, then 2)
# Task 3 is independent → runs in Wave 1 alongside Task 1

tasks = [
  {name: "fix auth",    files: ["pkg/auth.go"]},
  {name: "fix config",  files: ["internal/config.go"]},
  {name: "fix logging", files: ["pkg/log.go"]},
]

# No overlap → PARALLEL (all 3 at once)

第 3 步：启动 Agent

策略：并行（文件无重叠）

Codex 子 Agent 后端（首选）：

spawn_agent(message="Fix the null check in pkg/auth.go:validateToken around line 89...")
spawn_agent(message="Add timeout field to internal/config.go:Config struct...")
spawn_agent(message="Fix log rotation in pkg/log.go:rotateLogFile...")

Codex CLI 后端：

Bash(command='codex exec --full-auto -C "$(pwd)" -o .agents/codex-team/auth-fix.md "Fix the null check in pkg/auth.go:validateToken around line 89..."', run_in_background=true)
Bash(command='codex exec --full-auto -C "$(pwd)" -o .agents/codex-team/config-fix.md "Add timeout field to internal/config.go:Config struct..."', run_in_background=true)
Bash(command='codex exec --full-auto -C "$(pwd)" -o .agents/codex-team/logging-fix.md "Fix log rotation in pkg/log.go:rotateLogFile..."', run_in_background=true)

策略：合并（同一文件）

将所有修复合并到一个 Agent 提示词中：

spawn_agent(message="Fix these 3 issues in cmd/zeus.go: (1) rename spec_path to spec_location in QUEST_REQUEST payload (2) remove beads field (3) fix dispatch counter increment location")

# CLI equivalent:
Bash(command='codex exec --full-auto -C "$(pwd)" -o .agents/codex-team/zeus-fixes.md \
  "Fix these 3 issues in cmd/zeus.go: \
   (1) Line 245: rename spec_path to spec_location in QUEST_REQUEST payload \
   (2) Line 250: remove the spurious beads field from the payload \
   (3) Line 196: fix dispatch counter — increment inside the loop, not outside"', run_in_background=true)

一个 Agent，一个文件，不可能发生冲突。

策略：多轮（部分重叠）

# Wave 1: non-overlapping tasks (sub-agent backend)
spawn_agent(message='Fix null check in pkg/auth.go:89...')
spawn_agent(message='Add timeout to internal/config.go...')

# Wait for Wave 1 (sub-agent backend)
wait(ids=["<id-1>", "<id-2>"], timeout_ms=120000)

# Wave 1: non-overlapping tasks (CLI backend)
Bash(command='codex exec ... -o .agents/codex-team/auth-fix.md "Fix null check in pkg/auth.go:89..."', run_in_background=true)
Bash(command='codex exec ... -o .agents/codex-team/config-fix.md "Add timeout to internal/config.go..."', run_in_background=true)

# Wait for Wave 1
TaskOutput(task_id="<id-1>", block=true, timeout=120000)
TaskOutput(task_id="<id-2>", block=true, timeout=120000)

# Read Wave 1 results — understand what changed
Read(.agents/codex-team/auth-fix.md)
git diff pkg/auth.go

# Wave 2: task that shares files with Wave 1 (sub-agent backend)
spawn_agent(message='Add rate limiting to pkg/auth.go and pkg/middleware.go. Note: validateToken now has a null check at line 89. Build on current file state.')

# Wave 2: CLI backend equivalent
Bash(command='codex exec ... -o .agents/codex-team/rate-limit.md \
  "Add rate limiting to pkg/auth.go and pkg/middleware.go. \
   Note: pkg/auth.go was recently modified — the validateToken function now has a null check at line 89. \
   Build on the current state of the file."', run_in_background=true)

TaskOutput(task_id="<id-3>", block=true, timeout=120000)

团队负责人整合第 1 轮的结果，并将相关上下文注入第 2 轮的提示词。不要直接提供原始差异，而应说明更改了什么，以及这对下一项任务为何重要。

第 4 步：等待完成

# Sub-agent backend:
wait(ids=["<id-1>", "<id-2>", "<id-3>"], timeout_ms=120000)

# CLI backend:
TaskOutput(task_id="<id-1>", block=true, timeout=120000)
TaskOutput(task_id="<id-2>", block=true, timeout=120000)
TaskOutput(task_id="<id-3>", block=true, timeout=120000)

第 5 步：验证结果

• 读取 .agents/codex-team/ 中的输出文件
• 检查 git diff，查看每个 Agent 所做的更改
• 如适用，运行测试
• 对于多轮策略：验证第 2 轮 Agent 是否基于第 1 轮的更改正确完成工作

输出目录

mkdir -p .agents/codex-team

输出文件：.agents/codex-team/<task-name>.md

提示词编写指南

优质的 Codex 提示词应当具体且完整：

# GOOD: Specific file, line, exact change
"Fix in cmd/zeus.go line 245: rename spec_path to spec_location in the QUEST_REQUEST payload struct"

# BAD: Vague, requires exploration
"Fix the spec path issue somewhere in the codebase"

在每条提示词中包含：

• 确切的文件路径
• 行号或函数名
• 要更改的内容及原因
• 任何限制（不要修改其他文件、保持 API 兼容性）

对于多轮策略中第 2 轮及之后的提示词，还应包含：

• 前几轮做了哪些更改（概述，不要提供原始差异）
• 前几轮编辑后共享文件的当前状态

限制

• Agent 数量上限： 每轮 6 个（合理使用资源）
• 超时： 每个 Agent 默认 2 分钟。对于较大的任务，可通过 timeout 参数延长
• 轮数上限： 建议最多 3 轮。如需更多轮，请重新考虑任务拆分方式

后备方案

如果 Codex 不可用，可委派给 /swarm，它会自动选择最佳可用后端（支持消息传递、重定向和优雅关闭的原生团队，或作为最后手段的后台任务）：

Skill(skill="swarm")

注意： /codex-team 会将 Codex CLI 进程作为后台 shell 命令运行——这没有问题（它们是独立的操作系统进程）。对于 Claude Agent 编排，请使用 /swarm，它会使用运行时原生的多 Agent 原语。

快速参考

项目	值
模型	用户配置的 Codex 默认模型（使用 -m "<model>" 指定）
命令	codex exec --full-auto -C "$(pwd)" -o <file> "prompt"
输出目录	.agents/codex-team/
每轮 Agent 数量上限	建议 6 个
超时	默认 120s
策略	并行（无重叠）、合并（同一文件）、多轮（部分重叠）
后备方案	/swarm（运行时原生）

---

示例

并行执行（文件无重叠）

用户说： 使用 /codex-team 修复 auth.go、config.go 和 logging.go 中的三个错误

执行过程：

1. Agent 分析目标文件（auth.go、config.go、log.go——无重叠）
2. Agent 选择并行策略
3. Agent 启动三个 Codex Agent（如果可用则使用子 Agent，否则通过 Bash 使用 CLI）
4. 所有 Agent 同时执行，并将结果写入 .agents/codex-team/*.md
5. 团队负责人使用 git diff 和测试验证结果
6. 团队负责人将所有更改一起提交

结果： 并行修复三个错误，且没有文件冲突。

合并策略（同一文件）

用户说： 修复 zeus.go 中的三个问题：重命名字段、移除未使用的字段、修复计数器

执行过程：

1. Agent 分析目标文件（这三项任务都会修改 zeus.go）
2. Agent 选择合并策略
3. Agent 将所有三个修复合并到一条 Codex 提示词中，并附上针对具体行的说明
4. Agent 启动一个 Codex Agent，使用合并后的提示词
5. Agent 一次性完成所有三个修复
6. 团队负责人验证并提交

结果： 一个 Agent，一个文件，不可能发生冲突。

多波（部分重叠）

用户说： 修复 auth.go，为 auth.go + middleware.go 添加速率限制，更新 config.go

发生的情况：

1. Agent 识别出重叠：任务 1 和任务 2 都涉及 auth.go
2. Agent 将任务拆分为多个波次：W1 = 任务 1 + 任务 3（无重叠），W2 = 任务 2
3. Agent 并行启动第 1 波的 Agent，并等待完成
4. Agent 读取第 1 波的结果，为第 2 波综合上下文
5. Agent 启动第 2 波的 Agent，并提供更新后的文件状态上下文
6. 团队负责人在第 2 波完成后进行验证并提交

结果： 按顺序执行各波可避免冲突，并将上下文传递到后续波次。

---

故障排除

问题	原因	解决方案
找不到 Codex CLI	未安装 codex，或其不在 PATH 中	运行 npm i -g @openai/codex，或使用备用方案 /swarm
默认 Codex 模型不可用	账户/配置不匹配，或默认模型不受支持	确认 codex exec --full-auto -C "$(pwd)" "echo ok" 可以运行，或使用 -m "<model>" 指定受支持的模型
Agent 产生文件冲突	多个 Agent 编辑同一个文件	使用文件目标分析，并应用合并策略或多波策略
Agent 超时且没有输出	任务过于复杂，或提示词含糊	将任务拆分得更小，并添加具体的文件:行号说明
输出文件为空或缺失	-o 路径无效，或权限被拒绝	检查 .agents/codex-team/ 目录是否存在且可写

参考文档

• references/fungible-agent-coordination.md
• references/claude-code-latest-features.md
• ../shared/references/claude-code-latest-features.md
• references/codex-team.feature — 可执行规范：分析文件目标以划分互不重叠的范围，启动无冲突的波次，在回收结果前等待所有任务完成（soc-qk4b）