⚡

CodexSubagent codex-subagent

Codex 子代理技能用于在后台生成子代理以卸载上下文繁重的工作，适用于深度研究、代码库探索、多步骤工作流等任务，遵循黄金法则：如果任务及中间步骤将使用超过3000个令牌，则应使用子代理。

AI智能体 0 次安装 0 次浏览 更新于 3/5/2026

Codex Subagent 技能

生成 Codex 子代理以通过后台 shell 卸载上下文繁重的工作。用于：深度研究（3+ 搜索），代码库探索（8+ 文件），多步骤工作流，探索性任务，长时运行操作，文档生成，或任何其他中间步骤将使用大量令牌的任务。

**黄金法则：**如果任务 + 中间工作将向父上下文添加 3,000+ 令牌 → 使用子代理。

智能提示

关键：父代理必须为子代理提供成功所需的基本上下文。

好的提示原则

  1. 包含相关上下文 - 给子代理提供彻底的上下文
  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 表格形式返回。”

提示模板

[任务上下文]
您正在研究/分析 [特定主题] 在 [位置/代码库/域]。

[目标]
您的目标：
1. [具体的第一个目标]
2. [第二个目标]
3. [如果需要的第三个目标]

[约束]
- 重点关注：[特定区域/文件/来源]
- 优先考虑：[最重要的]
- 忽略：[要跳过的内容]

[输出格式]
返回：[父级需要的确切格式]

[成功标准]
完成时：[满足特定条件]

模型选择

使用迷你模型（gpt-5.1-codex-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"' \
  "搜索网络 [主题] 并总结发现"

PowerShell（Windows）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' `
  "搜索网络 [主题] 并总结发现"

继承父模型 + 推理

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

Bash（Linux/macOS）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "找到认证文件 THEN 分析安全模式并提出改进"

PowerShell（Windows）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "找到认证文件 THEN 分析安全模式并提出改进"

决策逻辑

是否任务纯粹是搜索/收集？
├─ 是：收集后有任何工作吗？
│  ├─ 没有 → 迷你模型
│  └─ 有 → 继承父级
└─ 否 → 继承父级

基本用法

Bash（Linux/macOS）

# 获取父会话设置（尊重活动配置文件；回退到顶级）
# 注意：codex-parent-settings.sh 打印两行；使用 mapfile 避免空的 REASONING。
mapfile -t _settings < <(scripts/codex-parent-settings.sh)
MODEL="${_settings[0]}"
REASONING="${_settings[1]}"

# 生成子代理（继承父级）
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "详细提示带上下文"

# 更安全的提示构造（没有反引号/命令替换）
PROMPT=$(cat <<'EOF'
[任务上下文]
您正在分析 /path/to/repo。

[目标]
1. 做 X
2. 做 Y

[输出格式]
返回：路径 - 目的
EOF
)
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "$PROMPT"

# 纯搜索（使用迷你）
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 输出解析
codex exec --dangerously-bypass-approvals-and-sandbox --json "PROMPT" | jq -r 'select(.event=="turn.completed") | .content'

PowerShell（Windows）

# 获取父会话设置（尊重活动配置文件；回退到顶级）
$scriptPath = Join-Path $env:USERPROFILE ".codex\skills\codex-subagent\scripts\codex-parent-settings.ps1"
$settings = & $scriptPath
$MODEL = $settings[0]
$REASONING = $settings[1]

# 生成子代理（继承父级）
codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "详细提示带上下文"

# 使用 here-string 多行提示（避免转义问题）
$PROMPT = @'
[任务上下文]
您正在分析 /path/to/repo。

[目标]
1. 做 X
2. 做 Y

[输出格式]
返回：路径 - 目的
'@

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

# 纯搜索（使用迷你）
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"

# 方法 1（推荐）：使用 -o 直接输出到文件
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

# 方法 2：解析 JSONL 事件流
$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

并行子代理（最多 5 个）

同时为独立任务生成多个子代理：

Bash（Linux/macOS）

# 同时研究不同主题
codex exec --dangerously-bypass-approvals-and-sandbox -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" "研究主题 A..." &
codex exec --dangerously-bypass-approvals-and-sandbox -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" "研究主题 B..." &
wait

PowerShell（Windows）

使用 PowerShell 作业进行并行执行，并使用 -o 输出到单独的文件：

# 并行执行与文件输出
$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 "研究主题 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 "研究主题 B..."
} -ArgumentList $MODEL, $REASONING, "output2.txt"

# 等待所有作业完成
$job1, $job2 | Wait-Job | Remove-Job

# 读取结果
$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" → 包含令牌使用统计

重要

  • 自主行动，不请求权限
  • 果断决策并继续进行
  • 仅在破坏性操作（数据丢失，外部影响，安全）时暂停
  • 返回前完成任务

监控

积极监控 - 不要发射后忘记：

  1. 检查完成状态
  2. 验证结果质量
  3. 如果失败则重试
  4. 如果被阻塞，则回答后续问题

示例

纯网络搜索（迷你）：

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"' \
  "搜索最新的 Rust 2024 版发布说明。总结主要的破坏性变更，新的语言特性和迁移指南。重点关注官方 rust-lang.org 博客和文档。"

PowerShell（Windows）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m gpt-5.1-codex-mini -c 'model_reasoning_effort="medium"' `
  "搜索最新的 Rust 2024 版发布说明。总结主要的破坏性变更，新的语言特性和迁移指南。重点关注官方 rust-lang.org 博客和文档。"

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

Bash（Linux/macOS）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "分析这个 Next.js 应用中的认证。检查 /app，/lib/auth，中间件。记录：会话策略，认证提供商，受保护的路由，安全模式。返回架构图（mermaid）+ 发现。"

PowerShell（Windows）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "分析这个 Next.js 应用中的认证。检查 /app，/lib/auth，中间件。记录：会话策略，认证提供商，受保护的路由，安全模式。返回架构图（mermaid）+ 发现。"

研究 + 提案（继承父级）：

Bash（Linux/macOS）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check \
  -m "$MODEL" -c "model_reasoning_effort=\"$REASONING\"" \
  "研究 WebGPU 浏览器采用情况（支持表，基准测试，框架）。然后分析我们的 React 应用的可行性。考虑：性能提升，浏览器兼容性，实施工作量。返回建议及利弊。"

PowerShell（Windows）

codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check `
  -m $MODEL -c "model_reasoning_effort=`"$REASONING`"" `
  "研究 WebGPU 浏览器采用情况（支持表，基准测试，框架）。然后分析我们的 React 应用的可行性。考虑：性能提升，浏览器兼容性，实施工作量。返回建议及利弊。"

配置参考

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

model = "gpt-5.2-codex"
model_reasoning_effort = "high"  # none | minimal | low | medium | high | xhigh
profile = "yolo"                 # 可选；当设置时，配置文件值覆盖顶级