Codex 子智能体

这篇适合谁、读完能做到什么

如果你希望 Codex 同时探索代码、跑测试、读日志，又不想让主会话被这些输出塞满，这篇适合你。读完你能让 Codex 启动子智能体（subagent）并行工作，会写委派指令，会选模型和推理强度，也能查看、引导正在运行的子智能体，并定义自己的智能体。^[1]

子智能体是什么

子智能体是 Codex 为某个具体任务启动的一个代理。子智能体工作流会并行运行几个子智能体，再把它们返回的结果合并成一次回复。每个子智能体在自己的线程（agent thread）里工作，支持的客户端里可以打开这个线程查看进展。^[1] 当前版本的 Codex 默认开启这一功能，ChatGPT 桌面 App、Codex CLI 和 IDE 扩展里都能看到子智能体的活动。^[1]

为什么要拆开干

对话越长，越难用。探索时产生的笔记、测试日志、堆栈信息和命令输出，会把真正重要的需求和决定埋住，这种情况叫上下文污染（context pollution）。对话里的无关细节越积越多，输出质量也会下降，这叫上下文腐化（context rot）。^[1]

子智能体把这些噪音挪到主线程之外。主智能体只保留需求、决定和最终产出；子智能体并行完成探索、测试或日志分析，返回的是摘要，而不是原始输出。^[1]

代价也要算清楚。每个子智能体都要做自己的模型调用和工具调用，所以同样的任务，子智能体工作流比单智能体消耗更多 token。^[1] 并行适合以阅读为主的工作，比如探索代码、跑测试、分诊和总结。以写代码为主的工作要更小心：多个智能体同时改同一处代码，容易冲突，还会增加协调的工作量。^[1]

怎么发起子智能体工作流

在 CLI、IDE 或 App 的对话里，直接要求 Codex 使用子智能体即可。如果项目的 AGENTS.md 或某个技能（skill）的说明里写了需要委派，Codex 也会照做。^[1] 在 CLI 里，/subagents 可以在各个智能体线程之间切换，在它运行时查看进展。主线程最后会把子智能体的结果汇总进最终回复。^[1]

怎么写委派指令

好的委派指令要说清三件事：怎么拆分工作，Codex 是否要等所有智能体都完成再继续，以及每个智能体要返回什么样的摘要或产出。^[1] 下面是文档给出的一个 PR 审查示例，每个审查点交给一个智能体：

I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code

多个智能体运行时，Codex 会等全部请求的结果都返回，再给出一份合并的回复。^[1]

怎么选模型和推理强度

如果子智能体没有单独设置模型或推理强度，它就继承主智能体的设置。^[1] 文档建议：复杂、多步骤、需要规划、调用工具和验证的任务，用 gpt-6.1-sol；快速、范围窄、重复性高或量大的任务，用 gpt-6-luna。两者都要求你的账户或工作区有使用权限。^[1]

推理强度从 low 到 ultra 有多个档位，能选哪一档取决于客户端和所选模型。high 适合需要追踪复杂逻辑、检查假设或处理边界情况的智能体，比如审查员或安全审查。low 适合简单、最看重速度的任务。强度越高，响应越慢，消耗的 token 也越多，但在难题上质量可能更好。^[1]

查看和引导正在运行的智能体

在桌面 App 里，可以从主线程的活动记录打开某个子智能体线程，看它做了什么。在 IDE 里，展开输入框上方的后台智能体面板，可以查看状态、停止所有活动的子智能体，或打开某个线程。^[1] 在 CLI、App 和 IDE 里，你都可以直接让 Codex 引导正在运行的子智能体、停止它，或者关闭已经结束的线程。^[1]

审批和沙箱

子智能体继承父回合的沙箱策略和审批设置。在 CLI 里，这包括中途用 /permissions 或 --yolo 做出的修改，自定义智能体文件无法替换这些设置。^[1]

在交互式 CLI 里，审批请求可能来自你没有在看的智能体线程。审批弹窗会显示请求来自哪个线程，按 o 可以先打开那个线程，再决定批准、拒绝或回答。非交互模式下，或者无法弹出新审批时，需要新审批的操作会直接失败，错误回报给父工作流。^[1]

内置和自定义智能体

Codex 内置三个智能体：default 是通用的兜底智能体，worker 负责实现和修复，explorer 负责以阅读为主的代码库探索。^[1]

自定义智能体要写成独立的 TOML 文件：个人使用的放在 ~/.codex/agents/，项目专用的放在 .codex/agents/。每个文件定义一个智能体，必须包含 name、description 和 developer_instructions 三个字段。^[1] 一个只读探索的智能体可以这样写：

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Stay in exploration mode.
Do not edit files.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
Prefer fast search and targeted file reads over broad scans.
"""

自定义智能体会继承父会话的权限、模型提供方和 MCP 服务器，文件里无法覆盖这些设置。所以 MCP 服务器要在主会话里配置，子智能体才能使用。^[1] 要限制某个智能体的能力，可以把 features.shell_tool、features.apps 这类功能开关设为 false，再用 skills.config 关掉单个技能。^[1]

全局设置

全局设置写在配置文件的 [agents] 下。agents.enabled 默认为开启。agents.max_concurrent_threads_per_session 限制同时打开的子智能体线程数，不含主线程。agents.default_subagent_model 和 agents.default_subagent_reasoning_effort 为子智能体设定默认模型和推理强度。agents.interrupt_message 默认为 true，智能体的回合被打断时，会在它的上下文里记录一条消息。^[1]

如果想在项目里把并发数限制为 8，就在 .codex/config.toml 里这样写：

[agents]
max_concurrent_threads_per_session = 8

实例：一个 PR 审查小组

审查任务可以拆给三个自定义智能体：pr_explorer 梳理代码路径、收集证据；reviewer 找正确性、安全和测试方面的风险；docs_researcher 通过专门的 MCP 服务器核对框架或 API 文档。^[1]

常见问题

• token 消耗涨得很快。 每个子智能体都在独立工作，只有能拆成互不依赖的小块时，才适合并行。^[1]
• 并行改代码互相冲突。 并行适合阅读和检查；多个智能体同时改代码时要格外小心。^[1]
• 审批好像卡住了。 在 CLI 里看审批弹窗上的来源线程名，按 o 打开它。^[1]
• 非交互模式在新审批处失败。 这种模式下无法弹出审批，应当在运行前就在父会话里设好权限。^[1]

下一步

这些设置可接受的取值，以及各个模型的说明，可以参考 Codex 官方文档。^[1]