Codex 刚刚上线了 Subagent 功能。

能够并行拉起多个 Subagent 干活，最后把结果合并成一个响应返回给你。

官方文档：https://developers.openai.com/codex/subagents

比如你让 Codex 审查一个 PR，它可以同时拉起 6 个 Agent——一个查安全漏洞，一个查代码质量，一个找 bug，一个盯竞态条件，一个检查测试稳定性，一个评估可维护性。

代码库探索、多步功能实现这类高度并行的复杂任务，特别适合这种玩法。

一句话概括：你现在可以用一条指令，让 Codex 拉起一支 AI 团队并行干活。

当前版本 Codex 默认启用 Subagent。

Subagent 的运行状态可在 Codex 应用和 CLI 中查看，IDE 插件的支持即将上线。

Subagent 是什么，解决什么问题

先说痛点。

单个 Agent 干活有三个硬伤：

第一，上下文会被撑爆。 模型的上下文窗口是有限的。你让 Codex 审查一个大 PR，它一边读代码一边跑测试一边翻文档，中间产生的探索笔记、测试日志、堆栈追踪、命令输出全都塞在同一个对话里。有用的信息被噪音淹没——Chroma 的研究团队管这叫 Context Rot（上下文退化）：对话越长，模型越不靠谱。

第二，串行执行太慢。 查安全、查质量、查 bug 这些任务之间没有依赖关系，但单 Agent 只能一件一件做。你在等它做完第五项的时候，前面四项的结论已经在上下文里积灰了。

第三，一个人格不够用。 安全审查需要偏执狂，代码风格检查需要洁癖，文档验证需要耐心——这些"性格"塞进同一个 Agent 里，互相打架。

Subagent 的解法很直接：把一个大任务拆成多个小任务，每个小任务交给一个专职 Agent 并行跑，最后汇总结果。

• 主 Agent 专注做决策，不被中间噪音干扰

• 各 Subagent 各干各的，互不污染上下文

• 最终只把精炼的结论交回来

跟传统的 prompt chaining（把输出接力传给下一个 prompt）相比，Subagent 是真正的并行。

运行原理

只有你明确要求时，Codex 才会拉起 Subagent。每个 Subagent 独立调用模型和工具，所以 token 消耗比单 Agent 跑法更高。

Codex 统一负责编排：拉起 Subagent、分发指令、等结果、关线程。多个 Agent 并行跑时，Codex 等所有结果到齐后才返回汇总响应。

试试在你的项目上跑这个：

对当前 PR（本分支 vs main）做以下审查，每项各启动一个 Subagent，全部跑完后汇总：1. 安全问题2. 代码质量3. Bug4. 竞态条件5. 测试稳定性6. 代码可维护性

与 Subagent 交互

• CLI 里用 /agent 切换 Agent 线程，查看各线程的工作进展。

• 直接对 Codex 说话就能操控 Subagent——调整方向、叫停、关掉已完成的线程。

沙箱与权限

Subagent 继承当前的沙箱策略。

交互式 CLI 会话中，非活跃线程的审批请求也会弹出来，哪怕你正盯着主线程。弹窗会标明来源线程，按 o 可以跳过去看一眼再决定批准还是拒绝。

非交互式场景下弹不出审批窗口，需要审批的操作会直接失败，错误信息反馈给父工作流。

Codex 启动 Subagent 时，会把父轮次的运行时配置一并带过去——包括你在会话中动态改过的沙箱和审批设置（/approvals changes、--yolo 之类的），即使自定义 Agent 文件里有不同的默认值，也以你的实时设置为准。

单个自定义 Agent]也可以单独指定沙箱模式，比如强制只读。

内置 Agent

Codex 自带三个内置 Agent：

• default — 通用兜底

• worker — 干活型，负责实现和修复

• explorer — 读代码型，专注代码库探索

自定义 Agent

往下面两个目录丢 TOML 文件就行：

• ~/.codex/agents/ — 个人级

• .codex/agents/ — 项目级

一个文件定义一个 Agent。Codex 把它当作子会话的配置层加载，所以自定义 Agent 能覆盖常规 Codex 配置的同一套设置。这种方式比独立的 Agent 清单文件稍重，格式后续可能会变。

必填字段：

• name — 名称

• description — 描述

• developer_instructions — 核心指令

可选字段 nickname_candidates、model、model_reasoning_effort、sandbox_mode、mcp_servers、skills.config 省略时从父会话继承。

全局设置

