配置指南 · 截至 2026-11-22

Claude Code 子代理与默认模型环境变量配置:5 个核心键控住主从路由与账单

截至 2026-11-22,Claude Code 通过 5 个核心环境变量控制主会话与子代理模型路由:ANTHROPIC_MODEL 指定主会话模型,ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 分别钉死 opus、sonnet、haiku 三档别名映射,CLAUDE_CODE_SUBAGENT_MODEL 则把所有子代理统一锁定到指定模型。接入自定义 ANTHROPIC_BASE_URL 网关时,把这 5 个键写进 ~/.claude/settings.json 的 env 块,即可避免别名漂移报错,并防止并行子代理默认跑在高价旗舰上消耗额度。

更新于 2026-11-22

把这个工具接到 QCode 端点:一把 key 调 Claude、GPT 与国产模型。

#CLAUDE_CODE_SUBAGENT_MODEL#ANTHROPIC_DEFAULT_*_MODEL#v2.1.330#settings.json env

四个先要记住的关键事实

5 个核心变量

主模型、三档别名与全局子代理覆盖

ANTHROPIC_MODEL 管主会话,ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL 与 ANTHROPIC_DEFAULT_HAIKU_MODEL 决定别名解析结果,CLAUDE_CODE_SUBAGENT_MODEL 可把 Explore、Plan 等全部子代理锁定到同一模型;另可用 ANTHROPIC_DEFAULT_FABLE_MODEL 钉死 fable 别名。

$0.10 / $4

Anthropic 官方 API 输入标价差距(每百万 token)

Anthropic 官方价目页(2026-11-22 核对):Claude Haiku 5.5 在 100,000 token 以内输入仅 $0.10、输出 $0.50;Sonnet 5.5 为 $2 与 $10;Opus 5.5 为 $4 与 $20;Fable 5.2 为 $8 与 $40。主会话留旗舰、探索类子代理切轻量档,单次任务成本结构差异显著。

v2.1.330

2026-11-20 发布,修复多项子代理与模型切换问题

Claude Code v2.1.330 修复了某子代理结束后误关其他子代理仍在使用的 MCP 服务器、后台子代理停止后未保持停止状态、/context 后改模型未更新系统提示词,以及 SessionStart hook 写入的环境变量在 claude -p --continue 中丢失等问题。

~/.claude/settings.json

env 块全局生效且优先于 shell 导出

当同一变量同时出现在 shell 与 settings.json 的 env 块时,大多数会话以 settings.json 为准,且它对后台代理同样生效;切勿把 API 密钥写进会提交进仓库的项目级 .claude/settings.json,单项目覆盖请用 .claude/settings.local.json。

5 个环境变量的分工、优先级与别名解析机制

Claude Code 的模型选型按五层优先级生效:会话内 /model 最高,其次是启动参数 claude --model、环境变量 ANTHROPIC_MODEL、配置文件里的 model 字段,最后是新会话默认变量 ANTHROPIC_DEFAULT_MODEL(需 v2.1.236 及以上)。当你输入 opus、sonnet、haiku、fable 或 opusplan 别名,或自定义子代理 YAML frontmatter 写了 model: sonnet、model: haiku 时,Claude Code 会把别名解析到具体模型 ID:在 Anthropic API 上,opus、sonnet、haiku 分别解析为 Opus 5.5(需 v2.1.280+)、Sonnet 5.5(需 v2.1.284+)与 Haiku 5.5(需 v2.1.293+),fable 解析为 Fable 5.2(需 v2.1.321+);但在 Amazon Bedrock、Microsoft Foundry 或第三方 LLM 网关上,默认映射可能落在旧版或网关未配置的 ID 上,因此需要用 ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 与 ANTHROPIC_DEFAULT_FABLE_MODEL 显式钉死完整 ID。

