Claude Code 子代理：省下什么，又花掉什么

子代理是 Claude Code 在你的会话内启动的独立 Claude 工作进程。它有自己的上下文窗口、系统提示和工具，在自己的窗口中读取、搜索、运行命令，最后只交回结果。Claude 也会自行委派任务，例如需要搜索代码时交给内置的 Explore 子代理。

因此，子代理节省的是主对话的上下文空间，不一定节省总 token。读取过程不会进入主对话，所以主对话保持简短；但所有代理处理的 token 总量可能更高，因为每个子代理都要为自己的启动和探索付费，同时运行多个还会把两项成本叠加。

子代理要支付哪些成本

子代理开始时没有你的对话历史、已经调用的技能或 Claude 读过的文件。它依据 Claude 写的一条任务交接消息工作。它的每次请求都携带：

• →它自己的系统提示（比主会话短），以及它可用的工具，包括 MCP 工具。
• →你的 CLAUDE.md 文件和一份 git 状态快照。内置 Explore 和 Plan 子代理会跳过两者，从而降低启动成本。
• →任务消息，以及其定义中预加载的所有技能的全文。

然后它运行自己的代理循环。每次工具调用的结果、每个读过的文件和每条命令的输出都会进入其上下文，下一步会重发不断增长的内容。搜索越久，循环成本就越会超过启动成本。

缓存的帮助也不如主对话大。子代理的前缀与主对话不同，因此首次请求不能读取主对话的提示缓存，启动内容需要全新处理。之后建立的缓存默认仅保留五分钟；即使订阅主对话可保留一小时，也是如此。subagentPromptCacheTtl 可把有效期提高到一小时，但缓存写入价格也更高。

最后，结果返回主对话：子代理的最后一条消息，外加一段简短的 token 计数和耗时信息。它会进入你的对话，并在之后每轮重发。因此，只要求两行结论的子代理，比要求完整报告的子代理更少增加主对话成本。

它省下了什么

省下的是子代理读取和运行、却从未进入主对话的内容：为了找到一个函数打开的十几个文件，或三次失败测试背后几千行的输出。如果在主对话中做，这些内容会一直留在上下文，直到清空或压缩前每轮重发。缓存会降低重复读取价格，却仍消耗用量上限，也仍挤占模型推理所用的窗口。

Claude Code 文档举了一个典型例子：研究型子代理读取约 6,100 token 的文件，主对话只收到 420 token 的结果。主上下文只增加了结果；读取仍在子代理自己的窗口中计费。

所以，当子代理挡住大量内容、主会话又还有许多轮时，它可能划算；任务很小，或必须重新读取主对话已有内容时，它可能更贵。

什么时候子代理划算

• →探索不熟悉的代码，而且读到的大部分内容最终无关。
• →输出很多但只需要结论的操作：把测试运行归结为失败项，把日志归结为错误，把一页文档归结为一个答案。
• →长期任务。主会话之后的轮数越多，每个未进入主上下文的 token 就越值钱。
• →并行进行独立调查。总耗时取决于最慢的一项，而不是各项耗时之和；这省的是时间，不是 token，每项仍需自己的启动成本。
• →较小模型就能做好搜索、概括和检查的工作。

什么时候会浪费 token

• →小而明确的改动。已知目标文件时，启动成本会超过它替代的探索量，新子代理还需先收集上下文。
• →依赖主对话已有知识的工作。新子代理会重读 Claude 已读过的文件。频繁往返，或规划、实现、测试等共享上下文的阶段，更适合留在主对话。
• →任务重叠的并行代理。三个子代理若都需要同一核心模块，就各自读一遍，结果也分别进入主上下文。
• →订阅中同时运行许多代理。每个子代理都消耗与主对话相同的套餐用量上限；Claude Code 文档明确指出，同时运行多个会使 token 用量倍增。

