Claude Code 子智能体换用其他模型运行的方法——交给 Sonnet、Haiku 的设置与实测

Claude Code 的主对话想用 Opus 5，effort 也想保持在高档。可是连翻译、批量检查文件这类工作也交给同一个模型，未免有些浪费——于是就有了这个问题：能不能只让子智能体用 Sonnet 或 Haiku 来跑？

先说结论：可以。子智能体的模型与主对话分开决定，通过调用时的指定、定义文件里的 model 或环境变量都能修改。effort 也可以为每个子智能体单独指定。

本文先整理截至2026年9月15日官方文档中写明的规格，然后给出我实际用其他模型启动子智能体、再对照对话日志确认的结果。我把同一段翻译交给 Opus 5、Sonnet 5、Haiku 4.5 各做 2 次，比较了耗时、费用和译文质量。

1. 能做什么：让子智能体使用与主对话不同的模型和 effort

子智能体是 Claude Code 为了把一部分工作交出去而启动的、拥有独立上下文的执行者。它不与主对话共享对话历史，完成后只把结果交回主对话（它与 Agent Teams 的区别，见Claude Code：Subagents 与 Agent Teams 之别）。

对于子智能体，官方文档写明可以单独指定的有以下两项。

也就是说，“主对话用 Opus 5、effort 为 high，翻译角色用 Sonnet 5、effort 为 medium”这样的组合，在官方规格范围内就能直接实现。effort 本身的含义请参阅Claude Code effort 设置完全指南：5 等级 + Ultracode。

来源：Claude Code 官方文档《Create custom subagents》（Supported frontmatter fields）、同《Model configuration》（effort 的优先顺序）

2. 模型的决定顺序

如开头的图所示，子智能体的模型按“调用时的指定”→“定义文件中的 model”→“环境变量 CLAUDE_CODE_SUBAGENT_MODEL”→“主对话的模型”的顺序，取第一个符合的。需要注意的有以下 3 点。

第一，顺序因版本而异。v2.1.251 之前，环境变量排在最上面，连调用时的指定和定义文件中的 model（包括 inherit）都会被它覆盖。如果遇到“定义里写了 model: sonnet 却不生效”，请先检查版本和环境变量。

第二，想把所有子智能体统一成一个模型，需要另外的设置。仅靠环境变量，在定义文件中写了 model 的子智能体不会听从。要强制全部统一，需在 CLAUDE_CODE_SUBAGENT_MODEL 之外，再把 CLAUDE_CODE_SUBAGENT_MODEL_FORCE 设为 1（v2.1.257 及以后）。

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

强制之后，包括内置的 Explore 和 Plan 在内，定义文件中的 model 都会被忽略，Claude 在调用时也无法再指定模型。例外有 2 个：完整继承整段对话的 fork，以及以子智能体方式运行 model: inherit 的技能，这两种情况仍使用主对话的模型。

第三，sonnet 和 opus 指向哪个模型，取决于接入平台。同样写 sonnet，得到的模型会有如下差异。

来源：Claude Code 官方文档《Model configuration》（截至2026年9月15日的表格）。想固定到特定版本时，请写完整模型 ID 而不是别名

如果组织的托管设置限制了可用模型（availableModels），子智能体的 model 和环境变量同样受此限制。

3. 设置方法（5 种）

① 写在定义文件里（适合始终用同一模型的角色）

最好用的方法，是为每个角色建一个定义文件。放在项目的 .claude/agents/ 下可以通过 git 共享；如果要在自己的所有项目中使用，就放在 ~/.claude/agents/ 下。

---
name: translator
description: 将日文文章翻译成英文。在被要求翻译时使用
model: sonnet
effort: medium
tools: Read, Write, Grep
---
你是一名技术文章译者。不要改动 HTML 的标签和属性，
只把可见的文字译成自然的英文。

同名定义有多个时，优先顺序为：组织的托管设置、启动时的 --agents、项目、用户、插件。自 v2.1.198 起，/agents 命令不再打开创建界面，因此请让 Claude 帮你创建，或直接编写文件。

② 调用时指定（只想临时换一下）

即使不建定义，Claude 在启动子智能体时也能附带模型。在对话中说“这个检查交给 Haiku 的子智能体”，Claude 就会在这次调用中附带模型来启动。这个指定优先于定义文件。是否真的附带上了，请用第 5 章的方法确认。

③ 用环境变量设定默认值（想把没有指定的子智能体一并改掉）

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "sonnet"
  }
}

