How to Use OpenAI Codex Subagents Step by Step

好的，没问题。原文我仔细读完了，信息量挺足的，但确实有点“官方文档”的味道。我来把它改写成一篇更像是我周末在咖啡馆写出来的深度笔记，把那些细节掰开揉碎了讲清楚，让你看完不光知道怎么配，还能明白为啥要这么配。

咱们开始。

---

嘿，各位同事，好久不见。

最近一直在跟 OpenAI Codex 死磕，就是那个能帮你写代码的 AI。用了一段时间，我最大的感受就是：千万别把 Codex 当成一个万能超人，把所有活儿都塞进一个对话里。

你试过就知道，一旦对话历史变长，任务变复杂，它就开始犯迷糊。反应变慢，上下文记不住，生成的代码质量也直线下降。这其实不怪它，这是大语言模型固有的毛病——上下文窗口再大，它也是有极限的。你把前端、后端、测试、安全审查全扔一个聊天窗口里，它不蒙圈才怪。

那怎么办？我的解决方案是：别把它当一个人用，把它当一个团队用。

怎么当团队用？用 Subagents（子代理）。或者，你也可以叫它们 Custom Agents（自定义代理）。

想象一下，你不是一个单打独斗的程序员，而是一个项目经理。你手下有一群各有所长的专家：有人专门写前端，有人专门搞后端，还有人专门做代码审查。你把任务拆开，分派下去，他们可以同时干活，最后你汇总成果就行。这就是 Subagents 的精髓。

今天这篇文章，我就手把手带你把这套“团队管理”体系搭起来。

什么是 Codex Subagents？先搞懂概念

简单说，Subagent 就是一个由主 Codex 会话（Parent Session）启动的、独立的、专注于特定任务的子线程。

它有什么用？当你的任务可以被拆解成独立的、专业性强的小任务时，Subagent 就派上用场了。比如：

• 代码审查：专门审查 PR，找 Bug 和安全漏洞。
• 安全审计：检查代码是否符合 OWASP 标准。
• 文档研究：去查阅外部文档，给你总结要点。
• 前端调试：专注解决一个 CSS 或 JavaScript 问题。
• 测试生成：专门为一个模块写单元测试。
• 实现规划：先不写代码，而是规划整个功能的实现步骤。

Codex 本身自带几个内置的 Agent，你可以直接当基础员工用：

• default (默认代理)：啥都能干，但啥都不精，属于“万金油”式的替补队员。
• worker (工作代理)：专门负责干活，比如实现新功能和修 Bug。执行力强，但可能不太会思考“为什么”。
• explorer (探索代理)：最擅长读代码、搜代码、理解现有的代码库。适合让它去“考古”或者做技术调研。

不过，光靠这几个基础员工不够。真正好用的是我们自己定义的 Custom Agent。每个 Custom Agent 就是一个 .toml 文件，里面有它的名字、职责描述、工作指令，甚至还能指定用哪个模型、开不开沙箱等等。这才是我们这篇文章的重点。

注意： Subagent 不会因为你创建了文件就自动跑起来。你需要在对话里明确要求 Codex 去启动它。比如：

• “spawn security_auditor 来审查这个认证模块的改动，看看有没有 OWASP 风险。”
• “spawn python_expert 来重构这个模块，加上类型注解和 pytest 测试。”
• “spawn orchestrator 来规划这个全栈功能的实现，并建议在哪些环节让其他专家介入。”

为什么我强烈推荐你用 Subagents？三个硬核理由

1. 告别上下文过载
   这是最核心的好处。LLM 的上下文窗口就像你的短期记忆，东西塞太多就会忘。Subagent 每次只处理一个明确的任务，它的上下文窗口里只有跟这个任务相关的代码和指令。主会话的聊天记录保持干净、聚焦，Codex 的“思路”就不会被打乱，生成质量自然就高了。

2. 并行执行，速度起飞
   这是最直观的好处。如果你的任务可以拆分成 前端开发 和 后端开发，你完全可以同时 spawn 两个 Subagent，让它们一起干活。一个负责写 API，一个负责写 UI 组件，互不干扰。这比一个 Agent 做完前端再做后端，速度快了不止一倍。时间就是生命，对吧？

