Every Claude Code Environment Variable That Actually Matters

The Billing Gotcha Nobody Warns You About#

If you pay for a Claude Max subscription and also have ANTHROPIC_API_KEY set in your shell, Claude Code charges your API account. Not your subscription. I found this out the hard way when my April invoice showed $47 in API usage alongside my $100/month Max plan.

Warning: Setting ANTHROPIC_API_KEY in your shell profile overrides subscription billing. If you have a Max plan, remove the key from .bashrc/.zshrc and let Claude Code use its built-in auth. Check with echo $ANTHROPIC_API_KEY before your next long session.

The fix is simple: unset the variable. Run unset ANTHROPIC_API_KEY or remove it from your profile entirely. Claude Code falls back to its OAuth login, which routes through your subscription.

If you need both (subscription for daily work, API key for scripts), use ANTHROPIC_AUTH_TOKEN for the alternative auth path. It takes priority over settings.json but does not trigger API billing the same way.

Authentication and Model Selection#

Two claude code environment variables control authentication. ANTHROPIC_API_KEY is the standard one. ANTHROPIC_AUTH_TOKEN overrides whatever is stored in your local settings, which is useful for ephemeral environments where you inject secrets at runtime.

Model pinning is where things get interesting. You can lock Claude Code to a specific model version instead of accepting whatever Anthropic rolls out.

• ANTHROPIC_MODEL sets the default conversation model globally
• ANTHROPIC_DEFAULT_OPUS_MODEL pins a specific Opus version (e.g., claude-opus-4-6-20260410)
• ANTHROPIC_DEFAULT_SONNET_MODEL pins a specific Sonnet version
• ANTHROPIC_DEFAULT_HAIKU_MODEL pins Haiku (this replaced the deprecated ANTHROPIC_SMALL_FAST_MODEL)
• ANTHROPIC_CUSTOM_MODEL_OPTION adds a custom model ID to the /model picker without validation

I pin Sonnet for daily tasks and switch to Opus only for multi-file refactors. Pinning also prevents surprise behavior changes when Anthropic silently updates the model behind a version alias.

# Pin models for consistent behavior
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-20250514"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6-20260410"

Cloud Provider Routing#

Enterprise teams rarely call the Anthropic API directly. Bedrock, Vertex AI, and Azure AI Foundry each need their own set of environment variables. Get one wrong and Claude Code silently falls back to direct API, which means unexpected billing.

The pattern across all three providers is the same: one toggle variable to activate, region/project identifiers, and credentials. The toggle is critical because Claude Code defaults to the direct Anthropic API if it is missing.

Tip: Test your provider config with a short prompt before starting real work. If Claude Code responds but your cloud billing dashboard shows nothing, the toggle variable is not set and you are hitting the direct API.

Declare Claude Code Environment Variables in settings.json#

Stuffing environment variables into .bashrc works for one person. It falls apart the moment a second developer joins the project. Claude Code reads a settings.json file at ~/.claude/settings.json (user scope) and .claude/settings.json (project scope) that can declare environment variables alongside other configuration options.

Project-scoped settings travel with the repo. Every developer gets the same defaults without touching their shell.

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_REGION": "us-east-1",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-20250514",
    "BASH_MAX_TIMEOUT_MS": "300000"
  }
}

The env key in settings.json is the cleanest approach. Shell variables still override it, so individual developers can still customize locally. But the baseline is consistent and version-controlled.

Behavior Toggles Worth Knowing#

Beyond auth and model selection, a handful of variables control timeouts, telemetry, and tool behavior. Most people never touch these, but they solve real problems when you hit them.

• BASH_MAX_TIMEOUT_MS caps how long bash commands can run. Default is 120000 (2 minutes), max is 600000. Raise this if Claude Code keeps timing out on builds or test suites.
• CLAUDE_CODE_MAX_OUTPUT_TOKENS overrides the max output length. Useful when generation keeps getting cut off mid-function.
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is the master toggle for analytics. Set to 1 and Claude Code stops sending telemetry, update checks, and usage pings.
• DISABLE_TELEMETRY opts out of Statsig telemetry specifically. DISABLE_ERROR_REPORTING opts out of Sentry.
• DISABLE_AUTOUPDATER prevents Claude Code from updating itself. Pin this in CI or when you need reproducible tool versions.
• MCP_TIMEOUT and MCP_TOOL_TIMEOUT control how long MCP servers have to start up and respond.
• ANTHROPIC_BASE_URL redirects API traffic to a custom endpoint for local models, corporate gateways, or logging proxies. HTTP_PROXY and HTTPS_PROXY handle network-level proxying.
• CLAUDE_CODE_ENABLE_TELEMETRY plus the OTEL_* variables unlock OpenTelemetry trace export if your team runs a collector.

The telemetry trio (DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, DISABLE_ERROR_REPORTING) is worth setting in any corporate environment where outbound traffic gets flagged by security.

CI/CD and Headless Mode#

Running Claude Code in a pipeline requires a different configuration mindset. There is no interactive terminal, no OAuth flow, and no human to approve tool calls. The headless mode docs cover the full surface, but the essentials fit in one block.

export ANTHROPIC_API_KEY="$VAULT_CLAUDE_KEY"
export DISABLE_AUTOUPDATER=1
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

claude -p "Review this PR for security issues" \
  --max-turns 10 \
  --output-format json \
  --allowedTools Read,Grep,Glob

The -p flag passes a prompt directly without opening an interactive session. --max-turns prevents runaway loops, and --output-format json gives you structured output for downstream parsing.

--allowedTools restricts which tools Claude Code can invoke, so it cannot write files or run arbitrary commands in your pipeline. This is the single most important flag for CI safety.

• --output-format accepts text, json, or stream-json for real-time streaming
• CLAUDE_CODE_STREAMLINED_OUTPUT simplifies the output format for log ingestion
• ANTHROPIC_BASE_URL can point Claude Code at a gateway or proxy for rate-limit management in shared pipelines

For token cost control in CI, combine --max-turns with a specific model pin. Sonnet handles code review at a fraction of the Opus cost, and for most PR review tasks, the quality difference is negligible.

TL;DR: Start with zero env vars and add only what your setup demands. Max subscribers should remove ANTHROPIC_API_KEY. Enterprise teams need one provider toggle plus credentials. CI needs ANTHROPIC_API_KEY, DISABLE_AUTOUPDATER, and --max-turns. Everything else is tuning.