codex-subagent

Codex 子 Agent 技能

派生自主子 Agent，分担上下文密集型工作。子 Agent 消耗自己的 token，只返回最终结果。

黄金法则： 如果任务及其中间工作会向父级上下文增加 3,000 个或更多 token → 使用子 Agent。

智能提示

重要：父 Agent 必须为子 Agent 提供完成任务所需的关键信息。

优质提示原则

1. 包含相关背景 - 为子 Agent 提供充分的上下文
2. 明确具体 - 清楚说明约束、要求和输出格式
3. 提供方向 - 指明要查找的位置和优先参考的来源
4. 定义成功标准 - 说明完整答案应包含什么

示例

❌ 不佳：“研究身份验证”

✅ 良好：“研究此 Next.js 代码库中的身份验证。重点关注：1）会话管理策略（JWT 还是会话 Cookie）；2）身份验证提供程序集成（NextAuth、Clerk 等）；3）受保护路由模式。检查 /app、/lib/auth 和中间件文件。返回架构摘要并附上代码示例。”

❌ 不佳：“搜索 Codex SDK”

✅ 良好：“查找最新的 Codex SDK 文档并总结主要更新。重点关注：1）安装/快速入门；2）核心 API 方法和参数；3）重大变更或弃用内容。优先参考 OpenAI 官方文档和发行说明。返回简明摘要并附上引用。”

❌ 不佳：“查找 API 端点”

✅ 良好：“查找此 Express.js 应用中的所有 REST API 端点。检查 /routes、/api 和 /controllers 目录。记录每个端点的：方法（GET/POST 等）、路径、身份验证要求、请求/响应架构。以 Markdown 表格返回。”

提示模板

[TASK CONTEXT]
You are researching/analyzing [SPECIFIC TOPIC] in [LOCATION/CODEBASE/DOMAIN].

[OBJECTIVES]
Your goals:
1. [1st objective with specifics]
2. [2nd objective]
3. [3rd objective if needed]

[CONSTRAINTS]
- Focus on: [specific areas/files/sources]
- Prioritize: [what matters most]
- Ignore: [what to skip]

[OUTPUT FORMAT]
Return: [exactly what format parent needs]

[SUCCESS CRITERIA]
Complete when: [specific conditions met]

模型选择

使用 Mini 模型（gpt-5.1-codex-mini + medium）

纯搜索 - 收集信息后无需进行其他工作。

Bash（Linux/macOS）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' \
  "Search web for [TOPIC] and summarize findings"

PowerShell（Windows）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' `
  "Search web for [TOPIC] and summarize findings"

继承父级模型 + 推理能力

多步骤工作流 - 搜索 + 分析/重构/生成：

Bash（Linux/macOS）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "Find auth files THEN analyze security patterns and propose improvements"

PowerShell（Windows）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "Find auth files THEN analyze security patterns and propose improvements"

决策逻辑

Is task PURELY search/gather?
├─ YES: Any work after gathering?
│  ├─ NO → mini model
│  └─ YES → inherit parent
└─ NO → inherit parent

基本用法

Bash（Linux/macOS）

# Get parent session settings (respects active profile; falls back to top-level)
# NOTE: codex-parent-settings.sh prints two lines; use mapfile to avoid empty REASONING.
mapfile -t _settings < <(scripts/codex-parent-settings.sh)
MODEL="${_settings[0]}"
REASONING="${_settings[1]}"

# Spawn subagent (inherit parent)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "DETAILED_PROMPT_WITH_CONTEXT"

# Safer prompt construction (no backticks / command substitution)
PROMPT=$(cat <<'EOF'
[TASK CONTEXT]
You are analyzing /path/to/repo.

[OBJECTIVES]
1. Do X
2. Do Y

[OUTPUT FORMAT]
Return: path - purpose
EOF
)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "$PROMPT"

# Pure search (use mini)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' \
  "SEARCH_ONLY_PROMPT"

# JSON output for parsing
codex exec --dangerously-bypass-approvals-and-sandbox --json "PROMPT" | jq -r 'select(.event=="turn.completed") | .content'

PowerShell（Windows）

# Get parent session settings (respects active profile; falls back to top-level)
$scriptPath = Join-Path $env:USERPROFILE ".codex\skills\codex-subagent\scripts\codex-parent-settings.ps1"
$settings = & $scriptPath
$MODEL = $settings[0]
$REASONING = $settings[1]

# Spawn subagent (inherit parent)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "DETAILED_PROMPT_WITH_CONTEXT"

# Use here-string for multi-line prompts (avoids escaping issues)
$PROMPT = @'
[TASK CONTEXT]
You are analyzing /path/to/repo.

[OBJECTIVES]
1. Do X
2. Do Y

[OUTPUT FORMAT]
Return: path - purpose
'@

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  $PROMPT

# Pure search (use mini)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' `
  "SEARCH_ONLY_PROMPT"

# Method 1 (Recommended): Use -o to output directly to file
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  -o output.txt "PROMPT"
$content = Get-Content -Path output.txt -Raw

