Setup guide · As of 2026-11-22

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.

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

Four key values to know first

5 core env vars

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.

$0.10 / $4

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.

v2.1.330

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.

~/.claude/settings.json

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.

  1. 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.
  2. 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.
  3. 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.
  4. 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

2026-11-19

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.

2026-11-20

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.

2026-11-22

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)

  1. 1Gateway vs model selection: official docs state that ANTHROPIC_BASE_URL changes 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.
  2. 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.
  3. 3Gateway model tuning: for model IDs Claude Code cannot recognize, CLAUDE_CODE_MAX_OUTPUT_TOKENS defaults to 32000 with a 128000 cap; CLAUDE_CODE_MAX_CONTEXT_TOKENS overrides the assumed context window, CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 populates /model from /v1/models, and CLAUDE_CODE_PROMPT_CACHE_TTL (v2.1.242+) accepts 5m or 1h.
  4. 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. 1"Setting ANTHROPIC_BASE_URL automatically selects the gateway's recommended model" — false. Official docs confirm it only changes the endpoint; leaving ANTHROPIC_DEFAULT_*_MODEL unpinned lets Claude Code send unmapped defaults or older IDs that the gateway rejects.
  2. 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. 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_URL gateway); to run it on Haiku, set CLAUDE_CODE_SUBAGENT_MODEL or create a custom Explore file in ~/.claude/agents/ with model: haiku.
  4. 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. 5"Use ANTHROPIC_SMALL_FAST_MODEL for background tasks" — outdated; official docs mark it deprecated in favor of ANTHROPIC_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

  1. 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".
  2. 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" (or claude-haiku-5-5 for search-heavy workflows; optionally add "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1" to load /v1/models into /model).
  3. 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 /model claude-fable-5-2, /model glm-5.3, or /model kimi-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

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.

Not sure where to start?

Try it for a week

Small Pack: $4 for $30 of quota, valid 7 days

Use it every day

Starter: $9.00/month with $5 of quota every day — just $0.060 per $1 of quota, vs about $0.113 for the Medium Pack