codex-team

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex Team

The lead orchestrates, Codex agents execute. Each agent gets one focused task. The team lead prevents file conflicts before spawning — the orchestrator IS the lock manager.

由主导代理进行编排，Codex agents负责执行。每个代理承担一项明确聚焦的任务。团队主导代理会在生成子代理前预防文件冲突——编排器同时也是锁管理器。

When to Use

使用场景

You have 2+ tasks (bug fixes, implementations, refactors)
Tasks are well-scoped with clear instructions
You want Codex execution with predictable isolation
You may be in Claude or Codex runtime (skill auto-selects backend)

Don't use when: Tasks need tight shared-state coordination. Use

/swarm

for dependency-heavy wave orchestration.

你有2个及以上任务（bug修复、功能实现、代码重构）
任务范围清晰，指令明确
你希望Codex执行任务时具备可预测的隔离性
你可能处于Claude或Codex运行环境（技能会自动选择后端）

请勿使用的场景： 任务需要紧密的共享状态协调。对于依赖度高的多轮编排，请使用

/swarm

。

Backend Selection (MANDATORY)

后端选择（必填）

Select backend in this order:

```
spawn_agent
```
available -> Codex experimental sub-agents (preferred)
Otherwise -> Codex CLI via Bash (
```
codex exec ...
```
)

If neither is available, fall back to

/swarm

按以下顺序选择后端：

若
```
spawn_agent
```
可用 → Codex实验性子代理（优先选择）
否则 → 通过Bash调用Codex CLI（
```
codex exec ...
```
）

如果两者都不可用，则回退到

/swarm

。

Pre-Flight (CLI backend only)

预检操作（仅CLI后端需要）

undefined

undefined

REQUIRED before spawning with Codex CLI backend

使用Codex CLI后端生成代理前必须执行

if ! which codex > /dev/null 2>&1; then echo "Codex CLI not found. Install: npm i -g @openai/codex"

Fallback: use /swarm

if ! which codex > /dev/null 2>&1; then echo "未找到Codex CLI。请安装：npm i -g @openai/codex"

回退方案：使用/swarm

Model availability test

模型可用性测试

CODEX_MODEL="${CODEX_MODEL:-gpt-5.3-codex}" if ! codex exec --full-auto -m "$CODEX_MODEL" -C "$(pwd)" "echo ok" > /dev/null 2>&1; then echo "Codex model $CODEX_MODEL unavailable. Falling back to /swarm." fi

undefined

CODEX_MODEL="${CODEX_MODEL:-gpt-5.3-codex}" if ! codex exec --full-auto -m "$CODEX_MODEL" -C "$(pwd)" "echo ok" > /dev/null 2>&1; then echo "Codex模型$CODEX_MODEL不可用。将回退到/swarm。" fi

undefined

Canonical Command

标准命令

bash

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

Flag order:

--full-auto

-m

-C

-o

-> prompt. Always this order.

Valid flags:

--full-auto

-m

-C

-o

--json

--output-schema

--add-dir

-s

DO NOT USE:

-q

--quiet

