Codex 子代理使用教程

📚 系列导航：上一篇 Codex MCP 外部工具接入教程 教你给 Codex 接上外部工具，让它能查文档、连服务。这一篇换个思路——不是给它「加工具」，而是教你把活儿拆出去并行跑：子代理（Subagent），一批带独立模型、独立指令、独立权限的专项助手，几个同时干，干完把结论汇总成一份交回来。

兄弟们，今天聊 Codex 里最唬人、也最容易用歪的一个功能——子代理。

名字一听就高级，「多代理并行」，仿佛你一个人指挥一支小分队。我刚摸到这功能那阵，确实飘了一下，恨不得把每个任务都拆成五六个 agent 一起跑，觉得这才叫「专业玩法」。

但说句实话：Codex 的子代理跟你在别处见的不太一样，有个反直觉的设定你必须先知道——别指望它看到复杂任务就一定主动拆。 当前 Codex 会在你明确要求并行时委派，也会遵循适用的 AGENTS.md 或 Skill 委派指令。你想稳定触发，就把「开几个 agent、怎么分工、是否等齐」说清楚。

这一篇我不光教你怎么唤起子代理、怎么写自定义 agent、怎么给不同 agent 挑不同模型，更重要的是帮你想清楚那条线：什么活值得拆出去并行，什么活拆了纯属给自己添堵又烧钱。

看完这一篇，你会拿到：

• 子代理到底是什么——把活儿拆给一批专项 agent 并行跑、再汇总，和「单个 agent 闷头干」差在哪
• 它真正解决的两个老毛病：上下文污染（context pollution）和上下文腐烂（context rot），以及那条反共识的线：什么时候别拆
• Codex 自带的三种内置 agent（default / worker / explorer）——是「类型」不是「实例上限」，开箱即用、不用配
• 怎么写自定义 agent：往 ~/.codex/agents/ 或 .codex/agents/ 丢一个 TOML 文件，必填三个字段是干嘛的
• 怎么给不同 agent 选不同模型和「思考强度」，让侦察兵用快模型、审查员用强模型
• 手把手实战：写一个只读侦察 agent，派它跑、验证它只回摘要、不越权

⚠️ 下文凡涉及具体命令、配置键、默认值，都以 Codex 官方子代理文档 为准；模型名和推理强度会随版本变化，选择时以你本地实际显示为准。

Codex 子代理的独立线程与工作方式

先给结论：子代理就是 Codex 临时派生出来的一批专项 agent——它们各自在独立的线程里干活，干完不把过程中翻的一堆原始资料倒回来，由 Codex 统一收成一份结论交给你。

类比：把一个大案子拆成几路侦探同时查。 你是探长（主线对话），手上一个复杂案子，比如「把这次改动从安全、性能、测试三个角度审一遍」。这三路互不挡道，你犯不着自己一个人顺着查三趟。于是你派出三路侦探：一路专盯安全漏洞、一路专盯性能、一路专盯测试缺口，三人同时出门、各查各的。查完了，他们不会把翻过的几百页卷宗全堆回你桌上，而是各递一份摘要：「安全这块有两处风险，在 X 和 Y」。你最后拿到的，是一份按角度归好类的汇总。

这批侦探有几样东西是「他们自己的」，跟你这条主线隔开。官方把术语理得很清楚，值得记一下：

Subagent：Codex 派生出来、用来处理某个具体任务的受托 agent。 Agent thread：某个 agent 的 CLI 线程，你能用 /agent 进去查看、来回切换。

拆开看，一个子代理可以拥有这么几样「独立」的东西：

最关键的一点，也是 Codex 子代理的灵魂：它的价值是「把吵闹的中间产物搬出主线」。官方原话——让主 agent 专注在需求、决策和最终产出上，把探路、跑测试、翻日志这些会刷一大屏的脏活丢给子代理并行干，子代理只回摘要、不回原始输出。

这一点决定了子代理「擅长什么、不擅长什么」，下一节就靠它来判断。

这张图把子代理的运作方式画成了一条线：主线 agent 把一个大任务拆开、分发给几路子代理并行干，每路子代理都待在自己独立的上下文里（探路的、跑测试的、翻文档的互不污染），干完只把一份摘要回传给主线——那些刷屏的原始细节全留在各自线程里，主线始终清清爽爽。