全局配置放在配置文件的 [agents] 节下：

字段	类型	必填	说明
agents.max_threads	number	否	并发线程上限，默认 6
agents.max_depth	number	否	嵌套深度（根会话从 0 算），默认 1
agents.job_max_runtime_seconds	number	否	CSV 批量任务每个 worker 的默认超时，不设则 1800 秒

• max_depth 为 1 表示允许直接 Subagent，但 Subagent 不能再往下嵌套。

• 自定义 Agent 与内置 Agent 同名时，自定义优先。

文件格式

字段	类型	必填	说明
name	string	是	Codex 识别和启动 Agent 用的名字
description	string	是	告诉 Codex 什么场景该用这个 Agent
developer_instructions	string	是	定义行为的核心指令
nickname_candidates	string[]	否	显示昵称池，区分同类型的多个实例

还可以塞 model、model_reasoning_effort、sandbox_mode、mcp_servers、skills.config 等 config.toml 支持的键。

Codex 靠 name 字段识别 Agent。文件名跟 name 一致是惯例，但 name 字段才是真相来源。

显示昵称

同一个 Agent 跑多个实例时，nickname_candidates 让 UI 显示不同的名字，而不是一串重复的 Agent 名。

昵称只影响展示，内部仍然按 name 识别。候选列表不能为空，名称需唯一，可以用 ASCII 字母、数字、空格、连字符、下划线。

name = "reviewer"description = "专注正确性、安全性和测试覆盖的 PR 审查 Agent。"developer_instructions = """像代码 Owner 一样审查。优先关注正确性、安全性、行为回退和缺失的测试覆盖。"""nickname_candidates = ["Atlas", "Delta", "Echo"]

UI 里显示 Atlas / Delta / Echo，底层类型仍是 reviewer。

设计原则

好的自定义 Agent 要窄而有主见——职责明确、工具匹配、指令防跑偏。

示例 1：PR 审查

三个 Agent 分工协作：

• pr_explorer — 梳理代码库、收集证据

• reviewer — 找正确性、安全性和测试风险

• docs_researcher — 通过 MCP 服务器查阅框架和 API 文档

项目配置 .codex/config.toml：

[agents]max_threads = 6max_depth = 1

.codex/agents/pr-explorer.toml：

name = "pr_explorer"description = "只读代码库探索，在提出变更前先收集证据。"model = "gpt-5.3-codex-spark"model_reasoning_effort = "medium"sandbox_mode = "read-only"developer_instructions = """保持探索模式。追踪真实执行路径，标注文件和符号，不主动提修复建议。快速搜索 + 定向读文件，别大范围扫。"""

.codex/agents/reviewer.toml：

name = "reviewer"description = "专注正确性、安全性和测试覆盖的 PR 审查 Agent。"model = "gpt-5.4"model_reasoning_effort = "high"sandbox_mode = "read-only"developer_instructions = """像代码 Owner 一样审查。优先关注正确性、安全性、行为回退和缺失的测试覆盖。先说具体发现，附复现步骤，别发纯风格评论——除非里面藏着真 bug。"""

.codex/agents/docs-researcher.toml：

name = "docs_researcher"description = "文档专家，通过 docs MCP 服务器验证 API 和框架行为。"model = "gpt-5.3-codex-spark"model_reasoning_effort = "medium"sandbox_mode = "read-only"developer_instructions = """用 docs MCP 服务器确认 API、参数和版本特定行为。答案要简洁，附链接或精确引用。不改代码。"""
[mcp_servers.openaiDeveloperDocs]url = "https://developers.openai.com/mcp"

用法：

审查本分支与 main 的差异。pr_explorer 梳理受影响的代码路径，reviewer 找风险，docs_researcher 验证补丁依赖的框架 API。

此工作流为实验性功能，可能随 Subagent 支持的演进而变化。

CSV 批量任务（spawn_agents_on_csv）

大量同类任务、每行一个工作项的场景，用 spawn_agents_on_csv。Codex 读 CSV，每行拉一个 worker，跑完后合并结果导出为新 CSV。

典型场景：

• 逐文件 / 逐包 / 逐服务审查

• 批量检查事故、PR 或迁移目标

• 为大量输入生成结构化摘要

参数：

• csv_path — 源 CSV

• instruction — worker 提示词模板，用 {column_name} 插值

• id_column — 哪一列做条目 ID

• output_schema — worker 返回的 JSON 结构

• output_csv_path、max_concurrency、max_runtime_seconds — 流控

