主页
📅 2026-10-14 · 依据:Claude Code Changelog(v2.1.293 于 10-07,v2.1.295 于 10-08,v2.1.296 于 10-09)与 Subagents 文档 上一课(第 39 课)讲过 v2.1.292–295 的 plugin 直装、
onFailure: "block"等;本课只补它没覆盖的 v2.1.293 的 Haiku 5.5 和 v2.1.296 的新增项。
场景:账单涨了,而且一到高峰就全挂
你开了一个大任务,让 Claude 派出十几个 subagent 去并行读代码。半小时后你发现两件事:一是 /usage 里 subagent 的 token 占了大头,而它们干的活(grep、总结)根本不需要最强模型;二是遇到服务过载(529)时,重试等得越来越久,你守在屏幕前不知道它是在等还是卡死了。这一课就用 v2.1.293–296 新增的几个小开关解决这类“并行 + 长时间 + 省钱”的问题。
技巧 1:把便宜又快的 Haiku 5.5 派给“体力活” subagent
解决的问题:搜索、归类、写摘要这类 subagent 没必要用最强模型,但你又懒得每次手动指定。
v2.1.293 加入了 Claude Haiku 5.5(模型 ID claude-haiku-5-5),changelog 写明它现在是 Anthropic API 上默认的 Haiku,带 1M 上下文,价格 $0.10 / $0.50 每百万 token(输入/输出)。subagent 的 model 字段本来就支持 haiku 别名,所以最简单的用法是给“体力活” agent 写死 haiku:
---
name: code-scout
description: 只读侦察。按关键词在仓库里找相关文件并给出一段话摘要。需要定位代码时主动使用。
tools: Read, Glob, Grep
model: haiku
---
你是侦察兵。只读,不改任何文件。输出:相关文件路径 + 每个文件一句话作用。不要贴大段代码。
想让会话里所有 subagent 都压到便宜模型(排查成本时很有用),官方 subagent 文档给的写法是两个环境变量一起设(v2.1.257+),会覆盖各 agent 的 frontmatter model:
{
"env": {
"CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
"CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
}
}
注意:model 的解析顺序是——调用时传入的 model 参数 → agent 的 frontmatter → CLAUDE_CODE_SUBAGENT_MODEL → 主会话模型(来自官方 subagent 文档)。所以没加 FORCE 时,frontmatter 优先。
文档:Subagents
技巧 2:给 subagent 配 autoCompactWindow,让它比主会话更早压缩(v2.1.296)
解决的问题:长时间运行的 subagent 在上下文很满时变慢、变笨,但主会话的压缩阈值又不想动。
v2.1.296 changelog 原文:新增 autoCompactWindow,可写在子 agent 的 frontmatter 和 --agents 的定义里,“让子 agent 比主会话更早自动压缩”。写法示意:
---
name: long-reader
description: 通读大量文档并持续做笔记。
model: haiku
autoCompactWindow: <数值,按文档取值>
---
⚠️ 诚实提醒:我检索时 Subagents 文档的字段表还没有列出 autoCompactWindow,changelog 也没给取值单位和示例,所以上面的 <数值> 我不编。安全做法是用一个小任务对比开关前后的 /context 占用来实测;字段名写错时,官方文档说明“无法识别的字段会被静默忽略”(所以别以为写了就生效,要实测)。
同时顺手知道一件事(v2.1.295):subagent 的 skills 字段现在最多预载 32 个技能,别把整个技能库塞进去。
技巧 3:CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL:给“工作流”里的一堆 agent 统一用一个模型(v2.1.296)
解决的问题:动态工作流(dynamic workflows)会调度几十上百个 agent,每个都跟着主模型跑,账单瞬间爆表。
changelog:新增环境变量 CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL,让所有 workflow agent 跑在同一个模型上。和技巧 1 的区别:它只管“工作流脚本派出的 agent”,不动你平时手动调用的 subagent。写进项目的 .claude/settings.json:
{
"env": {
"CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL": "haiku"
}
}
(取值写法我沿用了文档里 subagent model 的别名习惯;changelog 没给示例,首次使用请先在小工作流上确认模型是否生效。)
验证:跑一个小规模工作流,事后用 /usage 看各 agent 的模型与 token 占比。
文档:What's new 周报(动态工作流见 Week 22)
技巧 4:过载重试别干等——CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS 与 MCP 描述上限
解决的问题:①高峰期 529 过载时,不知道该等多久;②自己写的内部 MCP server 工具描述被截断。
- v2.1.296:新增
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS,设置 529 过载错误最长重试等待(毫秒)。想让无人值守任务耐心点就调大,想快速失败就调小。 - v2.1.295:新增
CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS,限制“无人值守重试模式”在 429/529 上最长等多久(上一课已提过)。 - v2.1.296:MCP 工具描述和 server 指令的字符上限由 2,048 提到 4,096——如果你之前为了塞进限制把描述写得又短又糊,现在可以补回关键的使用约束。
# 夜间批处理:过载时最多等 5 分钟再放弃(毫秒)
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS=300000 claude -p "跑完整套迁移检查并输出报告" --output-format json
(数值 300000 是我举的例子,官方未给推荐值,按你的任务耐受度调。)
今日实操(15 分钟)
- 升级并确认版本 ≥ 2.1.296(
claude --version)。 - 在项目里建上面的
code-scoutagent,用一个“找出所有用到 X 的文件”的任务触发它。 - 验收标准:
/usage里能看到该 subagent 的 token 记在 Haiku 档;再对比同一任务用主模型跑的 token 差异,写下节省比例。做完后试着把autoCompactWindow加到一个长任务 agent 上,用/context判断它是否生效——不生效就说明字段取值需要查最新文档。