子代理层面,内置 Explore 默认沿用父会话模型(父会话走 Fable 且经订阅、Console 或 ANTHROPIC_BASE_URL 网关连接时,Explore 会落到 opus 别名对应的 Opus 模型),内置 Plan 同样继承父会话模型,statusline-setup 用 Sonnet,claude-code-guide 与 web-fetch 用 Haiku;设置 CLAUDE_CODE_SUBAGENT_MODEL 后,则会把包括 Explore 与 Plan 在内的所有子代理统一锁定到该模型。

此外,旧变量 ANTHROPIC_SMALL_FAST_MODEL 已标记弃用,后台轻量任务改由 ANTHROPIC_DEFAULT_HAIKU_MODEL 承接。

2026-11-20 动态:v2.1.330 子代理与模型切换修复,及社区限额痛点

截至 2026-11-22,最新正式版 Claude Code v2.1.330(2026-11-20 发布)包含多条与多子代理和模型配置直接相关的修复

  1. 1修复单个子代理结束后误关闭其他子代理或主会话仍在使用的 MCP 服务器
  2. 2修复已停止的后台子代理有时未能保持停止状态,以及在应用或 SDK 会话中主线程仍持续等待刚结束的已停止后台代理
  3. 3修复在 /context 之后、首条消息之前切换模型时系统提示词仍残留旧模型指令的问题,以及多个 Claude Code 进程同时保存用户设置时改动丢失的问题
  4. 4修复 SessionStart hook 写入的环境变量在使用 claude -p --continue 时丢失,以及 Amazon Bedrock (Mantle) 终端会话未选模型时忽略已钉死 Opus 并在宣告回退后仍调用不可用默认模型的问题。社区侧,2026-11-19 至 2026-11-20 论坛与 X 上有多名开发者反映,在 Max 等订阅档下用重型主代理配并行子代理时,周限额在 1 到 2 天内即耗尽,因此越来越多团队改用「Opus 5.5 负责规划监督、Sonnet 或更低价模型负责执行与搜索」的分层路由。

三个关键节点:限额痛点发酵、v2.1.330 修复落地与当前推荐配置

2026-11-19

2026-11-19 至 2026-11-20,社区多名重度用户反映在订阅套餐下开启多代理并行工作流后,周限额在 1 到 2 天内耗尽,单次会话消耗约 800k token 即触达会话上限;讨论焦点迅速转向「主会话编排 + 低价子代理执行」的模型分层。

2026-11-20

Claude Code v2.1.330 于 2026-11-20 发布,集中修复了子代理共用 MCP 服务器被提前关闭、后台子代理停止状态异常、并发保存用户设置丢改动,以及 SessionStart hook 环境变量在 claude -p --continue 续跑时丢失等问题,使多子代理环境配置更加稳定。

2026-11-22

截至 2026-11-22,Anthropic API 上 opus、sonnet、haiku、fable 分别对应 Opus 5.5、Sonnet 5.5、Haiku 5.5 与 Fable 5.2;配合自定义网关时,在 ~/.claude/settings.json 中固定三档默认别名与 CLAUDE_CODE_SUBAGENT_MODEL 是防止误路由与超支的标准做法。

已核实官方文档事实 vs 常见配置误区与社区说法

已核实(Claude Code 官方文档、v2.1.330 发布说明与厂商官方价目页)

  1. 1网关与选型解耦:官方文档明确写到 ANTHROPIC_BASE_URL 只改变请求发往的地址,不决定由哪个模型响应;且自 v2.1.196 起,指向 api.anthropic.com 之外的主机时 Remote Control 自动关闭。
  2. 2并发与描述上限:CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS(需 v2.1.217+)控制单会话最大并发子代理数,默认值为 20;旧变量 CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION(原默认 200)已于 v2.1.224 移除并失效;所有自定义子代理的 description 合并超过 15,000 token 时会在启动时弹出警告。
  3. 3自定义模型参数:经网关路由 Claude Code 无法识别的模型 ID 时,CLAUDE_CODE_MAX_OUTPUT_TOKENS 默认 32000、上限 128000;可用 CLAUDE_CODE_MAX_CONTEXT_TOKENS 修正上下文窗口,用 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 从网关 /v1/models 填充 /model 列表,用 CLAUDE_CODE_PROMPT_CACHE_TTL(需 v2.1.242+)设置 5m 或 1h 缓存时长。
  4. 4官方 API 标价(每百万 token 输入 / 输出):Anthropic 官方标价为 Claude Fable 5.2 $8 / $40、Opus 5.5 $4 / $20、Sonnet 5.5 $2 / $10、Haiku 5.5(提示词不超过 100,000 token)$0.10 / $0.50(超过 100,000 token 为 $0.50 / $2.50);Z.AI 官方标价为 GLM-5.3 输入 $1.4、缓存输入 $0.26、输出 $4.4,GLM-5.3-Flash 输入 $0.15、缓存输入 $0.03、输出 $0.50。