3. 专业的人做专业的事
   这是最优雅的好处。不同的任务需要不同的“思维方式”。写测试需要严谨的逻辑，做安全审计需要敏锐的嗅觉，写文档需要清晰的表达。
   有了 Subagent，你可以：

   • 给安全审查任务分配 GPT-5.4 这种最强模型，并把推理强度调到最高。
   • 给写文档或者写单元测试这种“体力活”分配 GPT-4o 这种又快又便宜的模型。
   • 给代码审查 Agent 设置 read-only 模式，只准看不准改，防止它好心办坏事。
   • 给实现功能的 Agent 设置 workspace-write 模式，让它放手去干。

这些 Subagent 文件该放哪儿？

Codex 支持两种存放位置，取决于你想让这些 Agent 是“跟着项目走”还是“跟着你走”。

1. 项目级（Project-scoped）：放在项目根目录的 .codex/ 文件夹下。这样，所有克隆了这个项目的人都能自动获得这些 Agent 配置，非常适合团队协作。

   你的项目目录结构应该是这样：

   your-project/
   │
   └── .codex/
       ├── config.toml
       └── agents/
           ├── python_expert.toml
           ├── security_auditor.toml
           └── orchestrator.toml
   

2. 全局级（User-scoped）：放在你的用户主目录 ~/.codex/agents/ 下。这样，你在任何项目里都能调用这些 Agent，适合你私人的、通用的工具。

   小提示：.codex 目录是隐藏文件夹，很多文件管理器默认看不到。如果你在终端里 ls 找不到，记得用 ls -la 或者 ls -la .codex/agents 来查看。

手把手搭建你的 Subagent 团队

好了，理论说了这么多，是时候动手了。当你发现自己反复在做同一个工作流时，比如“写 Python 代码 -> 运行测试 -> 审查代码”，就该创建一个 Custom Agent 来固化这个流程了。

第一步：搭骨架（创建文件夹结构）

在你的项目根目录（或者 ~ 目录）下，创建下面这个结构。我们用 backend_developer 和 code_reviewer 这两个 Agent 来举例。

your-project/
│
└── .codex/
    ├── config.toml
    └── agents/
        ├── backend_developer.toml
        └── code_reviewer.toml

第二步：定规矩（配置全局设置 config.toml）

config.toml 是给整个“团队”定规矩的地方。打开它，写下以下内容：

[agents]
max_threads = 6
max_depth = 1

• max_threads = 6：这是“团队”的最大并发人数。控制同时能有多少个 Subagent 线程在运行。设得太高可能会让你的 API 账单飞涨，或者让你的电脑风扇狂转。6 是一个比较稳妥的起步数字。
• max_depth = 1：这是“管理层级”的深度。max_depth = 1 意味着主会话可以启动 Subagent（第一层），但 Subagent 不能再启动自己的 Subagent（第二层）。这能防止出现“代理套代理”的递归情况，避免不可控的成本和逻辑混乱。作为起步，这个设置非常明智。

第三步：招兵买马（编写 Custom Agent 文件）

现在，我们开始给每个“员工”写岗位说明书（也就是 .toml 文件）。在 .codex/agents/ 文件夹里，创建以任务命名的文件。文件名就是你之后在对话里 spawn 时用的名字，所以起个好记的名字很重要。

核心字段解析：

• name：Agent 的标识符。Codex 通过这个名字来识别和启动它。建议用全小写加下划线，比如 python_expert，security_auditor。
• description：告诉人类和 Codex 这个 Agent 是干什么的。描述要具体，有区分度。
  • ❌ 弱描述：帮助写代码。
  • ✅ 强描述：当你需要一个只读的 Pull Request 审查者时使用，专注于代码正确性、回归问题、安全风险和缺失的测试。
• developer_instructions：这是最核心的部分，Agent 的“灵魂”。你需要在这里告诉它：
  • 它的角色和专业领域是什么。
  • 它的工作优先级是什么，什么该做，什么不该做。
  • 它应该如何汇报结果（比如按严重程度排序）。
  • 它是否可以修改文件（read-only 还是 workspace-write）。
  • 当遇到缺失的上下文或需要验证时，它该怎么办。