委派还可以嵌套。以 2026 年 9 月为准，子代理可以再启动子代理，默认最多比主对话深三层，同时最多运行 20 个。把 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 设为 1 可关闭嵌套；CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 可调整并发上限。

另有两个工具覆盖部分相同需求。/btw 用主对话已有内容回答插问，不使用工具，也不把回答加入历史。/subtask 会启动一个继承对话并读取其缓存的分支子代理。文档称，对需要相同上下文的任务，它比全新子代理便宜，但分支一开始就和主对话一样大。

让子代理使用更便宜的模型

自定义子代理是 Markdown 文件：单项目放在 .claude/agents/，所有项目共用则放在 ~/.claude/agents/。系统提示前有 YAML frontmatter。model 字段可用 haiku、sonnet、opus、fable、claude-opus-5-5 等完整模型 ID，或 inherit。执行搜索、概括或检查的子代理可设置 model: haiku。

Claude Code 按以下顺序选择子代理模型：Claude 在单次调用中指定的模型、定义中的 model 字段、CLAUDE_CODE_SUBAGENT_MODEL 环境变量，最后才是主对话模型。最后一项有成本影响：你用 /model 切到 Opus，所有继承主模型的子代理也会跟着切换。

内置 Explore 子代理不再默认使用 Haiku。从 Claude Code v2.1.198 起，它继承会话模型，在 Claude API 上最高为 Opus。若想降低探索成本，可新建名为 Explore、设置 model: haiku 的自定义子代理，覆盖内置版本；但自定义版本默认会加载 CLAUDE.md，除非加上 omitClaudeMd: true。单独设置 CLAUDE_CODE_SUBAGENT_MODEL 不会改变 Explore 或 Plan；v2.1.257 起再加 CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 才会应用到它们。

以 2026 年 9 月 Anthropic 的 API 标价为准，Claude Haiku 4.5 每百万输入 token 为 1 美元、输出为 5 美元；Sonnet 5 分别为 2 和 10 美元；Opus 5.5 分别为 4 和 20 美元。对订阅用户，Anthropic 帮助中心的说法是：Opus 每轮成本是 Sonnet 的数倍，Sonnet 又高于 Haiku。

但要考虑一个限制：子代理的上下文窗口由自身模型决定。Haiku 4.5 是 200K token，Sonnet 5 和 Opus 5.5 是 1M。另有两个字段可限制花费：maxTurns 限制子代理可进行的代理轮数；在 Sonnet 或 Opus 上，effort: low 可降低它的推理强度，而不改变主会话。

$/tasks

查看子代理实际消耗

要看合计，用能汇总所有请求的工具：

• →Pro、Max、Team 和 Enterprise 套餐中的 /usage，会把近期总用量分配到子代理、技能、插件和 MCP 服务器。d 和 w 可切换过去 24 小时与七天。它读取本地会话历史，不包含其他机器或 claude.ai；其中 Prompt cache (main) 只覆盖主对话。
• →脚本中，claude -p --output-format json 返回 total_cost_usd 和逐模型明细。Agent SDK 文档明确说，usage 字段只统计顶层循环；total_cost_usd 和 modelUsage 包含子代理请求。
• →团队可用 OpenTelemetry 的 token 和成本计数器。每个请求带有 query_source 标签，子代理请求的值是 subagent，还带 agent.name。
• →每个子代理的对话记录会保存在 ~/.claude/projects/{project}/{sessionId}/subagents/，默认保留 30 天，可查看它读过和运行过什么。

$/usage

委派之前先做什么

最便宜的探索，无论是否委派，都是根本不必进行的探索。知道文件时直接点名，问题也尽量收窄。每个自定义子代理的 description 保持简短：描述会占主对话的上下文，而子代理的系统提示只在它运行时加载。

如果想给探索设上限，capsul 可驱动你已经登录的 Claude Code，发送任务所需内容，在达到你设定的预算时停止，并告知哪些内容未被纳入。

$capsul ask 'why does the session expire early' --budget 3000