常见配置误区与非官方社区说法

  1. 1「设了 ANTHROPIC_BASE_URL 就会自动选网关推荐模型」——误区。官方文档说明该变量只改转发目标,不改模型路由;若不钉死 ANTHROPIC_DEFAULT_*_MODEL,客户端发出的默认或旧快照 ID 可能被网关拒绝。
  2. 2「终端里 export 出来的环境变量一定压过 settings.json」——误区。官方文档明确说明,当同一变量同时存在于 shell 与 settings.json 的 env 块时,大多数会话由 settings.json 覆盖进程环境。
  3. 3「内置 Explore 子代理默认就跑 Haiku,不用管成本」——误区。官方文档写明 Explore 默认沿用父会话模型(父会话为 Fable 且经订阅、Console 或 ANTHROPIC_BASE_URL 网关连接时落到 opus 别名),想用 Haiku 须设 CLAUDE_CODE_SUBAGENT_MODEL 或在 ~/.claude/agents/ 建同名 Explore 文件指定 model: haiku。
  4. 4「订阅撞到周限额后,在 /model 里切到 Sonnet 就能继续用」——社区开发者总结指出,5 小时窗与周限额在各模型间共享,只有弹出按模型家族限流提示(例如 "You've hit your Opus limit")时切换家族才有效。
  5. 5「后台轻量模型仍应配置 ANTHROPIC_SMALL_FAST_MODEL」——过时写法,官方文档已将其标为弃用,应改用 ANTHROPIC_DEFAULT_HAIKU_MODEL。

两种子代理降本架构对比:全局一刀切 vs 按角色细分

A:CLAUDE_CODE_SUBAGENT_MODEL 全局锁死

在 settings.json 的 env 块里设 CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-5-5(或 claude-haiku-5-5),强制 Explore、Plan 及所有自定义子代理统统走这一档模型。优点是一行生效、彻底杜绝任何后台代理意外拉起 Opus 5.5 或 Fable 5.2;缺点是无法为复杂审查子代理单独保留更高档位。

B:钉死三档别名 + ~/.claude/agents/ 按文件分流

不设全局覆盖,先用 ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 固定三档 ID,再在 ~/.claude/agents/ 下用 YAML frontmatter 给只读 Explore 覆盖文件写 model: haiku、给代码审查代理写 model: sonnet,主线程按需用 opus 或 opusplan(规划用 Opus、执行切 Sonnet)。修改代理文件后数秒内热生效,无需重启。