(don't exist)

bash

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

参数顺序：

--full-auto

→

-m

→

-C

→

-o

→ 提示词。请严格遵循此顺序。

有效参数：

--full-auto

-m

-C

-o

--json

--output-schema

--add-dir

-s

禁止使用：

-q

--quiet

（不存在该参数）

Cross-Project Tasks

跨项目任务

When tasks span multiple repos/directories, use

--add-dir

to grant access:

bash

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

The

--add-dir

flag is repeatable for multiple additional directories.

当任务涉及多个仓库/目录时，使用

--add-dir

授予访问权限：

bash

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

--add-dir

参数可重复使用以添加多个目录。

Progress Monitoring (optional)

进度监控（可选）

Add

--json

to stream JSONL events to stdout for real-time monitoring:

bash

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

Key events:

```
turn.started
```
/
```
turn.completed
```
— track progress
```
turn.completed
```
includes token
```
usage
```
field
No events for 60s → agent likely stuck

添加

--json

参数将JSONL事件流输出到标准输出，以实现实时监控：

bash

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

关键事件：

```
turn.started
```
/
```
turn.completed
```
—— 跟踪进度
```
turn.completed
```
包含token使用量字段
60秒无事件 → 代理可能已停滞

Sandbox Levels

沙箱级别

Use

-s

to control the sandbox:

Level	Flag	Use When
Read-only	`-s read-only`	Judges, reviewers (no file writes needed)
Workspace write	`-s workspace-write`	Default with `--full-auto`
Full access	`-s danger-full-access`	Only in externally sandboxed environments

For code review and analysis tasks, prefer

-s read-only

over

--full-auto

使用

-s

参数控制沙箱权限：

级别	参数	使用场景
只读	`-s read-only`	评审、检查场景（无需写入文件）
工作区可写	`-s workspace-write`	`--full-auto` 模式下的默认设置
完全访问	`-s danger-full-access`	仅在外部沙箱环境中使用

对于代码评审和分析任务，优先使用

-s read-only

而非

--full-auto

。

Execution

执行流程

Step 1: Define Tasks

步骤1：定义任务

Break work into focused tasks. Each task = one Codex agent (unless merged).

将工作拆解为多个聚焦的任务。每个任务对应一个Codex代理（除非合并任务）。

Step 2: Analyze File Targets (REQUIRED)

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

Before spawning, identify which files each task will edit. Codex agents are headless — they can't negotiate locks or wait turns. All conflict prevention happens here.

For each task, list the target files. Then apply the right strategy:

File Overlap	Strategy	Action
All tasks touch same file	Merge	Combine into 1 agent with all fixes
Some tasks share files	Multi-wave	Shared-file tasks go sequential across waves
No overlap	Parallel	Spawn all agents at once

undefined

在生成代理前，明确每个任务将编辑哪些文件。 Codex代理是无界面的——它们无法协商锁或等待轮次。所有冲突预防操作都在此步骤完成。

为每个任务列出目标文件，然后应用对应的策略：

文件重叠情况	策略	操作
所有任务都修改同一文件	合并	将所有任务合并为一个代理，一次性完成所有修复
部分任务共享文件	多轮执行	共享文件的任务分轮次依次执行
无文件重叠	并行执行	同时生成所有代理

undefined

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"]}, ]

tasks = [ {name: "修复spec_path", files: ["cmd/zeus.go"]}, {name: "移除beads字段", files: ["cmd/zeus.go"]}, {name: "修复调度计数器", files: ["cmd/zeus.go"]}, ]

All touch zeus.go → MERGE into 1 agent

所有任务都修改zeus.go → 合并为1个代理

undefined

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"]}, ]

undefined

tasks = [ {name: "修复认证bug", files: ["pkg/auth.go"]}, {name: "添加速率限制", files: ["pkg/auth.go", "pkg/middleware.go"]}, {name: "更新配置", files: ["internal/config.go"]}, ]

Task 1 and 2 share auth.go → MULTI-WAVE (1+3 parallel, then 2)

任务1和2共享auth.go → 多轮执行（任务1和3并行，然后执行任务2）

Task 3 is independent → runs in Wave 1 alongside Task 1

任务3独立 → 与任务1在第一轮并行执行

undefined

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

undefined

tasks = [ {name: "修复认证", files: ["pkg/auth.go"]}, {name: "修复配置", files: ["internal/config.go"]}, {name: "修复日志", files: ["pkg/log.go"]}, ]

No overlap → PARALLEL (all 3 at once)

无文件重叠 → 并行执行（3个任务同时进行）

undefined

undefined

Step 3: Spawn Agents

步骤3：生成代理

Strategy: Parallel (no file overlap)

Codex sub-agent backend (preferred):

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 backend:

Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -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 -m "gpt-5.3-codex" -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 -m "gpt-5.3-codex" -C "$(pwd)" -o .agents/codex-team/logging-fix.md "Fix log rotation in pkg/log.go:rotateLogFile..."', run_in_background=true)

Strategy: Merge (same file)

Combine all fixes into a single agent prompt:

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")

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

Codex子代理后端（优先选择）：

spawn_agent(message="修复pkg/auth.go:validateToken函数中第89行左右的空值检查...")
spawn_agent(message="为internal/config.go:Config结构体添加timeout字段...")
spawn_agent(message="修复pkg/log.go:rotateLogFile函数中的日志轮转问题...")

Codex CLI后端：

Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o .agents/codex-team/auth-fix.md "修复pkg/auth.go:validateToken函数中第89行左右的空值检查..."', run_in_background=true)
Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o .agents/codex-team/config-fix.md "为internal/config.go:Config结构体添加timeout字段..."', run_in_background=true)
Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o .agents/codex-team/logging-fix.md "修复pkg/log.go:rotateLogFile函数中的日志轮转问题..."', run_in_background=true)

策略：合并任务（同一文件）

将所有修复内容合并到单个代理提示词中：

spawn_agent(message="修复cmd/zeus.go中的3个问题：(1) 将QUEST_REQUEST payload中的spec_path重命名为spec_location (2) 移除beads字段 (3) 修复调度计数器的递增位置")

CLI equivalent:

CLI等效命令：

Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -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)