写在 settings.json 的 env 中，就会作用于模型没有被其他方式决定的子智能体。根据官方文档，智能体团队的成员和工作流中的智能体也在适用范围内。不过，仅靠这一项，内置的 Explore 和 Plan 的模型不会改变（第 4 章）。

④ 启动时用 --agents 传入（仅限当前会话）

claude --agents '{
  "translator": {
    "description": "Translates Japanese articles into English.",
    "prompt": "You are a technical translator. Keep all HTML tags.",
    "model": "sonnet",
    "effort": "medium"
  }
}'

不会保存到文件，只在该会话期间可用。

⑤ 在 Claude Agent SDK 中定义

from claude_agent_sdk import ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    agents={
        "translator": AgentDefinition(
            description="Translates Japanese articles into English.",
            prompt="You are a technical translator. Keep all HTML tags.",
            tools=["Read", "Write"],
            model="sonnet",
            effort="medium",
        ),
    }
)

在 SDK 的 AgentDefinition 中，model 同样可以写别名、inherit 或完整模型 ID。不写的话，按上面的顺序决定。另外，官方文档指出Opus 5 比以往的模型更倾向于把工作分派给子智能体，并介绍了限制同时运行数量（默认 20）和花费金额上限的设置。

来源：Claude Code 官方文档《Create custom subagents》（存放位置与优先顺序、--agents、/agents 的变更、环境变量）、同《Model configuration》（CLAUDE_CODE_SUBAGENT_MODEL 的适用范围）、同《Subagents in the SDK》（AgentDefinition、上限设置）

4. 内置子智能体用的是什么模型

即使自己不定义，Claude Code 也自带了几个子智能体。它们各自的模型如下。

来源：Claude Code 官方文档《Create custom subagents》（Built-in subagents，截至2026年9月15日）

自 v2.1.198 起，Explore 不再固定使用 Haiku。它沿用主对话的模型，在 Claude API 上以 Opus 为上限。主对话即使是 Fable 这样更高阶的模型，Explore 也用 Opus 运行；主对话是 Sonnet 或 Haiku 时，Explore 就用那个模型。如果想改回 Haiku，官方文档给出的方法是新建一个名为 Explore 的定义文件并写上 model: haiku（因为自己的定义优先于同名的内置子智能体）。

如果想用环境变量改变 Explore 和 Plan 的模型，还需要设置第 2 章介绍的 CLAUDE_CODE_SUBAGENT_MODEL_FORCE。

5. 实测①：真的用指定的模型运行了吗

我在自己的环境（主对话为 Opus 5，effort 为 high）中确认了是否与规格一致。我让内置的 general-purpose 执行同一个小任务——“读 README 并用 3 行总结”，分把模型指定为 sonnet、指定为 haiku、以及不指定这 3 种情况。

确认方法有 2 种。运行过程中，/tasks 的列表里会显示子智能体的模型（官方文档有记载）。结束之后，可以查看本地对话日志 subagents/ 文件夹中的 agent-*.jsonl，看每条回复的 message.model。日志的存放位置和读法，在Claude Code 按会话查看使用量的方法中有详细介绍。

来源：我的实测（2026年9月15日，Windows 桌面应用。每个子智能体的所有回复都记录为同一个模型）

指定了的都按指定的模型运行，没有指定的则沿用了主对话的模型。同一文件夹中的 agent-*.meta.json 只在指定了模型时，才会留下 "model": "sonnet" 这样的指定值。

6. 实测②：光是启动就要读入数万 token

从同一批日志中，还发现了另一件事。子智能体在开始干活之前，仅第一条回复就要读入数万 token。因为它自己的系统提示词、工具定义、CLAUDE.md 等会最先放进去。

来源：我的实测（2026年9月15日。各子智能体第一条回复的 token 数。写入全部是 5 分钟缓存）

从这些数字可以看出 3 点。

第一，同一模型的子智能体之间，开头的共同部分会从缓存读取。第 2 次启动时，Sonnet 5 约有 4.5 万 token 变成了缓存读取（单价为输入的 0.1 倍）。官方文档也写道，同一模型、开头相同的请求会共享缓存。反过来说，缓存按模型分开，子智能体也不会读取主对话的缓存（因为开头的内容不同）。

第二，即使是订阅，子智能体的缓存也是 5 分钟过期。根据官方文档，在套餐范围内使用时，主对话的缓存是 1 小时，而子智能体是 5 分钟。间隔 5 分钟以上再启动下一个子智能体，就又要从写入开始。如果想改成 1 小时，可以把设置项 subagentPromptCacheTtl 或环境变量 CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL 设为 1h（v2.1.242 及以后）。如果想按子智能体分别决定，就在定义文件的 experimental 中写 cacheTtl（v2.1.248 及以后。订阅在使用额外用量（usage credits）期间，这里的 1h 会被忽略）。1 小时缓存的写入单价是输入单价的 2 倍（5 分钟缓存为 1.25 倍）。

