Claude Code 嵌套子代理深度怎么配：默认 3 层与防失控清单

Claude Code 2.1.219 把嵌套子代理默认深度从 1 调回 3，并新增 workflowSizeGuideline 与 strictAllowlist。本文给出深度×场景决策表和防 runaway 配置清单。

Claude Code 嵌套子代理深度怎么配：默认 3 层与防失控清单

Claude Code 嵌套子代理深度怎么配：在 2.1.219（2026-07-24）里，默认 spawn 深度从 1 调回 3，环境变量 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 仍可覆盖；同时用 workflowSizeGuideline: "medium"（建议少于 15 个 agent）和 sandbox.network.strictAllowlist 给嵌套 fleet 加刹车。下面按「该开多深 → 怎么限流 → 无人值守怎么防挂」给出可直接复制的配置。

默认深度为何两周内变了三次

子代理嵌套深度在 2026 年 7 月经历了完整拉锯，搞不清时间线就容易配错环境变量。

版本区间 默认嵌套深度 可配置？ 备注
v2.1.172 – v2.1.216 5 层 否 子代理可继续 spawn，无公开上限 knob
v2.1.213 1 层 是（CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH） 硬 cap 并发与子代理 fleet，防 runaway
v2.1.219 3 层 是 官方 changelog 默认值；release note 写「was 1」

Anthropic 官方 release v2.1.219 的原话：「Subagents can now spawn nested subagents up to depth 3 by default (was 1); set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 to disable nesting」。深度 3 不是随手取的整数：据 Start Debugging 解读，它刚好覆盖「主会话 → 审查者 → 按 finding 派 verifier → verifier 内Focused lookup」这类 review fan-out，深度 1 时上述结构会塌缩成单个子代理顺序执行。

workflowSizeGuideline 与 medium 上限

2.1.219 把动态工作流的默认 size guideline 设为 medium，目标是少于 15 个 agent。这是建议性上限，不是硬顶；真正硬顶仍是并发数和 per-session 子代理限制（2.1.213 引入那套）。

在任意 settings 文件里写入：

{
  "workflowSizeGuideline": "medium"
}

设置后 /config 里对应行会隐藏，运行中的 workflow 状态行会打印当前 size，方便你看 fleet 是否膨胀。可选值除 medium 外，还可在 /config 的 Dynamic workflow size 里选其他档位或 unrestricted；具体枚举以当前版本 /config 界面为准。

要点：workflowSizeGuideline 塑造的是模型打算 spawn 多少 agent，不会单独拦住第 16 个；要和 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH、并发 cap 一起用。嵌套加深后 token 消耗会非线性上涨，可对照 Claude Code 配额消耗过快的原因与对策 里的 session 管理手段。

CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 环境变量

环境变量名以 v2.1.219 changelog 为准：CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH。若你本地文档或旧帖仍写 CLAUDE_*_MAX_SUBAGENT_SPAWN_DEPTH 其他变体，以官方 release 名为准。

常用配法：

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"
  }
}

写入项目或用户级 settings.json 的 env 块即可。设为 "1" 等于关闭嵌套（子代理不能再 spawn 子代理）；设为 "3" 与 2.1.219 默认一致；更高值是否生效、上限多少，以你安装的 Claude Code 版本 changelog 为准，不要凭社区帖写死。

CI 或无头跑法里，建议在 pipeline 镜像里显式 pin 深度，别依赖默认值——默认值已经变过三次，升级 overnight 可能改变 fleet 形态和账单。

sandbox.network.strictAllowlist 防无人值守挂起

嵌套加深后，并行进程更多，任一子代理碰到未 allowlist 的域名都可能触发交互式提示；无人值守环境里，没人点的 prompt 等于挂起。

2.1.219 新增 sandbox.network.strictAllowlist：设为 true 时，沙箱命令访问非 allowlist 主机直接拒绝，不再弹窗询问（与 managed 部署里的 allowManagedDomainsOnly 思路一致，但现在任何 settings 文件都能开）。