One agent, one file, no conflicts possible.

**Strategy: Multi-wave (partial overlap)**

Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o .agents/codex-team/zeus-fixes.md
"修复cmd/zeus.go中的3个问题：
(1) 第245行：将QUEST_REQUEST payload中的spec_path重命名为spec_location
(2) 第250行：移除多余的beads字段
(3) 第196行：修复调度计数器——将递增操作移到循环内部"', run_in_background=true)


一个代理处理一个文件，完全避免冲突。

**策略：多轮执行（部分文件重叠）**

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...')

spawn_agent(message='修复pkg/auth.go第89行的空值检查...') spawn_agent(message='为internal/config.go添加timeout字段...')

Wait for Wave 1 (sub-agent backend)

等待第一轮完成（子代理后端）

wait(ids=["<id-1>", "<id-2>"], timeout_ms=120000)

Wave 1: non-overlapping tasks (CLI backend)

第一轮：非重叠任务（CLI后端）

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)

Bash(command='codex exec ... -o .agents/codex-team/auth-fix.md "修复pkg/auth.go第89行的空值检查..."', run_in_background=true) Bash(command='codex exec ... -o .agents/codex-team/config-fix.md "为internal/config.go添加timeout字段..."', 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.')

spawn_agent(message='为pkg/auth.go和pkg/middleware.go添加速率限制。注意：validateToken函数第89行现在有空值检查。基于当前文件状态进行修改。')

Wave 2: CLI backend equivalent

第二轮：CLI后端等效命令

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)


The team lead synthesizes Wave 1 results and injects relevant context into Wave 2 prompts. Don't dump raw diffs — describe what changed and why it matters for the next task.

Bash(command='codex exec ... -o .agents/codex-team/rate-limit.md
"为pkg/auth.go和pkg/middleware.go添加速率限制。
注意：pkg/auth.go最近已修改——validateToken函数第89行现在有空值检查。
基于文件的当前状态进行修改。"', run_in_background=true)

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


团队主导代理会综合第一轮的结果，并将相关上下文注入到第二轮的提示词中。不要直接粘贴原始diff——总结修改内容及其对后续任务的影响。

Step 4: Wait for Completion

步骤4：等待完成

undefined

undefined

Sub-agent backend:

子代理后端：

wait(ids=["<id-1>", "<id-2>", "<id-3>"], timeout_ms=120000)

CLI backend:

CLI后端：

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)

undefined

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)

undefined

Step 5: Verify Results

步骤5：验证结果

Read output files from
```
.agents/codex-team/
```
Check
```
git diff
```
for changes made by each agent
Run tests if applicable
For multi-wave: verify Wave 2 agents built correctly on Wave 1 changes

读取
```
.agents/codex-team/
```
目录下的输出文件
通过
```
git diff
```
检查每个代理的修改内容
如有需要，运行测试
对于多轮执行：验证第二轮代理是否基于第一轮的修改正确完成任务

Output Directory

输出目录

mkdir -p .agents/codex-team

Output files:

.agents/codex-team/<task-name>.md

mkdir -p .agents/codex-team

输出文件路径：

.agents/codex-team/<task-name>.md

Prompt Guidelines

提示词指南

Good Codex prompts are specific and self-contained:

undefined

优秀的Codex提示词应具体且自包含：

undefined

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"

"修复cmd/zeus.go第245行：将QUEST_REQUEST payload结构体中的spec_path重命名为spec_location"

BAD: Vague, requires exploration

糟糕示例：模糊不清，需要额外探索

"Fix the spec path issue somewhere in the codebase"


