奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

Codex 多代理配置怎么定：并发上限、子代理默认模型与角色定义

2026-08-09

Codex（OpenAI Codex）的多代理不是一个开关，而是两层开关加六个键。很多人第一次翻 config.toml 会直接搜 subagent，搜到两个键就以为配完了，结果并发上限还是不知道设在哪、角色也没被选中。这篇按官方《Configuration Reference》里的键位把这一组讲清楚，重点放在官方没给默认值的那几个键你该怎么自己定。

一、先认清这一组键的边界

官方配置参考里，多代理相关的键集中在 agents 这张表下：

键官方给的说明 / 默认值
agents.enabled默认 true
agents.max_concurrent_threads_per_session每会话并发线程上限（官方未给默认值）
agents.max_threads上一个键的旧别名
agents.default_subagent_model子代理默认模型
agents.default_subagent_reasoning_effort子代理默认推理强度
agents.interrupt_message默认 true
agents.<name>.description角色选择用的说明
agents.<name>.config_file该角色的 TOML 配置层路径

除此之外还有一个更上层的特性开关：features.multi_agent，官方标注默认 true，说明是「启用多代理协作工具」。

第一个要建立的判断：features.multi_agent 和 agents.enabled 是两个键，不是一个键的两种写法。官方文档没有说明两者同时为假/为真时谁压过谁，所以不要靠推理，靠命令看生效值——这一点第五节会给具体做法。

第二个要注意的是这张表的留白。max_concurrent_threads_per_session、default_subagent_model、default_subagent_reasoning_effort 这三个键，官方在配置参考里没有给默认值。这意味着你在动的是一个自己不知道原值的旋钮。改之前先把原状态记下来（哪怕只是记一句「我没配过这个键」），出问题时才知道往回退到哪。

二、并发上限：max_concurrent_threads_per_session 与旧别名

agents.max_threads 是 agents.max_concurrent_threads_per_session 的旧别名。你在网上看到的老配置片段可能还写着 max_threads，能不能用、和新键同时出现时以谁为准，官方配置参考没有说明，我也不打算替它猜。实际建议只有一条：新写的配置只写新键名，看到别人的老片段先换成新键再用，别两个都留着——留着你就得赌一个没有依据的优先级。

那么这个数该定成多少？官方没给推荐值，能拿来判断的是三条有依据的现实约束。

第一条是用量口径。 官方《Pricing》页写明，Codex 的用量计量单位是 messages（消息数），窗口是 5 小时滚动窗口，Plus 是 10–2,000 messages / 5h、Pro 是 50–40,000 messages / 5h，区间随模型（Pro 还随档位）变化（ChatGPT 官方定价页，2026-08-09 核对，以官方为准）。并发线程多开，意味着同一个 5 小时窗口里产生的消息更多。官方给的区间跨度极大，谁也没法替你算「开 4 路会不会撞上限」，但方向是明确的：并发上限本质上是一个额度消耗速率的旋钮，不是一个纯性能旋钮。

第二条是本地落盘。 在 codex-cli 0.147.0（Windows 11）上执行 codex doctor --summary，Notes 区会有一行 rollouts，本机显示的是 405 个活动文件、磁盘占用 3.07 GB。会话产物是实打实落在 ~/.codex/sessions/ 下的。开并发之前，先跑一次 doctor 看看这行数字——如果它已经很难看了，先解决磁盘再谈并发。

第三条是你现在没有的护栏。 想给并发配一个 token 层面的成本上限？在 codex-cli 0.147.0（Windows 11）上，codex features list 里 token_budget 处于 under development 阶段、生效值 false；配置参考里 features.rollout_budget.enabled 同样标注 under development、默认 false。也就是说，截至这个版本，你没有一个稳定可用的预算护栏来兜住并发跑飞的情况，只能靠自己把上限设保守一点。

综合下来，一个务实的起手式是：先设一个小值跑几天，观察额度和磁盘，再考虑要不要往上加。临时试值不用改文件，-c 支持点号路径：