第三，同样的文本，Haiku 4.5 的 token 数显得更少。根据官方定价页面，Claude 4.7 及以后的模型使用新的分词器，同样的文本会多计约 30% 的 token。Haiku 4.5 属于 4.7 之前的一代，不在使用新分词器的模型之列。直接比较表中的数字，Haiku 会显得比实际更轻。

如果把零碎的工作拆给很多个子智能体，这笔“光启动就要花的量”会每个都算一次。交给便宜的模型，不仅干活的部分，这部分也会变便宜。

来源：Claude Code 官方文档《How Claude Code uses prompt caching》（按模型区分的缓存、子智能体与缓存、缓存有效期）、Claude Platform Docs《Pricing》（分词器、缓存倍率）、Claude Code 官方文档《Create custom subagents》（omitClaudeMd）

7. 实测③：同一段翻译交给 3 个模型各做 2 次

开头提出的“只把翻译降一档”，我实际试了一下。从本站一篇文章的日文版中选了一节（HTML 共 6,265 字符，含表格、数值卡片和代码片段），用同样的指令让每个模型在不改变标签结构的前提下译成英文，各做 2 次，共 6 次。effort 方面，Opus 5 和 Sonnet 5 是沿用主对话的 high（Haiku 4.5 不支持 effort）。

来源：我的实测（2026年9月15日。费用是用对话日志中的 token 数乘以官方单价得出的标价换算。不含输出部分，见下方说明）

费用一栏没有计入输出部分，是因为日志里的输出 token 数不可信。有一条把约 8,800 字符的译文写入文件的回复，记录的输出只有 18 个 token。输出单价为每百万 token Opus 5 $25、Sonnet 5 $10、Haiku 4.5 $5，译文都是英文，长度约 8,500~8,900 字符。

译文质量由我逐句对照日文原文进行了确认。

• 6 次都没有发现意思理解错误。数值、表格和内部链接也都正确保留。不过这段文字数值和列表较多，属于比较好译的一类
• 差异出现在可读性和用词的统一上。Haiku 4.5 第 1 次的第一人称混用了 “my” 和 “the author's”，第 2 次出现了 “G from 9th rises to 6th” 这样生硬的语序。Sonnet 5 的英文很自然，但 “subagent” 第 1 次写成 “Sub-agent”，第 2 次写成 “Subagent”，每次写法不一。Opus 5 两次用词都保持一致
• 耗时最长的，恰恰是最便宜的 Haiku 4.5。Sonnet 5 两次的耗时相差近一倍。次数很少，速度排名仅供参考

8. 对费用和用量的影响

把子智能体的模型降一档能省多少，要看你用的是 API 按量付费，还是 Pro、Max 等订阅，思路不一样。

API 按量付费：单价之比直接生效

来源：Claude Platform Docs《Pricing》（每百万 token，截至2026年9月15日。Sonnet 5 的推出价格已直接转为正式价格）

Sonnet 5 的单价是 Opus 5 的五分之二，Haiku 4.5 是五分之一。第 7 章的实测中，输入与缓存部分的费用，Sonnet 5 约为 Opus 5 的一半，Haiku 4.5 约为五分之一。Haiku 4.5 接近单价之比，而 Sonnet 5 高于五分之二，原因是各模型的回复次数和每次读入的量不同（Sonnet 5 两次分别为 4 次和 6 次回复，Opus 5 两次都是 4 次；Haiku 4.5 还使用不同的分词器）。

订阅：有些上限换模型也恢复不了

在 Pro、Max 中，会话上限和每周上限是所有模型共用的。用完之后，即使用 /model 换模型，也无法继续使用。除此之外，还有“Opus 上限”“Sonnet 上限”这类按模型系列划分的上限，只有达到这类上限时，才能通过换成该系列以外的模型继续使用。

🟡 把子智能体换成 Sonnet 或 Haiku 后，套餐上限能多撑多久，官方并未公布。API 的单价之比可以作为参考，但官方没有说上限的消耗会按这个比例减少。哪个子智能体用得多，可以在 /usage 的套餐明细（按技能、子智能体、插件、MCP 服务器划分的占比）中确认。

