1 · agent-subagent#

https://developers.openai.com/codex/subagents

1.1 · S 什么场景#

Subagents 适合明显可并行的复杂任务，典型场景有：

• 大代码库探索，把不同问题拆给不同 agent
• 多步骤功能实现，把调研、实现、验证拆开并行处理
• PR review，把正确性、安全性、测试风险分给不同 agent
• 大批量重复任务，比如对 CSV 中每一行启动一个 worker 做审查或摘要

核心价值：

• 降低主线程上下文污染
• 让不同子任务使用不同模型、工具和指令
• 并行执行后由 Codex 汇总结果

1.2 · C 什么冲突#

Subagents 不是“免费并发”。

• 只有显式要求时，Codex 才会创建 subagent
• 每个 subagent 都会单独消耗模型推理和工具调用，所以 token 成本高于单 agent
• 并发越多，协调和审批越复杂
• 如果 agent 职责不清，容易漂移到相邻工作，反而增加噪音

文档的隐含建议是：只在任务天然可拆分时用，不要为了“看起来高级”而滥用。

1.3 · Q 什么问题#

1.3.1 · 1. Subagents 是怎么工作的？#

Codex 负责整套编排：

• 启动子 agent
• 转发后续指令
• 等待结果
• 回收线程
• 最后返回一份聚合后的答复

CLI 里可以用 /agent 查看和切换 agent 线程，也可以直接让 Codex 去继续推进、停止或关闭某个 subagent。

1.3.2 · 2. 默认有哪些 agent？#

内置 3 类：

• default：通用兜底 agent
• worker：偏执行，适合实现和修复
• explorer：偏只读探索，适合读代码和收集证据

1.3.3 · 3. 怎么定义自定义 agent？#

在下面两个目录放独立 TOML 文件：

• 个人级：~/.codex/agents/
• 项目级：.codex/agents/

每个 agent 文件至少要有：

• name
• description
• developer_instructions

可选字段包括：

• nickname_candidates
• model
• model_reasoning_effort
• sandbox_mode
• mcp_servers
• skills.config

如果这些可选项没写，就继承父 session 的配置。

一个最小示例：

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""
nickname_candidates = ["Atlas", "Delta", "Echo"]

注意：

• Codex 识别 agent 以 name 为准，不是文件名
• nickname_candidates 只是展示名，不影响真正的 agent 类型
• 如果自定义 agent 名字和内置 agent 重名，自定义配置优先

1.3.4 · 4. 全局并发和深度怎么控制？#

在配置里的 [agents] 下控制：

[agents]
max_threads = 6
max_depth = 1
job_max_runtime_seconds = 1800

几个关键点：

• max_threads：最多同时打开多少 agent 线程，默认 6
• max_depth：允许嵌套多少层，默认 1
• job_max_runtime_seconds：CSV 批处理时单 worker 的默认超时

1.3.5 · 5. 权限和沙箱怎么继承？#

subagent 默认继承父会话的 sandbox policy 和审批设置。

• 交互式 CLI 中，即使你在主线程，也可能看到来自子线程的审批请求
• 非交互模式下，如果需要新审批但无法弹出审批，动作会失败，并把错误回传给父流程
• 父线程运行时动态改过的设置也会重新应用到子线程，比如 /approvals 或 --yolo
• 也可以在某个自定义 agent 上单独覆盖 sandbox_mode，比如明确设成 read-only

1.3.6 · 6. 官方推荐怎样设计 custom agents？#

最佳实践是：窄而明确。

• 一个 agent 只做一类工作
• 给它匹配合适的工具面
• 指令要明确限制边界，避免顺手做别的事

官方给了两个典型模式：

• PR review：pr_explorer 负责读代码找证据，reviewer 负责找风险，docs_researcher 负责查文档
• 前端集成排障：code_mapper 负责定位代码路径，browser_debugger 负责浏览器复现，ui_fixer 负责最小修复

1.4 · A 回答问题#

一句话总结：

Subagents 就是让 Codex 把一个大任务拆成多个专职小 agent 并行完成，再统一汇总结果。

使用原则：

• 任务可并行，才值得拆
• agent 职责要窄，边界要硬
• 读、查、改、验最好分开
• 默认继承父级安全策略，需要时再按 agent 覆盖
• 要接受更高 token 成本，换取更清晰的上下文和更好的并行效率

如果你是要落地使用，这页文档最重要的信息其实只有三件事：

• 什么时候该开 subagents：并行型复杂任务
• 怎么定义 custom agents：在 ~/.codex/agents/ 或 .codex/agents/ 写 TOML
• 怎么控风险：限制 agent 职责、限制 sandbox、限制深度和并发