codex -c agents.max_concurrent_threads_per_session=2

三、子代理默认模型：这是最值得单独设的一个键

agents.default_subagent_model 之所以值得单独设，是因为主会话和子代理干的活往往不是一个量级，而模型单价的差距是量级级别的。

官方《Pricing》页给出的积分单价（credits / 1M tokens）里，GPT-5.6 Sol 的 Input 是 125、Output 是 750；GPT-5.6 Luna 的 Input 是 5、Output 是 30（ChatGPT 官方定价页，2026-08-09 核对，以官方为准）。直接从这张表能算出两条比例关系：三档之间输入单价差 25 倍，输出单价同样差 25 倍；而同一个模型内部，输出的单价是输入的 6 倍。

这两条比例给出的判断依据是：如果子代理承担的是「读一堆东西、给一小段结论」这类活儿，它的输入量大、输出量小，把它压到便宜档位省下来的是实打实的量级差；反过来，如果子代理要自己做复杂决策并写出大量内容，省的那点单价可能换不回质量损失。官方《Models》页对推理强度的选择原则给的原话是「选够用的最低档」，这个原则同样适用于选模型。

但有一个坑必须先说清楚：官方《Models》页明确写了 gpt-5.6-terra 与 gpt-5.6-luna 在 Codex cloud 上不可用，云端能落的只有 gpt-5.6-sol；而且 Codex cloud 是自动选择模型的，不是你本地配什么云端就用什么。所以如果你的流程有一段会跑到云端，default_subagent_model 写成 luna 并不会让云端也跟着变便宜。（云端部分为官方文档口径，非本机实测。）

顺带一提模型退役：官方原文是 GPT-5.4 与 GPT-5.4 mini 于 2026 年 8 月 31 日从 Codex 退役，迁移映射为 gpt-5.4 → gpt-5.6-terra、gpt-5.4-mini → gpt-5.6-luna。官方点名要一起改的地方里就包含自定义 agent——如果你给某个角色单独指定过 gpt-5.4，光改主会话模型是不够的。以官方最新说明为准。

四、推理强度与角色定义

agents.default_subagent_reasoning_effort 官方在配置参考里没有单列取值枚举。相邻的 model_reasoning_effort 给的枚举是 minimal / low / medium / high / xhigh，能不能逐字套到子代理这个键上，以官方文档为准，我这里不替它下结论。

这里还有一个特别容易混的地方。官方《Models》页讲推理强度时用的是 UI 侧的档位名——Light/Low、Medium、High、Extra High，外加两个特殊模式 Max（对单个问题启用扩展推理）和 Ultra（派生子代理并行处理任务）。UI 上这套名字和 config 取值 minimal…xhigh 不是同一套字符串，官方也没有给映射表，所以别把「我在配置里设了 xhigh」当成「我选了 Ultra」，更别以为设置 agents.* 就等于打开了 Ultra 那个模式。这两个入口的关系，官方文档在我核对的这几页里没有说明。

角色定义则是两个键：

  • agents.<name>.description：官方对它的说明是「角色选择用的说明」。注意这个定语——它是用来选角色的依据，不是写给人看的注释。写成「测试相关」这种含糊的描述，选不选得中就随缘了；把这个角色处理什么输入、产出什么、什么情况下不该用它写进去，才是这个键该有的样子。
  • agents.<name>.config_file：该角色的 TOML 配置层路径。注意「配置层」这个词，Codex 的配置是叠加的：CLI 侧 -p, --profile <CONFIG_PROFILE_V2> 的说明是把 $CODEX_HOME/<name>.config.toml 叠加到基础用户配置之上（本机 codex --help 实测原文，codex-cli 0.147.0 / Windows 11）。但 profile 和 agent 的 config_file 是两个不同入口，两者同时存在时的叠加顺序官方没有说明，别按直觉排。