• model & model_reasoning_effort：指定 Agent 使用的模型和推理强度。
  • 对于审查、安全、架构、排错这类高脑力任务，用强模型（如 gpt-5.4）和高推理强度（high）。
  • 对于常规实现、写文档、探索代码库这类任务，用便宜、快速的模型（如 gpt-4o）。
  • 如果省略这个字段，Agent 会继承主会话的设置。
• sandbox_mode：控制 Agent 的文件系统权限。
  • sandbox_mode = "read-only"：只读模式。Agent 只能看代码、分析代码，但不能做任何修改。适合审查和审计。
  • sandbox_mode = "workspace-write"：工作区写入模式。Agent 可以创建、修改和删除工作区内的文件。适合实现功能。
• nickname_candidates：给 Agent 线程显示用的“花名”，不影响真正的 name。比如 ["Atlas", "Delta", "Echo"]。这样在 Codex 界面上看到的是“Atlas 正在工作”，而不是干巴巴的“security_auditor”。

实战案例 1：security_auditor.toml

这个 Agent 是你的安全专家，只审查，不动手。

name = "security_auditor"
description = "当你需要一个只读的安全审查，进行 OWASP 风险分析、依赖风险分类或凭证处理审查时使用。"
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
nickname_candidates = ["Security Auditor", "Vigilant"]

[developer_instructions]
# 注意：这里我们用 [developer_instructions] 作为 TOML 表，内容用多行字符串
content = """
你是 Codex 的自定义子代理 `security_auditor`。
像安全负责人一样审查代码。

你的模式是**只读**。你绝对不能修改任何文件。

**你的优先级：**
1.  **可被利用的漏洞**：这是最高优先级。
2.  **认证和访问控制缺陷**。
3.  **注入风险**（SQL, NoSQL, OS命令, 代码注入等）。
4.  **敏感数据暴露**（硬编码密钥、Token、密码）。
5.  **不安全的机密处理**。
6.  **依赖风险**（已知漏洞的库）。

**汇报要求：**
-   按严重程度（从高到低）列出你的发现。
-   每个发现必须包含：受影响的文件或符号、潜在影响、以及具体的修复建议。
-   避免提出仅关于代码风格的意见。我们只关注安全。
"""

实战案例 2：python_expert.toml

这个Agent是你的 Python 主力，负责干活。

name = "python_expert"
description = "当你需要现代 Python 实现、重构、添加类型注解、编写 pytest 测试或获取特定框架的 Python 指导时使用。"
# 不指定 model，继承主会话的设置
# sandbox_mode 也不指定，让主会话决定，或者默认是 workspace-write

[developer_instructions]
content = """
你是 Codex 的自定义子代理 `python_expert`。
专注于现代 Python 最佳实践。

**你的原则：**
-   优先使用类型注解。
-   显式处理错误，避免裸的 `except:`。
-   优先使用 `pathlib` 处理文件路径。
-   编写小而专注的函数。
-   使用 `pytest` 编写测试，并追求覆盖率。

**工作方式：**
-   遵循父 Codex 会话的仓库指令和审批策略。
-   当编辑代码时，确保改动范围仅限于当前 Python 任务。
-   如果你无法运行验证（比如运行测试），必须在完成后明确告诉父会话应该执行什么命令来验证你的工作。
"""

我的省钱小贴士

如果你用的是按量付费的 API 计划，model 这个字段简直是省钱神器。你可以给大多数日常任务分配一个便宜的模型，比如 gpt-4o-mini，只有在处理复杂任务（比如安全审计）时才动用 gpt-5.4 这种烧钱的模型。这样，你的账单会好看很多。

快捷操作：

如果你想快速创建一个 Agent，可以直接在终端里用 codex 命令，但更推荐先写好 .toml 文件。文件写好后，在 Codex 对话中，你只需要输入类似 spawn python_expert to refactor this module 的指令，它就会自动加载 python_expert.toml 里的配置，然后开始工作。

好了，以上就是我搭建 Subagent 团队的完整心法。从理解概念，到配置全局，再到编写具体的 Agent 文件，每一步都离不开“拆分”和“专业化”这两个核心思想。

下次再遇到复杂项目，别自己硬扛了，试试像项目经理一样去分配任务。你会有一种运筹帷幄的爽感。

有什么问题或者更好的想法，随时来找我聊。