三步照做:在 ~/.claude/settings.json 配好网关与主从模型路由

  1. 1打开用户级配置文件 ~/.claude/settings.json(Windows 路径为 %USERPROFILE%\.claude\settings.json;单项目覆盖请放进已加入 gitignore 的 .claude/settings.local.json,切勿写入可提交的项目级 .claude/settings.json),在 "env" 对象中填入网关地址与凭据:"ANTHROPIC_BASE_URL": "https://api.qcode.cc/api"(中国大陆可用 https://asia.qcode.cc/api,北美与欧洲可用 https://us.qcode.cc/api),以及 "ANTHROPIC_AUTH_TOKEN": "你的 cr_ 密钥"。
  2. 2在同一个 "env" 对象中继续写入主模型、三档别名与子代理锁定变量:"ANTHROPIC_MODEL": "claude-opus-5-5"、"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5"、"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5"、"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5"、"ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5-2" 与 "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-5-5"(以搜索探索为主时可改为 claude-haiku-5-5;若希望 /model 列表自动拉取网关 /v1/models,可加设 "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1")。
  3. 3先用终端发一条连通性验证请求:curl -sS -X POST "$ANTHROPIC_BASE_URL/v1/messages" -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d '{"model": "claude-sonnet-5-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}',返回含 "id":"msg_ 与 "content" 即代表网关与密钥生效(报 401 时检查凭据变量或先跑 /logout 清除旧登录);随后启动 claude 运行 /status 核对 Anthropic base URL 与 Auth token,会话内随时用 /model claude-fable-5-2、/model glm-5.3 或 /model kimi-k3.1-pro 按任务难度切换(在选择器按 s 仅对当前会话生效)。

用一把 QCode API Key 落地多模型主从工作流

QCode.cc 是独立的 API 接入服务,与 Anthropic、OpenAI、Z.AI 等厂商无隶属关系。在 Claude Code 中把 ANTHROPIC_BASE_URL 指向 https://api.qcode.cc/api(中国大陆可用 https://asia.qcode.cc/api,北美与欧洲可用 https://us.qcode.cc/api)后,同一把 cr_ 密钥即可同时覆盖多档在售模型:主会话跑 claude-opus-5-5 或 claude-fable-5-2 做架构与复杂调试,子代理交给 claude-sonnet-5-5 或 claude-haiku-5-5,会话中也可直接用 /model 切到 glm-5.3、glm-5.3-flash、kimi-k3.1-pro 或 deepseek-v4.1-flash,无需维护多家账号,也不受订阅 5 小时滚动窗与周限额硬锁;同一把密钥还可分别接入 Codex CLI(https://api.qcode.cc/openai)与 OpenAI 兼容客户端(https://api.qcode.cc/openai/v1)调用 gpt-6.2-sol、qwen3.8-max 等型号。

按 token 计费,各模型实时单价以 /models 为准;付款支持 Visa / Mastercard、Apple Pay、Google Pay、支付宝、微信支付、俄罗斯本地银行卡与 СБП、独联体银行卡及多网络 USDT(18 条网络,0% 平台手续费,通常数分钟到账,最长 12 小时)。不想包月?按量包 ¥26 起买一笔额度,7 天内用完为止;已有个人套餐的用户额度不够时买加油包。

常见问题

ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_*_MODEL 与 CLAUDE_CODE_SUBAGENT_MODEL 有什么区别?

三类变量分别管主会话、别名映射与子代理。ANTHROPIC_MODEL 指定主会话本身运行的模型(优先级高于配置文件里的 model 字段与 ANTHROPIC_DEFAULT_MODEL,低于 --model 与 /model);ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 与 ANTHROPIC_DEFAULT_FABLE_MODEL 决定 opus、sonnet、haiku、fable 别名解析到哪个完整模型 ID(其中 ANTHROPIC_DEFAULT_HAIKU_MODEL 同时承接后台功能);CLAUDE_CODE_SUBAGENT_MODEL 则把 Explore、Plan 及自定义子代理全部锁定到同一个模型。

为什么在终端里 export 了模型环境变量,启动 Claude Code 却没生效?

最常见原因是 ~/.claude/settings.json(或受管配置)的 env 块覆盖了终端导出的值。官方文档写明,同一变量同时出现在 shell 与设置文件 env 块时,大多数会话会由设置文件写入进程环境;同时,会话内 /model(按回车会写入用户默认配置)和启动参数 --model 都会覆盖 ANTHROPIC_MODEL。建议把变量统一维护在 ~/.claude/settings.json 的 env 块中,并用 /status 与 /model 确认实际生效值。

怎么防止内置 Explore 和 Plan 子代理默认消耗 Opus 或 Fable 额度?

有两种直接做法:一是在 ~/.claude/settings.json 的 env 块中设置 CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-5-5 或 claude-haiku-5-5,把包括 Explore 与 Plan 在内的所有子代理统一降档;二是在 ~/.claude/agents/(用户级)或 .claude/agents/(项目级)创建名为 Explore 的 Markdown 文件,在 YAML frontmatter 中指定 model: haiku 覆盖内置 Explore。此外,可通过 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS(默认 20)限制单会话并发子代理数量。

接入自定义网关后报 401 或提示未知模型怎么排查?

报 401 通常是鉴权头用反或残留旧登录,报未知模型通常是别名解析到了网关未映射的 ID。ANTHROPIC_AUTH_TOKEN 以 Authorization: Bearer 发送并立即优先于已保存的 claude.ai 登录,ANTHROPIC_API_KEY 以 x-api-key 发送且交互模式首次会要求确认;遇 401 请先跑 /status 核对当前生效凭据、必要时执行 /logout 清理旧登录,再用 curl 请求 "$ANTHROPIC_BASE_URL/v1/messages" 验证;遇未知模型则把 ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 显式钉死为网关在售 ID(如 claude-sonnet-5-5)。

切到 QCode 需要绑月费吗?按量包和个人套餐的计费与续期怎么算?

不需要绑月费,按 token 计费,各模型实时单价以 /models 为准。按量包有效期 7 天、并发上限 5,额度耗尽返回 HTTP 402、到期返回 HTTP 401,到期后再买一个按量包可在同一把 API Key 上恢复并累加(按量包购买后不支持退款);个人套餐按月计期,有效期内额度不足可买加油包,个人套餐 Key 到期后不能原 Key 续期,需重新开通换新密钥。

QCode 支持哪些付款方式?起充门槛和到账时间是多少?

支持国际信用卡(Visa / Mastercard)、Apple Pay、Google Pay、支付宝、微信支付、俄罗斯本地银行卡与 СБП、独联体银行卡以及多网络加密货币(USDT 支持 18 条网络,0% 平台手续费,人工链上核验通常数分钟到账,最长 12 小时)。统一充值页 qcode.cc/recharge 区分美元与人民币两种独立余额:美元起充 $5(单笔最高 $2,000),人民币起充 ¥30。

参考来源

Claude Code 官方文档:Model configuration(code.claude.com/docs/en/model-config)、Environment variables(code.claude.com/docs/en/env-vars)、Sub-agents(code.claude.com/docs/en/sub-agents)、LLM gateway connect(code.claude.com/docs/en/llm-gateway-connect);Claude Code release v2.1.330(github.com/anthropics/claude-code/releases/tag/v2.1.330,2026-11-20);Anthropic API Pricing(platform.claude.com/docs/en/about-claude/pricing);Z.AI Pricing(docs.z.ai/guides/overview/pricing);社区讨论参考(Reddit 与 X,2026-11-19 至 2026-11-20,仅作痛点背景参考、不作官方口径)。以上均核对于 2026-11-22。

把主从模型路由写进 settings.json,一把 Key 管住全栈编码账单

无需绑定固定月费,注册 QCode 生成 cr_ API Key,30 秒填入 ~/.claude/settings.json 即可在同一工作流混用 Opus 5.5、Sonnet 5.5、Haiku 5.5 与 GLM-5.3,各模型实时单价见 /models。

相关阅读

加密货币充值指南

9 种币、56 条网络,0 平台手续费购买 AI 编程 API 额度。

Claude Code 模型配置、环境变量、子代理与 LLM 网关文档、v2.1.330 发布说明以及 Anthropic 与 Z.AI 官方价目页均核对于 2026-11-22,以 code.claude.com、platform.claude.com、github.com/anthropics/claude-code 与 docs.z.ai 官方页面为准。QCode.cc 是独立的 API 接入服务,与 Anthropic、OpenAI、Z.AI 等厂商无隶属关系、未获其背书。QCode 在售型号与实时单价以 qcode.cc/models 为准。

不确定从哪开始?

先试一周

小包 ¥26($30 额度,7 天)

每天都用

体验版 ¥63/月,每天 $5 额度;每 $1 额度只要 ¥0.42,中包约 ¥0.79