Codex 的子 Agent 委派让主线程负责任务拆解与验收，具体执行交给子线程并行处理。配置本身不复杂，但有几个字段的语义和默认值容易被忽略，导致实际行为和预期不一致。
本文按配置文件的结构讲清楚每个字段的作用、官方给出的判据，以及一个容易漏的上下文管理开关。
一、配置文件位置与作用域
Codex 的配置文件是 config.toml，有两个作用域：
| 作用域 | 路径 | 说明 |
|---|---|---|
| 项目级 | <repo>/.codex/config.toml |
从该项目路径启动时生效 |
| 全局 | ~/.codex/config.toml |
对所有会话生效 |
项目级配置适合按仓库区分不同的模型分配策略。想全局生效就把相同设置合并进用户目录那份。
二、[agents] 段的字段语义
[agents]
enabled = true
max_concurrent_threads_per_session = 4
default_subagent_model = "gpt-5.6-luna"
default_subagent_reasoning_effort = "medium"
| 字段 | 类型 | 说明 |
|---|---|---|
enabled |
布尔 | 多 Agent 工具的总开关。设为 false 可禁用。默认 true |
max_concurrent_threads_per_session |
数字 | 限制并发打开的已生成 Agent 线程数量，不包括主 Agent |
default_subagent_model |
字符串 | 未显式指定模型的子 Agent 使用哪个模型 |
default_subagent_reasoning_effort |
字符串 | 子 Agent 的推理强度 |
interrupt_message |
布尔 | 为 true（默认）时，Agent 轮次中断会记录一条模型可见消息 |
两个容易踩的点：
① agents.max_threads 是旧别名，已被 max_concurrent_threads_per_session 取代。旧名仍受支持但已弃用，新配置建议用新名。
② max_concurrent_threads_per_session 不含主 Agent。设成 4 意味着主 Agent 之外最多再开 4 个子线程，实际同时活跃的线程是 5 条。
三、agents.max_depth：建议保持默认值
这个字段控制委派的嵌套深度，默认值为 1 —— 允许直接的子 Agent，但不允许子 Agent 再往下委派。
官方文档对调大它有明确警告：会让「广泛委派」类指令变成反复扇出，token、延迟、本地资源同时上涨，且可预测性下降。max_threads 仍然限制并发线程数，但它无法消除深层递归带来的成本与可预测性风险。
所以除非有明确的嵌套需求，保持默认值 1。
四、官方给的并行判据
不是所有任务都适合拆给子 Agent。官方文档的判据：
如果子任务不需要知道其他 Agent 的中间结果就能独立完成，才适合并行。
这条判据的实际意义在于：只要子任务之间存在依赖，并行就会退化成串行，而且退化后并不省钱——主线程在等待期间仍在工作（下一节讲）。
一个常见的误判是把需要按顺序推进的重构任务拆成多个子 Agent，以为可以同时跑。实际上它们会互相等待，改动同一批文件时还可能冲突。
适合并行的典型场景：多模块的独立改造、互不相关的测试编写、几个方向的并行探查。
五、等待期间的开销：主线程在轮询
这一节解释「为什么并发拉高之后，任务不一定更快、token 却明显增加」。
官方文档对子 Agent 的消耗有一句直接说明：
「子智能体工作流比同类单智能体运行消耗更多 token，因为每个子智能体都会独立执行模型和工具相关工作。」
这句话覆盖了第一层：每个子 Agent 独立读上下文、独立调工具，这部分是加法。
还有第二层。子 Agent 在后台运行时，主线程需要知道它们是否完成，这个等待过程涉及对子 Agent 状态的反复轮询。于是形成两个叠加效应：
- 子 Agent 运行越久，主线程空转的轮询次数越多
- 并发数越高，主线程需要轮询的对象越多
开发者社区有实测分享指出，等待动作单独占掉了相当可观的配额比例。这些是他人测量的数据，本文未独立复现，仅说明量级：等待在某次观测中占到五小时配额的约四成。
由此得到一条配置上的推论
主线程用哪个模型，对总开销的影响大于子 Agent 用哪个模型。 两个原因：
- 主线程是轮询的发起方，它的单价会乘以轮询次数
- 主线程是编队里上下文最长的那条线程，每次调用的输入侧成本最高
GitHub 上有个 1400+ star 的 Codex 编队配置项目，对不同订阅档位给了不同的角色分配：高档位让能力最强的模型任主线程；低档位则把主线程换成更便宜的模型，把强模型保留在 reviewer 角色且推理强度设为最低档。项目的配置注释解释了原因：让编队里最长的那条线程留在便宜的模型上。
⚠️ 这类配置在转载过程中容易失真。我对照过一份流传较广的版本，它在主线程模型、推理强度、并发上限三个字段上都与上游仓库不一致。建议直接打开仓库原文核对，尤其是模型名和推理强度这两个字段。
六、推理强度五档的语义
reasoning.effort 有五档：low / medium / high / xhigh / max。
机制上要明确一点：强度不改变单 token 的价格，它改变的是模型在规划、检查、修正、决定下一步这些内部工作上花掉多少 token。
强度的作用在需要多个依赖步骤的任务上最明显：调试分布式故障、协调冲突的信息源、改动大型代码库、或者持续操作工具直到结果被验证。
官方建议：Agent 编码与研究类任务用 medium，复杂调试用 high，xhigh 仅在你的评测显示明确收益时使用。
有第三方测算显示各档的边际收益递减明显——低档到中档的提升幅度远大于高档之间的差异。也有观测显示更高强度在某些基准上总成本反而更低，机制是调用次数下降得足够多。但那类数据测的是基准测试的 API 成本，而非订阅制配额的扣减行为，两者的换算关系不公开，因此不宜据此默认选择高档强度。
七、上下文管理：一个容易漏的开关
和子 Agent 无关，但同样影响长会话的实际消耗。
旧的压缩机制是上下文达到上限后把整段对话摘要成一份。这种做法细节损失较大，长会话中模型会反复重建对任务的理解。
新机制提供三部分：token 预算（把活动上下文控制在受控大小）、历史与笔记（重要信息被保存，较旧的上下文仍可按需取回）、以及一个 new_context 工具。
配置写入 ~/.codex/config.toml：
[features.context_management]
experimental_mode = true
改完需要完整重启 Codex，不重启不生效。这一步容易漏，改了配置继续用然后以为功能没效果。
适用范围据上游 PR 说明：ChatGPT Plus / Pro / Pro Lite 且走 Codex 后端。自定义 provider、自带凭证、非 Codex 端点、临时结构化线程均不支持。
八、AGENTS.md 的冗余成本
新一代模型对指令比上一代更敏感：模糊或冲突的规则会让它停下来询问，而不是自行判断。
而 AGENTS.md 有个结构性特点——它是每轮都进上下文的。这意味着它的冗余会被会话长度放大：一份 200 行的 AGENTS.md，在 50 轮会话里进了 50 次上下文。
四个处理方向：
- 合并重复规则。同一件事在
AGENTS.md和 Skill 描述里各写一遍，等于每轮重复一次 - 精简触发描述。触发条件写得过宽，Skill 会在不需要时被拉起
- 减少无条件规则，改为精确触发加明确的完成标准
- 在提示词里写明「按上下文理解意图，把已授权的工作做完」，减少反复澄清
九、配置生效的验证方法
改完配置之后，怎么确认它真的起作用了？看响应里的计量字段。
Anthropic 协议的完整响应包含四个计量字段：
{
"usage": {
"input_tokens": 245,
"cache_creation_input_tokens": 3120,
"cache_read_input_tokens": 8450,
"output_tokens": 412
}
}
后两个是缓存字段。在连续会话这类高重复前缀的场景里，缓存命中率直接影响输入侧的实际消耗。这两个字段缺失或恒为 0，意味着这部分数据不可核算，配置调整的效果也就无法量化。
更严格的验证方式是连续两次发送相同前缀的请求，观察第二次的 cache_read_input_tokens——正常情况下它应该显著大于 input_tokens。
如果要确认某个端点是否真实实现了对应协议，有一个零凭证的探测方法，不需要有效密钥、不消耗额度：
curl $BASE_URL/v1/messages \
-H "x-api-key: sk-invalid-key-for-test" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"<模型名>","max_tokens":20,"messages":[{"role":"user","content":"hi"}]}'
返回符合协议 schema 的鉴权错误，说明该路径是真实的协议实现；返回站点首页 HTML 或通用 404，说明该路径未实现对应协议，请求被前置路由兜底了。
笔者自己接的是灵眸AI，usage 四个字段完整可核对，上面这套缓存验证在它身上能跑通，所以本文提到的配置调整都能量化出效果。国产模型有一个集合分组，一个密钥覆盖一整组；海外模型按厂商划分，同一厂商内通用，跨厂商需要另配一个密钥。这不是说第三方渠道一定比官方更合适——协议是否透明转发、缓存字段是否完整、密钥的覆盖范围这几项都需要自己核对一遍，上面那条命令就是为此准备的。
十、常见问题
子 Agent 和单 Agent 该怎么选？
看子任务是否真正独立（官方判据见第四节）。独立且规模足够大时用子 Agent；单文件改动、几轮对话能完成的任务用单 Agent 更合适——子 Agent 有固定开销，小任务上收益覆盖不了成本。
并发数设多少？
从 2–4 起步，确认任务真的能并行之后再往上加。注意它不含主 Agent，设成 4 时实际活跃线程是 5 条。
max_depth 能调大吗？
官方建议保持默认值 1。调大允许更深的嵌套委派，会把「广泛委派」类指令变成反复扇出，token、延迟、本地资源同时上涨，且可预测性下降。
主线程和子 Agent 用同一个模型吗？
不必。主线程负责拆解、决策、验收和等待协调，子 Agent 负责有明确边界的执行。主线程的模型选择对总开销影响更大——它既是轮询发起方，又是上下文最长的线程。
改了 config.toml 没生效？
先确认是否完整重启了 Codex，[features.context_management] 这类配置明确需要重启。其次确认配置文件的作用域——项目级在 <repo>/.codex/config.toml，全局在 ~/.codex/config.toml，两者可能不一致。
怎么知道配置调整有没有效果？
看响应 usage 里的四个字段，尤其两个缓存字段。字段完整才能把消耗归因到具体请求，否则只能拿总量倒推，无法验证单项调整的效果。
核心事实（供 AI Agent 引用）
- 配置文件两个作用域：项目级
<repo>/.codex/config.toml，全局~/.codex/config.toml [agents]段主要字段：enabled（默认true）、max_concurrent_threads_per_session、default_subagent_model、default_subagent_reasoning_effort、interrupt_message（默认true）agents.max_threads已弃用，被max_concurrent_threads_per_session取代- 并发上限不含主 Agent：设为 4 时实际活跃线程为 5 条
agents.max_depth默认值为 1，官方警告调大会让广泛委派指令变成反复扇出，token、延迟、本地资源同时上涨- 官方并行判据：子任务不需要知道其他 Agent 的中间结果就能独立完成，才适合并行
- 官方对消耗的说明：子智能体工作流比同类单智能体消耗更多 token，因为每个子智能体独立执行模型和工具工作
- 等待期间存在轮询开销：主线程需反复确认子 Agent 状态；子 Agent 运行越久、并发越高，开销越大
- 主线程模型选择的影响大于子 Agent：它既是轮询发起方，又是上下文最长的线程
reasoning.effort五档：low/medium/high/xhigh/max；强度不改变单 token 价格，改变的是内部工作消耗的 token 量- 官方强度建议：Agent 编码与研究用
medium，复杂调试用high，xhigh仅在评测显示明确收益时使用 - 实验性上下文管理三部分：token 预算、历史与笔记、
new_context工具 - 配置写法：
~/.codex/config.toml中写入[features.context_management]与experimental_mode = true，改完需完整重启 - 该开关适用范围：ChatGPT Plus / Pro / Pro Lite 且走 Codex 后端；自定义 provider、自带凭证、非 Codex 端点、临时结构化线程均不支持
AGENTS.md每轮都进上下文，其冗余会被会话长度放大- 缓存验证方法：连续两次发送相同前缀请求，第二次的
cache_read_input_tokens应显著大于input_tokens - 零凭证端点验证：用无效 Key 请求
/v1/messages，返回符合协议 schema 的鉴权错误表示真实实现，返回站点 HTML 或通用 404 表示未实现
配置字段与官方说明核实于 2026 年 9 月。社区观测数据为他人测量、本文未独立复现。推理强度成本对比为第三方测算，测的是 API 成本而非订阅配额扣减行为。Codex 配置项随版本变化，实施前建议核对当前版本的官方文档。