{
  "sandbox": {
    "enabled": true,
    "network": {
      "strictAllowlist": true,
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

headless、claude -p、远程 runner 场景建议默认打开。域名列表宁可少写，漏写的域名会 fail-closed 报错，比 silent hang 好排查。

深度×场景决策表

配深度前先对号入座，比盲目跟默认 3 更省 token。

场景 建议深度 理由
单文件 lint/fix、小范围 rename 1 无 fan-out，嵌套只会多 burn 上下文
标准 PR 代码审查（主 agent + 1 审查子代理） 1–2 一层委派足够；除非要 per-file verifier
多模块 review + 按 finding 并行验证 3 对齐官方 2.1.219 默认设计意图
全库探索 + 多假设并行（research spike） 2–3 + medium guideline 需要并行但要 workflowSizeGuideline 刹车
CI 无人值守批量任务 1 + strictAllowlist 禁嵌套降不可控性；网络 fail-closed
机械性子任务（扫描、模板生成） 1 + 专用子代理文件 用描述路由到便宜模型，见 Mistral 子代理省钱配置

深度和模型路由是两层决策：深度管「树有多深」，.claude/agents/*.md 管「每层用什么模型和工具」。深树配 Opus 全家桶，账单会比浅树高一个数量级。

防 runaway 配置清单

下面是一份可逐条勾选的 baseline，适合 2.1.219 及之后版本；旧版 ignore 不存在的 key 即可。

  1. Pin 深度：在 settings.json 的 env 里显式写 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH（本地开发 "3"，CI 建议 "1"）。
  2. Pin workflow 体量：设 workflowSizeGuideline: "medium"，跑长任务时盯状态行里的 size 提示。
  3. 网络 fail-closed：sandbox.enabled: true + sandbox.network.strictAllowlist: true + 最小 allowedDomains 列表。
  4. 子代理工具 allowlist：在 agent markdown frontmatter 里只开必要 tools（例如 mechanical 任务只留 Bash），避免深层节点带 Write 乱改。
  5. 会话边界：无关任务之间 /clear，避免主会话上下文把每一层嵌套都拖肥；大 refactor 拆成多个命名 session。
  6. 升级前读 changelog：默认深度、并发 cap、env 名都可能在 patch 版本里变；升级后跑一条已知任务对比 agent 数量。
  7. headless 加转发开关：需要审计嵌套输出时，2.1.219 支持 --forward-subagent-text 把 depth-2+ 子代理流打进 stream-json（见官方 release）；便于发现哪一层在狂 spawn。

嵌套本质是吞吐换可控性的杠杆，不是越深越好。默认回到 3 说明 Anthropic 认为 review fan-out 的收益大于 2.1.213 那版「全 flatten」的保守策略，但 advisory guideline 和 sandbox 网络锁意味着：默认更激进，约束责任在用户侧。

2.1.213 留下的硬 cap 仍然生效

容易误会「深度回到 3 = 完全放开」。2.1.213 引入的并发子代理上限和 per-session 子代理限制并未在 2.1.219 里撤销；变的是默认 spawn 深度和建议性 workflow 体量，不是「无限 fleet」。Start Debugging 在解读 2.1.219 时也强调：workflowSizeGuideline 管的是模型目标 spawn 数，真正天花板仍是 concurrency 与 session 级 cap。

实操上，如果你从 2.1.213 直接升到 2.1.219，会同时感受到两个方向的力量：深度 knob 默认更松（1→3），但 medium guideline 和 sandbox 网络锁又往回收。最稳的做法是：先保持 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 跑一条 baseline 任务，记录 agent 数量和 token；再改 "3" 对比差异，而不是升级当天直接跑生产 refactor。

headless 集成若已用 stream-json，2.1.219 还支持 --forward-subagent-text，depth-2 及更深子代理的文本/thinking 会按 spawning Agent 的 tool_use id 转发到主流。审计 spawn 树时，这条开关比事后猜「为什么 token 翻倍」省时间。具体 flag 行为以所装版本的 --help 输出为准。

常见问题

2.1.219 升级后子代理突然变多，是 bug 吗？

大概率不是。默认深度从 1 改到 3，同一 prompt 可能多 spawn 两层。若要保持旧行为，在 settings 里设 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1。同时检查是否启用了 dynamic workflow 且 size guideline 为 medium 仍允许较多 agent。

workflowSizeGuideline 设成 medium 还会超过 15 个 agent 吗？

会。官方 release 和第三方解读都强调这是 advisory（建议性），不是硬 ceiling。15 是 medium 档的目标参考；硬限制来自并发 cap 和 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH。要更紧就 pin 深度为 1 或选更小 guideline（以 /config 当前选项为准）。

strictAllowlist 和 allowManagedDomainsOnly 有什么区别？

allowManagedDomainsOnly 面向 managed 部署，由管理员强制 block 非托管域名。sandbox.network.strictAllowlist 是 2.1.219 起任何 settings 文件都能设的 fail-closed 开关：未 allowlist 的域名直接拒绝，不弹 prompt。无人值守场景优先用 strictAllowlist + 显式 allowedDomains。

参考资料