# Method 2: Parse JSONL event stream
$jsonl = codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --json "PROMPT"
$events = $jsonl -split "`n" | Where-Object { $_ } | ForEach-Object { $_ | ConvertFrom-Json }
$content = $events |
    Where-Object -Property type -EQ "item.completed" |
    Where-Object { $_.item.type -eq "agent_message" } |
    Select-Object -ExpandProperty item |
    Select-Object -ExpandProperty text

并行子 Agent（最多 5 个）

为相互独立的任务派生多个子 Agent：

Bash（Linux/macOS）

# Research different topics simultaneously
codex exec --dangerously-bypass-approvals-and-sandbox -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" "Research topic A..." &
codex exec --dangerously-bypass-approvals-and-sandbox -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" "Research topic B..." &
wait

PowerShell（Windows）

使用 PowerShell Jobs 并行执行，并通过 -o 将输出写入单独的文件：

# Parallel execution with file output
$job1 = Start-Job -ScriptBlock {
    param($m, $r, $out)
    codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
      -m $m -c "model_reasoning_effort=`"$r`"" -o $out "Research topic A..."
} -ArgumentList $MODEL, $REASONING, "output1.txt"

$job2 = Start-Job -ScriptBlock {
    param($m, $r, $out)
    codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
      -m $m -c "model_reasoning_effort=`"$r`"" -o $out "Research topic B..."
} -ArgumentList $MODEL, $REASONING, "output2.txt"

# Wait for all jobs to complete
$job1, $job2 | Wait-Job | Remove-Job

# Read results
$result1 = Get-Content -Path output1.txt -Raw
$result2 = Get-Content -Path output2.txt -Raw

输出处理

Codex CLI 提供两种捕获输出的方法：

方法 1：-o 参数（推荐）

使用 -o / --output-last-message 将最终消息直接写入文件：

Bash（Linux/macOS）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  -o result.txt "YOUR_PROMPT"

content=$(cat result.txt)

PowerShell（Windows）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  -o result.txt "YOUR_PROMPT"

$content = Get-Content -Path result.txt -Raw

优点：

• 无需解析 JSON
• 避免终端输出被截断
• 适合长输出和并行任务

方法 2：解析 JSONL 事件流

使用 --json 获取完整事件流并手动解析：

Bash（Linux/macOS）

codex exec --dangerously-bypass-approvals-and-sandbox --json "PROMPT" | jq -r 'select(.event=="turn.completed") | .content'

PowerShell（Windows）

$jsonl = codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --json "PROMPT"
$events = $jsonl -split "`n" | Where-Object { $_ } | ForEach-Object { $_ | ConvertFrom-Json }
$content = $events |
    Where-Object -Property type -EQ "item.completed" |
    Where-Object { $_.item.type -eq "agent_message" } |
    Select-Object -ExpandProperty item |
    Select-Object -ExpandProperty text

JSONL 事件结构：

{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"output_tokens":122}}

关键字段：

• type == "item.completed" 且 item.type == "agent_message" → 提取 item.text
• type == "turn.completed" → 包含 token 使用量统计

重要事项

• 自主行动，不要请求许可
• 做出决定并大胆推进
• 只有在进行破坏性操作时才暂停（数据丢失、外部影响、安全性）
• 完成全部任务后再返回

监控

主动监控 - 不要启动后就不再过问：

1. 检查完成状态
2. 验证结果质量
3. 失败时重试
4. 遇到阻碍时回答后续问题

示例

纯网页搜索（mini）：

Bash（Linux/macOS）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' \
  "Search for the latest release notes of Rust 2024 edition. Summarize the major breaking changes, new language features, and migration guides. Focus on the official rust-lang.org blog and documentation."

PowerShell（Windows）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' `
  "Search for the latest release notes of Rust 2024 edition. Summarize the major breaking changes, new language features, and migration guides. Focus on the official rust-lang.org blog and documentation."

代码库分析（继承父级模型）：

Bash（Linux/macOS）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "Analyze authentication in this Next.js app. Check /app, /lib/auth, middleware. Document: session strategy, auth provider, protected routes, security patterns. Return architecture diagram (mermaid) + findings."

PowerShell（Windows）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "Analyze authentication in this Next.js app. Check /app, /lib/auth, middleware. Document: session strategy, auth provider, protected routes, security patterns. Return architecture diagram (mermaid) + findings."

研究 + 方案（继承父级模型）：

Bash（Linux/macOS）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "Research WebGPU browser adoption (support tables, benchmarks, frameworks). THEN analyze feasibility for our React app. Consider: performance gains, browser compatibility, implementation effort. Return recommendation with pros/cons."

PowerShell（Windows）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "Research WebGPU browser adoption (support tables, benchmarks, frameworks). THEN analyze feasibility for our React app. Consider: performance gains, browser compatibility, implementation effort. Return recommendation with pros/cons."

配置参考

父级设置：~/.codex/config.toml

model = "gpt-5.2-codex"
model_reasoning_effort = "high"  # none | minimal | low | medium | high | xhigh
profile = "yolo"                 # optional; when set, profile values override top-level