每个 worker 必须且只能调用一次 report_agent_job_result。没报告结果就退出的，导出 CSV 里标记为错误。

创建 /tmp/components.csv，path 和 owner 两列，每个前端组件一行。
然后 spawn_agents_on_csv：- csv_path: /tmp/components.csv- id_column: path- instruction: "审查 {path}（负责人 {owner}），通过 report_agent_job_result 返回 {path, risk, summary, follow_up} 的 JSON。"- output_csv_path: /tmp/components-review.csv- output_schema: {path, risk, summary, follow_up} 均为必填 string

codex exec 跑时，stderr 上有单行进度。导出 CSV 带原始数据和 job_id、item_id、status、last_error、result_json 等元数据。

相关配置：

• agents.max_threads — 并发线程上限

• agents.job_max_runtime_seconds — 每个 worker 默认超时，单次调用的 max_runtime_seconds 优先

• sqlite_home — Agent 任务和导出结果的 SQLite 存储路径

示例 2：前端集成调试

UI 回归、浏览器流程不稳定、跨前后端的集成 bug——这个模式管用。

.codex/config.toml：

[agents]max_threads = 6max_depth = 1

.codex/agents/code-mapper.toml：

name = "code_mapper"description = "只读代码库探索，定位相关前后端代码路径。"model = "gpt-5.3-codex-spark"model_reasoning_effort = "medium"sandbox_mode = "read-only"developer_instructions = """梳理故障 UI 流程对应的代码。先定位入口点、状态转换和关键文件，再让 worker 动手。"""

.codex/agents/browser-debugger.toml：

name = "browser_debugger"description = "UI 调试 Agent，用浏览器工具复现问题、抓证据。"model = "gpt-5.4"model_reasoning_effort = "high"sandbox_mode = "workspace-write"developer_instructions = """在浏览器里复现问题，记录精确步骤，报告 UI 实际行为。截图、控制台输出、网络请求都要抓。不改应用代码。"""
[mcp_servers.chrome_devtools]url = "http://localhost:3000/mcp"startup_timeout_sec = 20

.codex/agents/ui-fixer.toml：

name = "ui_fixer"description = "问题明确后做最小修复的实现型 Agent。"model = "gpt-5.3-codex-spark"model_reasoning_effort = "medium"developer_instructions = """问题复现后接手修复。改动要小、要准，不碰无关文件，只验证改过的行为。"""
[[skills.config]]path = "/Users/me/.agents/skills/docs-editor/SKILL.md"enabled = false

用法：

排查设置弹窗保存失败的问题。browser_debugger 复现，code_mapper 追踪代码路径，ui_fixer 在故障模式明确后做最小修复。

这不只是多开几个窗口

Subagent 的意义不在于"能同时跑多个 Agent"——这个 Claude Code 也能做，Cursor 也有类似的多文件编辑能力。

Codex 这次做对的几件事：

把上下文隔离当作一等公民。 不是简单的"多开几个 Agent"，而是从架构层面解决了 Context Rot 的问题。每个 Subagent 有自己的干净上下文，不会互相污染，最终只把精炼结论交回主线程。

自定义 Agent 的配置足够简单。 一个 TOML 文件、三个必填字段，就能定义一个专职角色。不需要写代码，不需要搭框架。

模型分级很实用。 不是所有 Agent 都需要最强的模型。轻活用轻快模型，重活用重型模型，token 花在刀刃上。

CSV 批量任务是隐藏杀手锏。 把 Codex 从对话工具变成了批处理引擎，这个能力在企业场景里会很有价值。

适合什么，不适合什么

适合：

• 代码审查（多维度并行审查）

• 代码库探索（并行搜索 + 汇总）

• 批量审计和检查

• 多步骤的调试流程

不太适合：

• 需要大量文件写入的并行任务（多个 Agent 同时改代码容易冲突）

• 简单的单步操作（杀鸡别用牛刀）

• 上下文高度耦合的任务（拆不开就别硬拆）

往远了看

Subagent 这个方向指向一个更大的趋势：编码工具正在从一个聪明的助手演变成一支可调度的团队。

以前你跟 AI 的交互模式是我说一句，它干一件。现在变成了我描述目标，它自己拆解、组队、并行执行、汇总汇报。

这还是早期形态。等 Agent 之间能更好地共享发现、动态调整分工、甚至自主决定什么时候该拉新的队友——那才是真正的 AI 团队协作。

但至少，第一步已经迈出来了。