Codex 子代理运行机制与上限

这是关于 Codex 的 subagent（子代理）并行运行到底受什么限制、怎么配置、以及如何控成本 的一份速查说明。

什么时候会真的“跑出” subagents？

• 只有当你明确要求时，Codex 才会生成并运行子代理（例如提示里让它“并行开工/分派子任务”）。

真正限制数量与深度的开关（config.toml）

在 ~/.codex/config.toml（全局）或项目的 .codex/config.toml（仓库级）里的 [agents] 段落：

• agents.max_threads：并发子代理线程上限（默认 6）。

• agents.max_depth：嵌套层级上限（默认 1，根会话是 0）。

• agents.job_max_runtime_seconds：子工人/CSV 扇出任务的默认超时（未设时常见为 1800 秒）。
  这些键可以直接控制“能同时开多少个子代理、能嵌套多深、每个工人的最长跑多久”。

一次性覆盖 & 快速限流

无需改文件，也能在 单次运行里覆盖配置或模型选择：

• 直接用专用旗标（如 --model），或用 --config/-c 覆盖任意键：
  codex --model gpt-5.4-mini 或 codex -c 'agents.max_threads=4'。

配置层级与位置

• 全局：~/.codex/config.toml；

• 项目：.codex/config.toml；
  两者可叠加，项目级优先生效；App/IDE/CLI 共用同一套层级规则。

成本与时延的现实预期

• 子代理是独立的模型 + 工具会话，并行能提速，但令牌消耗与墙钟延迟也会增加；通常给“很多小工人”的场景选 更便宜/更小的模型 更划算（如 gpt-5.4-mini 或对应轻量档）。

小抄：常见任务怎么配

• 想要更可控的并行度：把 agents.max_threads 调低到 2–4。

• 需要更深的分解：把 agents.max_depth 从 1 调到 2，但记得也配合限流。

• 长耗时的批处理：适度上调 agents.job_max_runtime_seconds，或在调用处传 per-call 覆盖