Include in each prompt:
- Exact file path(s)
- Line numbers or function names
- What to change and why
- Any constraints (don't touch other files, preserve API compatibility)

For multi-wave Wave 2+ prompts, also include:
- What changed in prior waves (summarized, not raw diffs)
- Current state of shared files after prior edits

"修复代码库中与spec路径相关的问题"


每个提示词应包含：
- 精确的文件路径
- 行号或函数名
- 修改内容及原因
- 任何约束条件（如不要修改其他文件、保持API兼容性）

对于多轮执行的第二轮及以后的提示词，还应包含：
- 前一轮的修改总结（非原始diff）
- 共享文件修改后的当前状态

Limits

限制条件

Max agents: 6 per wave (resource-reasonable)
Timeout: 2 minutes default per agent. Increase with
```
timeout
```
param for larger tasks
Max waves: 3 recommended. If you need more, reconsider task decomposition

最大代理数： 每轮最多6个（考虑资源合理性）
超时时间： 每个代理默认2分钟。对于大型任务，可通过
```
timeout
```
参数延长
最大轮次： 建议不超过3轮。如果需要更多轮次，请重新考虑任务拆分方式

Team Runner Backend (Headless Orchestration)

Team Runner后端（无界面编排）

For headless batch execution of multiple Codex agents with structured output, use the team-runner script. This is the recommended backend when you need deterministic orchestration without interactive sessions.

对于需要无界面批量执行多个Codex代理并生成结构化输出的场景，使用team-runner脚本。当你需要确定性编排且无需交互会话时，这是推荐的后端方案。

When to Use Team Runner

Team Runner使用场景

Headless CI/CD or automation contexts
Batch execution where all agents run from a single spec file
When you need structured JSONL event monitoring and token tracking
When you need retry logic and consolidated reporting

无界面CI/CD或自动化环境
所有代理从单个配置文件批量执行的场景
需要结构化JSONL事件监控和token使用跟踪的场景
需要重试逻辑和统一报告的场景

Team Spec Format

Team配置文件格式

Create a JSON spec file conforming to

lib/schemas/team-spec.json

json

{
  "team_id": "my-team-001",
  "repo_path": "/path/to/repo",
  "agents": [
    {
      "name": "fix-auth",
      "prompt": "Fix the null check in pkg/auth.go:validateToken around line 89",
      "files": ["pkg/auth.go"],
      "output_file": "auth-fix.json",
      "sandbox_level": "workspace-write"
    },
    {
      "name": "fix-config",
      "prompt": "Add timeout field to internal/config.go:Config struct",
      "files": ["internal/config.go"],
      "output_file": "config-fix.json",
      "sandbox_level": "read-only"
    }
  ]
}

创建符合

lib/schemas/team-spec.json

规范的JSON配置文件：

json

{
  "team_id": "my-team-001",
  "repo_path": "/path/to/repo",
  "agents": [
    {
      "name": "fix-auth",
      "prompt": "修复pkg/auth.go:validateToken函数第89行左右的空值检查",
      "files": ["pkg/auth.go"],
      "output_file": "auth-fix.json",
      "sandbox_level": "workspace-write"
    },
    {
      "name": "fix-config",
      "prompt": "为internal/config.go:Config结构体添加timeout字段",
      "files": ["internal/config.go"],
      "output_file": "config-fix.json",
      "sandbox_level": "read-only"
    }
  ]
}

Running

运行方式

bash

undefined

bash

undefined

Execute team

执行团队任务

bash lib/scripts/team-runner.sh path/to/team-spec.json

Dry run (shows commands without executing)

试运行（仅显示命令不执行）

TEAM_RUNNER_DRY_RUN=1 bash lib/scripts/team-runner.sh path/to/team-spec.json

undefined

TEAM_RUNNER_DRY_RUN=1 bash lib/scripts/team-runner.sh path/to/team-spec.json

undefined

Components

组件说明

Component	Path	Purpose
Team runner	`lib/scripts/team-runner.sh`	Orchestrator: pre-flight, spawn, validate, report
Stream watcher	`lib/scripts/watch-codex-stream.sh`	JSONL event monitor with idle timeout detection
Team spec schema	`lib/schemas/team-spec.json`	Input validation schema
Worker output schema	`lib/schemas/worker-output.json`	Structured output schema (compatible with `--output-schema` )

组件	路径	用途
Team Runner	`lib/scripts/team-runner.sh`	编排器：预检、生成代理、验证、生成报告
流监控器	`lib/scripts/watch-codex-stream.sh`	JSONL事件监控，支持空闲超时检测
Team配置文件 schema	`lib/schemas/team-spec.json`	输入验证规范
工作输出 schema	`lib/schemas/worker-output.json`	结构化输出规范（兼容 `--output-schema` 参数）

Features

功能特性

Pre-flight checks: Validates codex, jq, git availability; sets
```
BEADS_NO_DAEMON=1
```
JSONL event watching: Monitors
```
turn.completed
```
events, tracks token usage, detects idle agents
Retry logic: Up to 3 attempts per failed agent with context injection

Sandbox mapping:

workspace-write

--full-auto

read-only

-s read-only

full-access

-s danger-full-access

Consolidated reporting: Generates
```
team-report.md
```
with per-agent status, tokens, duration

预检检查： 验证codex、jq、git是否可用；设置
```
BEADS_NO_DAEMON=1
```
JSONL事件监控： 监控
```
turn.completed
```
事件，跟踪token使用量，检测代理停滞
重试逻辑： 每个失败的代理最多重试3次，并注入上下文信息

沙箱映射：

workspace-write

→

--full-auto

，

read-only

→

-s read-only

，

full-access

→

-s danger-full-access

统一报告： 生成
```
team-report.md
```
，包含每个代理的状态、token使用量、执行时长

Environment Variables

环境变量

Variable	Default	Description
`CODEX_MODEL`	`gpt-5.3-codex`	Model for all agents
`CODEX_IDLE_TIMEOUT`	`60`	Seconds before idle timeout (exit 2)
`TEAM_RUNNER_MAX_AGENTS`	`6`	Max concurrent agents
`TEAM_RUNNER_DRY_RUN`	unset	Set to `1` for dry run

变量	默认值	说明
`CODEX_MODEL`	`gpt-5.3-codex`	所有代理使用的模型
`CODEX_IDLE_TIMEOUT`	`60`	空闲超时时间（秒），超时后退出（错误码2）
`TEAM_RUNNER_MAX_AGENTS`	`6`	最大并发代理数
`TEAM_RUNNER_DRY_RUN`	未设置	设置为 `1` 启用试运行模式

Output

输出结果

Results are written to

.agents/teams/<team_id>/

```
<agent-name>/output.json
```
— Agent output artifact
```
<agent-name>/events.jsonl
```
— Raw JSONL event stream
```
<agent-name>/status.json
```
— Watcher status (tokens, duration, exit code)
```
team-report.md
```
— Consolidated team report

结果将写入

.agents/teams/<team_id>/

```
<agent-name>/output.json
```
—— 代理输出产物
```
<agent-name>/events.jsonl
```
—— 原始JSONL事件流
```
<agent-name>/status.json
```
—— 监控状态（token使用量、时长、退出码）
```
team-report.md
```
—— 团队任务统一报告

Fallback

回退方案

If Codex is unavailable, use

/swarm

with Claude-native Task tool agents:

Task(description="Fix task 1", subagent_type="general-purpose", run_in_background=true, prompt="...")

如果Codex不可用，使用

/swarm

结合Claude原生Task工具代理：

Task(description="修复任务1", subagent_type="general-purpose", run_in_background=true, prompt="...")

Quick Reference

快速参考

Item	Value
Model	`gpt-5.3-codex`
Command	`codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o <file> "prompt"`
Output dir	`.agents/codex-team/`
Max agents/wave	6 recommended
Timeout	120s default
Strategies	Parallel (no overlap), Merge (same file), Multi-wave (partial overlap)
Fallback	`/swarm` (runtime-native)

项	值
模型	`gpt-5.3-codex`
命令	`codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o <file> "prompt"`
输出目录	`.agents/codex-team/`
每轮最大代理数	建议6个
超时时间	默认120秒
策略	并行执行（无文件重叠）、合并任务（同一文件）、多轮执行（部分文件重叠）
回退方案	`/swarm` （原生运行时）

Examples

示例

Parallel Execution (No File Overlap)

并行执行（无文件重叠）

User says: Fix three bugs in auth.go, config.go, and logging.go using

/codex-team

What happens:

Agent analyzes file targets (auth.go, config.go, log.go — no overlap)
Agent selects PARALLEL strategy
Agent spawns three Codex agents (sub-agents if available, else CLI via Bash)
All agents execute simultaneously, write to
```
.agents/codex-team/*.md
```
Team lead verifies results with
```
git diff
```
and tests
Team lead commits all changes together

Result: Three bugs fixed in parallel with zero file conflicts.

用户需求： 使用

/codex-team

修复auth.go、config.go和logging.go中的三个bug

执行流程：

代理分析目标文件（auth.go、config.go、log.go——无重叠）
代理选择并行执行策略
代理生成三个Codex代理（优先使用子代理，否则通过Bash调用CLI）
所有代理同时执行，输出文件写入
```
.agents/codex-team/*.md
```
团队主导代理通过
```
git diff
```
和测试验证结果
团队主导代理一次性提交所有修改

结果： 三个bug并行修复，无任何文件冲突。

Merge Strategy (Same File)

合并策略（同一文件）

User says: Fix three issues in zeus.go: rename field, remove unused field, fix counter

What happens:

Agent analyzes file targets (all three tasks touch zeus.go)
Agent selects MERGE strategy
Agent combines all three fixes into a single Codex prompt with line-specific instructions
Agent spawns ONE Codex agent with merged prompt
Agent completes all three fixes in one pass
Team lead verifies and commits

Result: One agent, one file, no conflicts possible.

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

执行流程：

代理分析目标文件（三个任务都修改zeus.go）
代理选择合并策略
代理将三个修复内容合并为一个包含行号具体指令的Codex提示词
代理生成一个Codex代理执行合并后的任务
代理一次性完成三个修复
团队主导代理验证并提交修改

结果： 一个代理处理一个文件，完全避免冲突。

Multi-Wave (Partial Overlap)

多轮执行（部分文件重叠）

User says: Fix auth.go, add rate limiting to auth.go + middleware.go, update config.go

What happens:

Agent identifies overlap: tasks 1 and 2 both touch auth.go
Agent decomposes into waves: W1 = task 1 + task 3 (non-overlapping), W2 = task 2
Agent spawns Wave 1 agents in parallel, waits for completion
Agent reads Wave 1 results, synthesizes context for Wave 2
Agent spawns Wave 2 agent with updated file-state context
Team lead validates and commits after Wave 2

Result: Sequential wave execution prevents conflicts, context flows forward.

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

执行流程：

代理识别重叠情况：任务1和2都修改auth.go
代理拆分为多轮：第一轮=任务1+任务3（无重叠），第二轮=任务2
代理并行生成第一轮的两个代理，等待完成
代理读取第一轮结果，为第二轮生成上下文信息
代理使用更新后的文件状态上下文生成第二轮代理
团队主导代理在第二轮完成后验证并提交修改

结果： 分轮次顺序执行避免了冲突，上下文信息顺利传递。

Troubleshooting

故障排除

Problem	Cause	Solution
Codex CLI not found	`codex` not installed or not on PATH	Run `npm i -g @openai/codex` or use fallback `/swarm`
Model `gpt-5.3-codex` unavailable	ChatGPT account, not API account	Use API account or switch to `gpt-4o`
Agents produce file conflicts	Multiple agents editing same file	Use file-target analysis and apply merge or multi-wave strategy
Agent timeout with no output	Task too complex or vague prompt	Break into smaller tasks, add specific file:line instructions
Output files empty or missing	`-o` path invalid or permission denied	Check `.agents/codex-team/` directory exists and is writable

问题	原因	解决方案
未找到Codex CLI	`codex` 未安装或未在PATH中	执行 `npm i -g @openai/codex` 安装，或使用回退方案 `/swarm`
模型 `gpt-5.3-codex` 不可用	使用的是ChatGPT账号而非API账号	使用API账号，或切换为 `gpt-4o`
代理产生文件冲突	多个代理修改同一文件	执行目标文件分析，应用合并或多轮执行策略
代理超时且无输出	任务过于复杂或提示词模糊	将任务拆分为更小的子任务，添加具体的文件:行号指令
输出文件为空或丢失	`-o` 路径无效或无写入权限	检查 `.agents/codex-team/` 目录是否存在且可写入