来源：Claude Code 官方文档《Error reference》（You've hit your session limit：所有模型共用的上限与按模型系列划分的上限）、同《Manage costs effectively》（/usage 的套餐明细）

9. 哪些工作可以换成低一档的模型

官方文档给出的参考是：多数编码工作 Sonnet 就能胜任，而且比 Opus 便宜；Opus 留给复杂的架构决策和多步推理；简单的子智能体工作，在定义文件中指定 model: haiku。对智能体团队的成员，官方也推荐使用 Sonnet。

在此基础上，结合第 7 章的实测和本站的实际运营，列出 3 条判断依据。

拿不准的时候，最稳妥的做法是把一项日常工作交给降档后的模型，与现在模型的结果放在一起比较。只需改定义文件中 model 这一行就能试，不合适也能马上改回来。如果想分开的不是子智能体的模型，而是主对话的模型——只在制定计划时用 Opus、实现时用 Sonnet——可以用 opusplan 来做到，详见Claude Code 的 opusplan 是什么？。

FAQ

Q1. 对话中途用 /model 更换主对话的模型，子智能体也会跟着变吗？
由调用时的指定、定义文件中的 model（inherit 除外）或环境变量决定模型的子智能体不会变。三者都没有的子智能体，以及在定义文件中设为 inherit 的子智能体，会跟随主对话的模型。另外，更换主对话的模型后，主对话的缓存需要重新建立。

Q2. 能不能模型不变，只降低 effort？
可以。在定义文件中写上 effort: medium 这样的设置，就只在该子智能体运行期间使用这个 effort。不过，如果设置了环境变量 CLAUDE_CODE_EFFORT_LEVEL，则以它为准。

Q3. 在 Amazon Bedrock 上写 model: sonnet，会是哪个模型？
按截至2026年9月15日的官方文档，是 Sonnet 4.5。在 Anthropic API 上则是 Sonnet 5，所以同一个定义文件，接入平台不同，结果也不同。想固定版本，请写完整模型 ID。

Q4. 把子智能体的缓存设为 1 小时更划算吗？
要看用法。如果间隔 5 分钟以上反复启动同一类子智能体，可以减少每次的写入。另一方面，1 小时缓存的写入单价是输入单价的 2 倍（5 分钟为 1.25 倍），如果只是短时间内集中运行，5 分钟缓存反而更便宜。设为 1 小时的设置方法及其条件，已在第 6 章中汇总。

Q5. 明明指定了模型，却感觉没生效。
请按以下顺序检查：①CLAUDE_CODE_SUBAGENT_MODEL_FORCE 是否已启用（启用后定义文件的指定会被忽略）；②是否在 v2.1.251 之前的版本中设置了环境变量；③组织的托管设置是否允许该模型。实际用哪个模型运行，运行中可以看 /tasks，结束后可以看对话日志中的 message.model。

来源

• Claude Code Docs — Create custom subagents（定义文件的字段、模型的决定顺序及各版本差异、CLAUDE_CODE_SUBAGENT_MODEL_FORCE、内置子智能体、存放位置与优先顺序、--agents、omitClaudeMd、用 /tasks 确认）
• Claude Code Docs — Model configuration（别名指向的模型、CLAUDE_CODE_SUBAGENT_MODEL 的适用范围、effort 的优先顺序、availableModels）
• Claude Code Docs — How Claude Code uses prompt caching（按模型区分的缓存、子智能体的缓存有效期、subagentPromptCacheTtl 以及通过环境变量和定义文件的指定）
• Claude Code Docs — Manage costs effectively（选择模型的参考、推荐智能体团队成员使用 Sonnet 的说明、/usage 的明细）
• Claude Code Docs — Error reference（所有模型共用的上限与按模型系列划分的上限）
• Claude Code Docs — Subagents in the SDK（AgentDefinition 的 model 与 effort、Opus 5 与上限设置）
• Claude Code Docs — Orchestrate teams of Claude Code sessions（智能体团队成员的模型如何决定）
• Claude Platform Docs — Pricing（各模型单价、缓存倍率、分词器）

相关文章

• Claude Code：Subagents 与 Agent Teams 之别——子智能体是什么
• Claude Code effort 设置完全指南：5 等级 + Ultracode——effort 的含义
• Claude Code 按会话查看使用量的方法——对话日志的读法
• Claude Code 的上下文到底被什么吃掉了——CLAUDE.md 每次都会被读取的机制
• Claude Code 的 opusplan 是什么？——只在 plan mode 期间让主对话使用 Opus
• 10个Claude Code省Token技巧与超额费用详解——其他可以削减的地方