💡 一句话总结：子代理 = 一批带独立线程、可独立配模型和权限的专项 agent，各自并行干活、只把摘要汇总回主线；核心价值是「把吵闹的中间产物搬出你的主对话」。

Codex 子代理适合处理哪些任务

知道了「是什么」，得搞清「为什么要有它」。官方把子代理要治的病说得特别直白，就俩词，你记住这俩词，这功能你就懂了一半。

上下文污染：关键信息被中间输出淹没

类比：一桌正经文件里混进一摞外卖单。 你的主对话本来摊着正事——需求、约束、定下来的决策。结果你让它「把整个测试套件跑一遍」，哗啦刷出几百上千行测试日志，全糊在桌上。有用的那几句「哪几个挂了」，被埋在一摞没用的中间输出底下，你想找都得扒半天。 这就是上下文污染：噪声把信号盖住了。

官方定义：

Context pollution（上下文污染）：有用的信息被吵闹的中间输出埋没。

真实场景：我去年调一个第三方接口，让 Codex 反复试调、每次刷一屏 JSON 返回。聊到第十几轮，我回头想确认「最初的需求是不是字段 A 必填」，往上翻——全是 JSON，翻了快二十屏才找到那句话。那一刻我就懂了，会刷大量中间输出的活，根本不该在主线上摊开干。

上下文腐烂：无关细节持续降低可靠性

类比：会议开太久，人就开始走神。 一场会，前一个钟头大家还紧扣议题；拖到第三个钟头，桌上堆满了跑题的细节、临时岔出去的话头，决策质量肉眼可见地往下掉。模型也一样——对话越填越满、越填越杂，它的表现会随着「不相关的细节」越积越多而慢慢变差。

官方定义：

Context rot（上下文腐烂）：随着对话被越来越多不那么相关的细节填满，表现逐渐变差。

这俩病的药方是同一个：把吵闹的活搬出主线，扔给子代理并行干，让它们只把提炼过的摘要交回来。 官方还举了个极端例子——一份几百万 token 的大文档，Codex 能拆成若干小块、派多个子代理分头啃，每个只把「嚼出来的要点」回传主线。主线始终清清爽爽。

哪些任务不适合拆给子代理

好，病说清了，回到开头那句——为什么「一上来就拆」是错的？

因为子代理不是免费的。官方反复强调一条成本：每个子代理都要自己跑模型、自己调工具，所以子代理工作流比同等的单 agent 跑法更烧 token。 拆得越多，烧得越多。还有第二条隐性成本——并行写比并行读危险得多：

起步时，把并行 agent 用在偏读的任务上，比如探路、跑测试、分流、做摘要。偏写的并行工作流要更小心，因为多个 agent 同时改代码会撞车、还会增加协调成本。

我把官方的取舍提炼成一张对照表，这是本节最该带走的东西：

真实场景：我有阵子犯轴，连「把这个函数名改清楚」都想喊一句「开个 agent 去改」，图个「显得专业」。结果纯属添堵——派生、跑模型、回传，一圈下来比我直接在主线说「把这名字改了」慢一截，还白烧 token。从那以后我立了条铁规矩：一句话能说清、改动就在眼前的活，绝不拆。

💡 一句话总结：子代理治的是「上下文污染 + 上下文腐烂」两个病——把吵闹的偏读活搬出主线并行干；但小修改、强依赖、并行写这三类别碰，拆得多 ≠ 专业，过度拆只会又慢又贵又撞车。

下面这张图把「拆与不拆」的判断和「拆出去之后怎么跑」串成一条线：

这张图在干什么：先判断「该不该拆」，不该拆就留主线；该拆且你开了口，Codex 才派出几路 agent 并行，等齐所有结果后汇总成一份交回主线——注意那个「你开口」的岔口，没它 Codex 不会自己拆。

使用内置 Agent 触发并行委派

讲完「该不该用」，来真的拆一次。好消息是：Codex 自带三种内置 agent，开箱即用，你一行配置都不用写。

⚠️ 这里说「三种」不是「三个」，差别很关键：default / worker / explorer 是三种类型（角色），不是「同时只能开三个」。实际派活时，你可以同时启动多个同类型实例；并发上限由 agents.max_concurrent_threads_per_session 控制，未设置时由 Codex 选择，不要再照旧教程写死为 6。

