Claude Code Subagent & Default Model Env Vars: 5 Keys to Control Routing and Token Spend
As of November 22, 2026, Claude Code controls main-session and subagent model routing through 5 core environment variables: ANTHROPIC_MODEL sets the primary model, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL pin the opus, sonnet, and haiku aliases, and CLAUDE_CODE_SUBAGENT_MODEL forces every subagent onto one model. When routing through a custom ANTHROPIC_BASE_URL gateway, storing these 5 keys in the env block of ~/.claude/settings.json prevents alias drift errors and keeps parallel subagents off flagship pricing.
Updated 2026-11-22
Point this tool at the QCode endpoint — one key for Claude, GPT and Chinese models.
- Billed per token — live rates on /models
- Pay by card (Visa / Mastercard), Apple Pay, Google Pay or crypto
- Self-service: top up and activate instantly
Four key values to know first
Primary model, three tier aliases, and global subagent override
ANTHROPIC_MODEL sets the main session, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL control alias resolution, and CLAUDE_CODE_SUBAGENT_MODEL locks Explore, Plan, and every other subagent onto one model; ANTHROPIC_DEFAULT_FABLE_MODEL pins the fable alias.
Anthropic official API input rate gap (per 1M tokens)
On Anthropic's official pricing page (checked 2026-11-22): Claude Haiku 5.5 bills $0.10 input and $0.50 output for prompts up to 100,000 tokens; Sonnet 5.5 bills $2 / $10; Opus 5.5 bills $4 / $20; and Fable 5.2 bills $8 / $40. Keeping the flagship on the main thread and routing search subagents to lighter tiers changes session spend dramatically.
Shipped 2026-11-20 with subagent and model-switch fixes
Claude Code v2.1.330 fixes subagent-declared MCP servers shutting down while other subagents still use them, stopped background subagents failing to stay stopped, stale system-prompt instructions after switching models post-/context, and SessionStart hook env vars being lost on claude -p --continue.
Global env block that overrides shell exports
When the same variable is set in both your shell and a settings file env block, the settings file wins in most sessions and also reaches background agents. Never place API credentials in a committed project .claude/settings.json; use .claude/settings.local.json for single-project overrides.
Roles, precedence, and alias resolution across the 5 env vars
Claude Code resolves model selection in five priority layers: in-session /model wins first, followed by the startup flag claude --model, the ANTHROPIC_MODEL environment variable, the model field in settings, and finally ANTHROPIC_DEFAULT_MODEL for new sessions (requires v2.1.236 or later). Whenever you pass an alias such as opus, sonnet, haiku, fable, or opusplan, or declare model: sonnet or model: haiku in a custom subagent's YAML frontmatter, Claude Code resolves that alias to a full model ID. On the Anthropic API, opus, sonnet, and haiku resolve to Opus 5.5 (v2.1.280+), Sonnet 5.5 (v2.1.284+), and Haiku 5.5 (v2.1.293+), while fable resolves to Fable 5.2 (v2.1.321+).
On Amazon Bedrock, Microsoft Foundry, or custom LLM gateways, default mappings can land on older or unconfigured IDs, so pinning full IDs via ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, and ANTHROPIC_DEFAULT_FABLE_MODEL is essential. For subagents, built-in Explore uses the parent conversation's model (dropping from Fable to the opus alias on subscriptions, Anthropic Console, or ANTHROPIC_BASE_URL gateways), Plan inherits from the parent conversation, statusline-setup runs on Sonnet, and claude-code-guide and web-fetch run on Haiku.
Setting CLAUDE_CODE_SUBAGENT_MODEL forces every subagent, Explore and Plan included, onto that single model. The older ANTHROPIC_SMALL_FAST_MODEL variable is deprecated; background tasks now use ANTHROPIC_DEFAULT_HAIKU_MODEL.
2026-11-20 update: v2.1.330 subagent fixes and community quota pressure
As of 2026-11-22, the latest Claude Code release v2.1.330 (shipped 2026-11-20) delivers several fixes directly affecting multi-subagent and pinned-model workflows.
- 1Subagent MCP lifecycle: fixed an MCP server declared by subagents shutting down when one subagent finished while other subagents or the session still used it.
- 2Background subagent state: fixed stopped background subagents sometimes not staying stopped, and fixed Claude still waiting for a background agent stopped just as it finished in app or SDK sessions.
- 3Model switching and settings: fixed the system prompt keeping the earlier model's instructions when switching models after /context before the first message, and fixed user settings changes being lost when several Claude Code processes saved concurrently.
- 4Hooks and pinned fallbacks: fixed environment variables written by a SessionStart hook being lost under claude -p
--continue, and fixed Amazon Bedrock (Mantle) terminal sessions started with no model selected ignoring a pinned Opus model. On the community side, developers posting on forums and X between 2026-11-19 and 2026-11-20 reported burning through weekly subscription limits in 1 to 2 days when pairing flagship coordinators with parallel subagents, accelerating adoption of an Opus 5.5 supervisor plus Sonnet or lower-cost worker split.
Three checkpoints: quota pressure, v2.1.330 fixes, and current baseline
Between 2026-11-19 and 2026-11-20, heavy users in community threads reported exhausting weekly subscription limits in 1 to 2 days under parallel multi-agent runs, with session caps hit around 800k tokens; discussion shifted rapidly toward supervising on the main thread while delegating routine work to lower-cost subagents.
Claude Code v2.1.330 shipped on 2026-11-20, fixing premature shutdown of shared subagent MCP servers, background subagent stop handling, concurrent user-settings writes, and SessionStart hook env vars lost under claude -p --continue.
As of 2026-11-22, Anthropic API aliases opus, sonnet, haiku, and fable resolve to Opus 5.5, Sonnet 5.5, Haiku 5.5, and Fable 5.2; behind a custom gateway, pinning all three default alias variables plus CLAUDE_CODE_SUBAGENT_MODEL in ~/.claude/settings.json is the standard guard against misrouting and surprise spend.
Verified documentation details vs common misconceptions and community reports
Confirmed (Claude Code docs, v2.1.330 release notes, and vendor pricing pages)
- 1Gateway vs model selection: official docs state that
ANTHROPIC_BASE_URLchanges where requests are sent, not which model answers them, and since v2.1.196 Remote Control is disabled whenever it points to a host other than api.anthropic.com. - 2Concurrency and description limits:
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS(v2.1.217+) caps concurrent subagents per session with a default of 20;CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION(formerly 200) was removed in v2.1.224 and is now a no-op; combined custom subagent descriptions over 15,000 tokens trigger a startup warning. - 3Gateway model tuning: for model IDs Claude Code cannot recognize,
CLAUDE_CODE_MAX_OUTPUT_TOKENSdefaults to 32000 with a 128000 cap;CLAUDE_CODE_MAX_CONTEXT_TOKENSoverrides the assumed context window,CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1populates /model from /v1/models, andCLAUDE_CODE_PROMPT_CACHE_TTL(v2.1.242+) accepts 5m or 1h. - 4Official API pricing (per 1M tokens input / output): Anthropic official rates list Claude Fable 5.2 at $8 / $40; Opus 5.5 at $4 / $20; Sonnet 5.5 at $2 / $10; and Haiku 5.5 at $0.10 / $0.50 up to 100,000 tokens ($0.50 / $2.50 over 100,000 tokens). Z.AI official rates list GLM-5.3 at $1.4 input, $0.26 cached input, and $4.4 output, and GLM-5.3-Flash at $0.15 input, $0.03 cached input, and $0.50 output.
Common misconceptions and community-reported behavior
- 1"Setting
ANTHROPIC_BASE_URLautomatically selects the gateway's recommended model" — false. Official docs confirm it only changes the endpoint; leavingANTHROPIC_DEFAULT_*_MODEL unpinned lets Claude Code send unmapped defaults or older IDs that the gateway rejects. - 2"Shell exports always override
settings.json" — false. Official docs specify that when a variable exists in both your shell and a settings file env block, the settings file writes into the process environment and wins in most sessions. - 3"Built-in Explore always runs on Haiku by default" — false. Explore runs on the parent conversation's model (or the opus alias when the parent runs Fable via a subscription, Console, or
ANTHROPIC_BASE_URLgateway); to run it on Haiku, setCLAUDE_CODE_SUBAGENT_MODELor create a custom Explore file in~/.claude/agents/ with model: haiku. - 4"Switching /model to Sonnet restores an exhausted weekly subscription cap" — community reports note that 5-hour and weekly limits are shared across models; switching families only helps on a family-specific message such as "You've hit your Opus limit".
- 5"Use
ANTHROPIC_SMALL_FAST_MODELfor background tasks" — outdated; official docs mark it deprecated in favor ofANTHROPIC_DEFAULT_HAIKU_MODEL.
Two subagent cost-control patterns: global override vs per-agent routing
A: Lock every subagent via CLAUDE_CODE_SUBAGENT_MODEL
Set CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-5-5 (or claude-haiku-5-5) in the env block of settings.json to force Explore, Plan, and every custom subagent onto one tier. One line eliminates accidental Opus 5.5 or Fable 5.2 spend in background delegations, at the trade-off of not keeping a higher tier for specialized review subagents.
B: Pin tier aliases + route per agent in ~/.claude/agents/
Leave the global override unset, pin ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL, then define YAML frontmatter files under ~/.claude/agents/ such as an Explore override with model: haiku and a code-reviewer with model: sonnet while running the main thread on opus or opusplan (Opus for planning, Sonnet for execution). File edits hot-reload within seconds without restarting.
Three steps: configure gateway and tiered subagent routing in ~/.claude/settings.json
- 1Open user-level
~/.claude/settings.json(on Windows: %USERPROFILE%\.claude\settings.json; use gitignored .claude/settings.local.json for a single project and never put credentials in committed .claude/settings.json) and add the gateway URL and credential inside "env": "ANTHROPIC_BASE_URL": "https://api.qcode.cc/api" (mainland China:https://asia.qcode.cc/api; North America/Europe:https://us.qcode.cc/api) and "ANTHROPIC_AUTH_TOKEN": "your-cr-api-key". - 2In the same "env" block, pin the primary model, tier aliases, and subagent model: "
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", and "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-5-5" (orclaude-haiku-5-5for search-heavy workflows; optionally add "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1" to load /v1/models into /model). - 3Run a quick shell verification: 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": "."}]}' — a JSON reply with "id":"msg_ and "content" confirms the endpoint and key (on 401, check your credential variable or run /logout to clear an existing login). Launch claude, run /status to verify Anthropic base URL and Auth token, and switch anytime with /modelclaude-fable-5-2, /modelglm-5.3, or /modelkimi-k3.1-pro(press s in the picker to switch for the current session only).
Run a multi-model tiered workflow with one QCode API key
QCode.cc is an independent API access service with no affiliation to Anthropic, OpenAI, or Z.AI. Pointing ANTHROPIC_BASE_URL in Claude Code to https://api.qcode.cc/api (https://asia.qcode.cc/api for mainland China, https://us.qcode.cc/api for North America and Europe) lets one cr_ key drive every tier in one workflow: run claude-opus-5-5 or claude-fable-5-2 on the main thread for architecture and hard debugging, assign subagents to claude-sonnet-5-5 or claude-haiku-5-5, and switch via /model to glm-5.3, glm-5.3-flash, kimi-k3.1-pro, or deepseek-v4.1-flash without juggling vendor accounts or hitting 5-hour and weekly subscription locks.
The same key also connects Codex CLI (https://api.qcode.cc/openai) and OpenAI-compatible clients (https://api.qcode.cc/openai/v1) to models like gpt-6.2-sol and qwen3.8-max. Billing is per token with live per-model rates on /models. Supported payments include Visa / Mastercard, Apple Pay, Google Pay, Alipay, WeChat Pay, Russian local bank cards and SBP, CIS bank cards, and multi-network USDT across 18 networks (0% platform fee, usually minutes and up to 12 hours).
Not ready for a monthly plan? Pay-as-you-go Packs start at $4 for a one-time quota you use within 7 days; if you already have a Personal Plan, add a booster pack when you need more quota.
Frequently asked questions
What is the difference between ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL, and CLAUDE_CODE_SUBAGENT_MODEL?
Each group controls a distinct layer: main session, alias resolution, and subagents. ANTHROPIC_MODEL sets the primary session model (above the settings model field and ANTHROPIC_DEFAULT_MODEL, below --model and /model). ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, and ANTHROPIC_DEFAULT_FABLE_MODEL determine which full model ID each alias (opus, sonnet, haiku, fable) resolves to, with ANTHROPIC_DEFAULT_HAIKU_MODEL also handling background functionality. CLAUDE_CODE_SUBAGENT_MODEL forces Explore, Plan, and every custom subagent onto one model.
Why did my shell export for model env vars not take effect in Claude Code?
Most often, the env block in ~/.claude/settings.json (or managed settings) replaced the shell value. Official docs state that when the same variable is set in both your shell and a settings file env block, the settings file writes into the process environment and wins in most sessions. In addition, /model (pressing Enter saves it as your user default) and --model override ANTHROPIC_MODEL. Keep your variables consolidated in ~/.claude/settings.json under env and confirm active settings with /status and /model.
How do I stop built-in Explore and Plan subagents from burning Opus or Fable tokens?
Two direct options work. First, set CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-5-5 or claude-haiku-5-5 inside the env block of ~/.claude/settings.json to force Explore, Plan, and all other subagents onto a lower-cost tier. Second, create a Markdown file named Explore in ~/.claude/agents/ (user scope) or .claude/agents/ (project scope) with model: haiku in its YAML frontmatter to override the built-in Explore agent. You can also cap parallel spawns with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (default 20).
How do I troubleshoot 401 or unknown-model errors behind a custom gateway?
A 401 usually indicates a credential-header mismatch or a stale login, while an unknown-model error means an alias resolved to an unmapped model ID. ANTHROPIC_AUTH_TOKEN sends Authorization: Bearer and immediately overrides a saved claude.ai login, whereas ANTHROPIC_API_KEY sends x-api-key and prompts once in interactive mode. On 401, run /status to check the active credential, run /logout if a saved login conflicts, and verify with curl against "$ANTHROPIC_BASE_URL/v1/messages". On unknown-model errors, pin ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL to exact IDs served by your gateway such as claude-sonnet-5-5.
Does QCode require a monthly subscription, and how do Packs and renewals work?
No monthly plan is required: QCode bills per token with live per-model rates listed on /models. Pay-as-you-go Packs are valid for 7 days with a concurrency cap of 5, return HTTP 402 when quota runs out and HTTP 401 when expired, and buying another pack restores and stacks quota on the same API key (packs are non-refundable). Personal Plans run on a monthly cycle with booster packs available during validity, while expired Personal Plan keys cannot be renewed in place and require opening a new key.
Which payment methods, minimum top-ups, and settlement times does QCode support?
QCode accepts international credit cards (Visa / Mastercard), Apple Pay, Google Pay, Alipay, WeChat Pay, Russian local bank cards and SBP, CIS bank cards, and multi-network cryptocurrency (USDT across 18 networks, 0% platform fee, manually verified on-chain, typically credited in minutes and up to 12 hours). The unified recharge page qcode.cc/recharge keeps USD and CNY balances separate: USD top-ups start at $5 (up to $2,000 per transaction) and CNY top-ups start at ¥30.
Sources
Claude Code official documentation: 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), and 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); community threads on Reddit and X (2026-11-19 to 2026-11-20, used as user-context background only, not official policy). All verified on 2026-11-22.
Put tiered model routing in settings.json and run every tier on one key
No monthly commitment required: create a QCode account for a cr_ API key, drop it into ~/.claude/settings.json in 30 seconds, and mix Opus 5.5, Sonnet 5.5, Haiku 5.5, and GLM-5.3 in one workflow, with live rates on /models.
Related reading
Pay-as-you-go Packs: no monthly plan, valid 7 days
Buy a one-time quota valid for 7 days or add a booster pack to a Personal Plan; per-model rates are on /models.
Claude Code custom endpoint setup
The two environment variables, the settings.json form, apiKeyHelper, and the documented web-session limitation.
Claude Code 401 on a Custom Base URL: Invalid API Key Triage (2026-11)
Checked 2026-11-20: a 401 on a custom address has three shapes, so read the /status address and credential lines first, then the settings.json env block, the header each variable uses, and /v1.
Crypto payment guide
Nine coins, 56 networks, zero platform fee for AI coding API credits.
Claude Code model configuration, environment variable, subagent, and LLM gateway documentation, v2.1.330 release notes, and Anthropic and Z.AI pricing pages were verified on 2026-11-22 and are authoritative at code.claude.com, platform.claude.com, github.com/anthropics/claude-code, and docs.z.ai. QCode.cc is an independent API access service with no affiliation to and no endorsement from Anthropic, OpenAI, or Z.AI. QCode model availability and live rates follow qcode.cc/models.