最后是 agents.interrupt_message，官方配置参考只给了键名和默认值 true，没有展开说明它的行为。名字看着像那么回事，但按字面猜出来的语义不能当依据用——需要的话去查官方文档，别照着名字写代码。

五、一段可参考的配置与验证流程

[agents]
enabled = true
max_concurrent_threads_per_session = 2
default_subagent_model = "gpt-5.6-luna"

[agents.reviewer]
description = "只读代码评审：读取指定改动范围，输出问题清单，不修改任何文件"
config_file = "~/.codex/agents/reviewer.config.toml"

以上为按官方文档键位组合的示例，未逐项实测，以官方文档为准。路径一律用 ~/.codex/... 的写法，别把自己的用户目录贴到公开的配置片段里。

改完之后必须验证，因为 Codex 在配置出错时的表现比你想的宽容——宽容到你察觉不到它没生效。验证按这个顺序走：

第一步，看配置有没有被加载。 跑 codex doctor --summary，盯 Configuration 分组里的 config 那一行。在 codex-cli 0.147.0（Windows 11）上故意执行 codex -c 'features=[unclosed' doctor --summary，doctor 照常跑完没有崩，但那一行变成了：

✗ config       config could not be loaded - Fix the reported config error, then rerun codex doctor.

这条实测结论的价值在于：「改完配置没生效」的第一步排查不是重启，是跑 doctor 看这一行。

第二步，看特性的生效值。 codex features list 会打出三列：特性名、所处阶段、当前生效值。在 codex-cli 0.147.0（Windows 11）上，multi_agent 这一行是 stable / true。想临时关掉多代理试问题是不是它引起的，用 --disable multi_agent（等价于 -c features.multi_agent=false）；想写进配置文件则是 codex features disable multi_agent。

读这张表时留个心眼：阶段值一共观测到五种——stable、under development、experimental、deprecated、removed。而 removed 的项仍然会出现在列表里，且生效值可能是 true（在 0.147.0 上 steer 就是 removed 且生效值为 true）。所以 removed 指的是这个开关不再需要你控制、行为已经固化，不等于功能没了。

第三步，别指望 --strict-config 兜住拼写错误。 它的作用是配置里出现本版本不认识的字段时报错退出，但在 codex-cli 0.147.0（Windows 11）上执行 codex -c model_reasoning_effortt=high --strict-config exec --help，命令正常打印了 help，没有报未知字段错误——说明校验发生在真正加载配置去跑会话的路径上，--help 这类不进入会话的路径不触发。同理，-c 的 value 是按 TOML 解析的，解析失败会按字面字符串处理，所以 -c agents.enabled=flase 这种拼错不会立刻报错给你看，它会安静地变成一个字符串。

要把诊断结果发给别人排查，用 codex doctor --json，官方说明是「Emit a redacted machine-readable report」——是脱敏报告。

六、什么情况下别动这组配置

  • 只是想让一次任务跑快点：并发上限是会话级的资源与额度旋钮，先把任务本身拆清楚，比调这个键有用。
  • 想靠它做成本控制：目前不行。能兜住成本的 rollout_budget / token_budget 在 0.147.0 上还处于 under development 阶段且默认关闭，别把希望寄托在还没稳定的开关上。
  • 团队里其他人也用同一份配置：default_subagent_model 改小了，别人可能在依赖原来的档位；这类会影响他人产出质量的键，改之前打个招呼。
  • 流程会走到云端：先确认模型在云端可用（官方口径下 terra 与 luna 在 Codex cloud 不可用，且云端自动选模型），否则本地这套模型配置到了云端就是空转。

相关阅读

本文依据 Codex 官方文档（learn.chatgpt.com/docs/ 的《Configuration Reference》《Models》《Pricing》页面）整理，核对日 2026-08-09；文中标注「本机实测」的部分基于 codex-cli 0.147.0 / Windows 11 环境下的只读命令输出。产品功能、模型与价格以官方最新说明为准。价格与活动随时可能调整，下单前请以官方页面为准。桌面应用与云端部分为官方文档口径，非本机实测。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员