官方给的三种内置 agent：

光有 agent 还不够，得有人喊它们出门。这里是 Codex 最该记牢的一条规矩：想稳定触发，就在话里明说要并行。 除了直接请求，当前 Codex 也会遵循适用的项目指令或 Skill 委派要求；但普通任务不要赌它一定主动拆。

所以「唤起」靠的不是什么特殊语法，就是你把话说清楚——明说怎么分活、要不要等齐、最后回什么。官方原话给的是「spawn two agents」「delegate this work in parallel」「use one agent per point」这种直白指令。一个写得好的子代理 prompt，官方说该讲明三件事：怎么分工、要不要等所有 agent 都完事再继续、最后回什么样的摘要。

照着官方的样子，你可以直接在 Codex 里这么说：

用并行子代理审一下这个分支（当前分支 vs main）。开一个 agent 专盯安全风险、一个专盯测试缺口、一个专盯可维护性。三个都等齐，再按类别把发现汇总，带上文件位置。

类比：你是导演喊「分镜同时拍」。 不喊就一条线顺着拍；你喊一句「这三场戏三个机位同时开拍，拍完都给我」，剧组才会分头行动。这句「同时开拍 + 都给我」就是你的派生指令——机位（agent）一直在，等的是你这声令下。

干起来之后，编排全由 Codex 自己扛——官方说它负责派生新 agent、转达后续指令、等结果、关掉干完的线程；多个 agent 在跑时，它会等到你要的结果全齐了，再返回一份汇总响应。

真实场景：我第一次用这功能审 PR，照着官方那条「spawn one agent per point」的 prompt 把六个审查点一次性甩出去，本来以为要等很久，结果几路并行下来，比我自己一条条问快了一大截，最后拿到的是按六个点归好类的一份汇总。那次我才真正体会到「并行」省的是什么——省的是你来回等的那几趟串行时间。

ℹ️ 当前 Codex app、CLI 和 IDE 扩展都能显示子代理活动，只是查看入口不同：CLI 用 /agent 切换线程，App 可打开子代理线程，IDE 在后台 Agent 面板可用时显示状态和入口。

💡 一句话总结：三种内置 agent（default / worker / explorer，是类型不是实例上限）开箱即用；想稳定触发就明说「开几个 agent 并行、等齐、回汇总」，也可以把委派要求写进适用的 AGENTS.md 或 Skill。

使用 /agent 查看和管理子代理线程

几路 agent 同时在跑，你总得有办法看它们干到哪了、甚至临时改主意。Codex 给了两个抓手。

使用 /agent 切换和查看线程

官方给的命令是 /agent（注意是单数，不是 /agents），在 CLI 里用它在几条活跃 agent 线程之间来回切换、查看某条线程当前在干嘛。

/agent

注意这跟你印象里别的工具可能不一样——它不是「运行某个 agent」的命令，而是「进去看 / 切线程」的命令。派生靠你说话，查看才靠 /agent。

直接要求 Codex 调整或停止线程

更顺手的是直接跟 Codex 说。官方原话：你可以直接让 Codex 去操控某个在跑的子代理、叫停它、或者关掉已经干完的 agent 线程。不用记什么子命令，大白话指挥就行，比如「把那个还在跑的探路 agent 停了」。

类比：你是调度台，对讲机随时插话。 几辆车在外面跑，你既能切到某个频道听某辆车的实时汇报（/agent），也能直接对着对讲机喊「3 号车别查了，回来」（喊话指挥）。车在外面自己跑，但方向盘的最终话语权一直在你手里。

这里还有个审批上的坑，官方专门讲了，值得知道：在交互式 CLI 里，审批请求可能从一个你没在看的 agent 线程里冒出来。 比如你正盯着主线，某个后台 agent 撞到要审批的操作，弹窗会标出是哪条线程发的——这时你可以按 o 先跳进那条线程看看上下文，再决定批不批、拒不拒、或怎么答。要是在非交互式流程里（比如脚本跑），冒不出新审批的操作会直接失败，并把错误抛回上层工作流。

💡 一句话总结：管在跑的 agent 两招——/agent（单数）进去切线程 / 看进度，或直接喊话让 Codex 停掉、操控、收尾某个 agent；交互式 CLI 里别的线程也可能弹审批，按 o 能跳进去看了再批。

创建 Codex 自定义 Agent

内置这三种 agent 能应付不少场景，但你要是发现自己老在重复同一类活——每次审查都强调「像 owner 那样审、盯正确性和安全」——那就该把这套固化成一个自定义 agent，下次一句话唤起。

怎么写：往 agent 目录丢一个 TOML（Tom’s Obvious Minimal Language，一种简洁的配置文件格式，比 JSON 更适合人读写）文件，一个文件定义一个 agent。 官方给的两个位置：

类比：给某一路侦探建一份「专属档案」。 内置那三位是公司随时能调的通用编制；你写的 TOML，是给某个专精方向的侦探单独立的档案——叫什么名、专攻什么、办案守则是什么、给他配什么级别的装备（模型）。立好档，以后点名就能调。

一个自定义 agent 文件长这样，必填只有三个字段：

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.
"""

把字段拎出来说清楚（官方 schema 原样）：

为不同 Agent 选择模型和推理强度

这是自定义 agent 最香的地方——让每路 agent 用最匹配的脑子。两个旋钮：

• model：用哪个模型。官方思路仍是「侦察用快的、审查用强的」——偏读、扫大文件可用当前列表里更快、更省的模型；审查和多步复杂逻辑用能力更强的模型。具体模型名随版本变化，以当前模型列表为准。
• model_reasoning_effort：推理强度。可选档位取决于模型，当前配置可能包含 low、medium、high、xhigh、max 或 ultra，不要假设每个模型都支持全部档位。

把它俩落到文件里，给侦察兵选择当前可用的快速模型和中等推理强度；如果不想把易变模型名写死，也可以省略 model，让它按继承与全局配置规则解析：

# .codex/agents/explorer.toml —— 只读侦察兵：快、省、不动手
name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes."
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless asked.
"""

注意上面那行 sandbox_mode = "read-only"——这就是给单个 agent 单独拧权限。官方说子代理默认继承你当前会话的沙箱策略，但你能在 agent 文件里给某一个单独标成只读，让这路侦察兵想动手也动不了。

⚠️ 一个权限上的优先级坑：你在会话里临时改的运行时设置（比如 /permissions 调整、--yolo），会被重新套用到派生出的子代理身上——哪怕那个 agent 文件里写了不一样的默认值。也就是说你会话里的实时选择，盖过 agent 文件里的静态默认。

还有一类全局 [agents] 配置，管的是所有子代理的「总闸」，写在你的 config.toml 里（不是单个 agent 文件）：

旧配置里的 agents.max_threads 仍可作为兼容别名，但新配置优先写当前字段名。并发越高，token、延迟和本机资源消耗越大，偏写任务还会增加文件冲突。

💡 一句话总结：自定义 agent 就是 ~/.codex/agents/ 或 .codex/agents/ 下的一个 TOML，必填 name / description / developer_instructions；可选字段不写就继承父会话，靠 model + model_reasoning_effort 给侦察兵配快脑、给审查员配强脑，还能 sandbox_mode 单独锁权限。

创建并验证只读侦察 Agent

光看不练假把式。下面带你手写一个最小的自定义 agent，再让它真的跑起来，亲眼看到「侦察兵探完路、只回结论、不越权」这条链路。全程不依赖复杂环境。

我们建一个最简单的：一个只读的「项目侦察兵」，专门读代码、回报结构和潜在问题，但一个字都不准改（靠 sandbox_mode = "read-only" 锁死）。

第一步：建一个玩具项目和 agent 目录（Mac / Linux）

mkdir sub-demo
cd sub-demo
mkdir -p .codex/agents

预期：sub-demo 文件夹里有了 .codex/agents/ 这层目录。敲 ls .codex 能看到 agents 在里头。

Windows 用户用 PowerShell：mkdir sub-demo; cd sub-demo; mkdir .codex\agents -Force 。后面 echo、cat 也对应换成 PowerShell 写法。

第二步：手写自定义 agent 文件

用你顺手的编辑器，新建 sub-demo/.codex/agents/scout.toml ，贴入：

name = "scout"
description = "只读的项目侦察兵，读指定文件、回报结构与潜在问题，不动手改。"
sandbox_mode = "read-only"
model_reasoning_effort = "low"
developer_instructions = """
你是一个只读的代码侦察兵，只探路、不改代码。
被派来时：
1. 读用户指定的文件
2. 按可读性、命名、潜在 bug 三类列出问题
3. 每条给一句改进方向，但绝不修改任何文件
最后只回一份精炼摘要，别把原始代码整段贴回来。
"""

注意这里没写 model 字段——按官方默认，它会从你的父会话继承模型。sandbox_mode = "read-only" 把它钉死成只读，它想写也写不了；model_reasoning_effort = "low" 让这种轻活跑得快些。

第三步：造一段「有改进空间」的代码给它侦察

echo 'def f(a, b):
    return a / b' > calc.py

这个函数名 f 、参数名 a / b 都很烂，还没处理除以 0——正好让侦察兵逮个正着。

预期：sub-demo 里有了 calc.py ，内容是上面那两行。

第四步：启动 Codex，明确让这个 Agent 去探

codex

进去后，明确点名让这个子代理去干，避免普通需求没有触发委派：

派 scout 这个子代理去侦察 calc.py，按它的守则只回一份问题摘要，别动文件。

预期：Codex 会派生 scout 子代理（在 app / CLI 里能看到这个 agent 线程在跑，可能带个昵称标签）。它在自己的只读线程里读完 calc.py ，然后只把一份「侦察摘要」汇总回主线——大致会指出：函数名 f 和参数 a / b 不达意、缺除数为 0 的处理、建议改成更清楚的命名并加边界判断。注意它只给方向、没动你的文件（因为它是 read-only）。想中途看它干到哪了，可以敲 /agent 切进它的线程瞄一眼。

第五步：验证它真的没改文件

退出 Codex，回终端看：

cat calc.py

（Windows PowerShell 用 type calc.py）

预期：calc.py 原封不动，还是那两行——这就是「锁权限」的威力：你把它钉成只读，它就算想帮你改也无能为力，只能动嘴。

跑通这五步，你就把「写 TOML → 明说派生 → 子代理在独立线程干活 → 只回摘要、不越权」这条完整链路亲手验证了一遍。以后任何自定义 agent，本质都是在这套机制上换指令、调模型、拧权限。

⚠️ 要是 Codex 没派生 scout、而是自己上手读了，多半是你没把「用子代理」说够明白——回到“使用内置 Agent 触发并行委派”，把「派 XX 子代理去」这种话说死，别让它以为你只是想要个结果。

💡 一句话总结：写一个 read-only 的侦察 TOML、明说「派 scout 去侦察」让它跑、再 cat 确认文件没被动——亲手跑通「独立干活 + 锁权限不越界」这条链路，比记十条字段都管用。

本篇小结

这一篇我们把 Codex 的「子代理」从「该不该用」一路讲到「怎么唤起、怎么写、怎么验证」——核心不是教你拆得多花哨，而是帮你建立那条「该并行还是自己干」的判断线，以及记牢 Codex 那个反直觉的设定：不开口它不拆。

把要点串起来回顾：

你现在应该能： 判断一个任务该不该拆给子代理（而不是一激动就拆）；用好内置三种 agent，或往 ~/.codex/agents/ 写一个带专属指令、专属模型、锁定权限的自定义 agent；并且记牢——得你开口它才拆，干完它只把摘要汇总回来。 这套「该并行就并行、该自己干就自己干」的分寸感，才是子代理真正的门槛——功能十分钟学会，分寸得用出来。

记住开头那句反共识的话：Codex 的子代理强，但它默认不替你做主——拆不拆、拆几个，话语权一直在你这儿。

下一篇 22「Agent Skills 技能」——到这儿你给 Codex 配的「外援」越来越成体系了：AGENTS.md 定规矩、斜杠命令攒快捷、MCP 接外部工具、现在又会拆子代理并行干活。但你有没有发现，子代理的「办案守则」还得每次写一长段 developer_instructions ？要是这套本领能打包成一个可复用的技能、随用随调，是不是更省事？下一篇就聊 Codex 怎么把一身本事沉淀成 Skill。