Claude Code Environment Variables: The 12 That Matter

Claude Code environment variables are values you set before launching claude that control authentication, which model answers, where requests are routed, and dozens of behaviour toggles. You can export them in your shell for one session, or put them in a settings.json env block so they apply every time.

Model IDs and defaults verified 31 July 2026 against Anthropic's model overview.

There are well over a hundred of them documented. You will never need most. This guide covers the ones that actually change your day-to-day work, organised by the job they do — with the exact name, what it does, and when you'd bother setting it. We put this through its paces on our own setup first, so the notes below reflect what really happened, not what should happen.

If you are brand new to the tool, start with what Claude Code is and the installation walkthrough first. Env vars are a tuning layer on top of a working setup, not a substitute for one.

What Claude Code environment variables actually control

Every variable is read once at startup, so a change needs a relaunch. They split five ways: auth and routing, model selection, cloud-provider routing, behaviour toggles, and network proxies. Everything else is long tail.

Every variable is read once, at startup. Change one and nothing happens to your running session — you have to quit and relaunch claude. That single fact explains most of the confusion people hit ("I set the key, why is it still using my subscription?").

Broadly, the claude code environment variables that matter fall into five buckets:

1. Auth and routing — who you are, and which endpoint your requests hit.
2. Model selection — which model answers, and which one handles background work.
3. Cloud providers — Bedrock, Google Cloud's Agent Platform, and friends.
4. Behaviour toggles — compaction, telemetry, timeouts, thinking budget.
5. Network — proxies for locked-down corporate machines.

Everything else is a long tail you can safely ignore until a specific problem sends you looking.

Auth and routing

ANTHROPIC_API_KEY overrides your subscription whenever it is set. ANTHROPIC_AUTH_TOKEN supplies a bearer value for gateways that expect one. ANTHROPIC_BASE_URL changes where the request goes — never which model answers it.

ANTHROPIC_API_KEY is the big one. It's sent as the X-Api-Key header, and here's the part that surprises people: when it's set, it is used instead of your Claude Pro, Max, Team, or Enterprise subscription — even if you're logged in. In non-interactive mode (claude -p), the key is always used when present. In interactive mode you get prompted to approve it once. If you want your subscription back, unset ANTHROPIC_API_KEY and relaunch. A stale key left in a .zshrc from months ago is the single most common cause of "why is my Max plan billing me API credits?"

ANTHROPIC_AUTH_TOKEN sets a custom Authorization header value — whatever you put here gets prefixed with Bearer . This is for gateways that expect a bearer token rather than an Anthropic API key.

ANTHROPIC_BASE_URL overrides the API endpoint so requests route through a proxy or gateway. This is the one people misunderstand most often. It changes where the request goes, not which model answers. Point it at a gateway and you still need ANTHROPIC_MODEL to name the model that gateway should serve. It also has side effects: when it points at a non-first-party host, MCP tool search is disabled by default (set ENABLE_TOOL_SEARCH=true if your proxy forwards tool_reference blocks), and Remote Control is disabled when it points anywhere other than api.anthropic.com.

That trio is also the mechanism behind third-party routing setups — the same pattern used when people run Claude Code against OpenRouter. If you'd rather not deal with keys at all, the terminal login flow is simpler and, for most subscription users, the right answer.

Model selection

ANTHROPIC_MODEL sets a default that --model and /model still override. The per-class variables — ANTHROPIC_DEFAULT_OPUS_MODEL, _SONNET_, and _HAIKU_ — map picker choices to concrete IDs on a gateway.

ANTHROPIC_MODEL names the model setting to use. Note the precedence: the --model flag and the in-session /model command both override it, so it's a default, not a lock. For example, teams currently pin ANTHROPIC_MODEL to a specific Claude Opus 5 or Claude Sonnet 5 model ID so every developer gets identical behaviour rather than whatever the latest default happens to be.

You can also set per-class defaults: ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL. These tell Claude Code which concrete model ID to use when you pick "Opus" or "Sonnet" in the picker — handy on a gateway where the model IDs don't match Anthropic's.

Running InnovateTechie inside Claude Code, we deliberately do not pin ANTHROPIC_MODEL to a single ID, because our whole way of working is to route by task — Sonnet as the everyday default, escalating to Opus for the genuinely hard changes and dropping to a Haiku-class model for cheap, bulk work. Locking one model in an env block would fight that habit every session, so we leave the default alone and reach for /model mid-task instead. If your team's value comes from consistency rather than routing, pin it; if it comes from picking the right model per job, resist the urge to hard-code one.

One to avoid: ANTHROPIC_SMALL_FAST_MODEL is marked deprecated in the docs. Use ANTHROPIC_DEFAULT_HAIKU_MODEL for the background/Haiku-class slot instead. If you're mainly trying to switch models day to day, the model-switching guide covers the flags and /model rather than env vars.

Cloud providers

CLAUDE_CODE_USE_BEDROCK=1 routes through Amazon Bedrock and CLAUDE_CODE_USE_VERTEX=1 through Google Cloud. Mind the override chain: GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, and your credentials file all outrank ANTHROPIC_VERTEX_PROJECT_ID.

Two flags do the heavy lifting: CLAUDE_CODE_USE_BEDROCK=1 routes through Amazon Bedrock — the flag is only the first step, so see the full Claude Code Bedrock setup for the IAM policy and region pinning it depends on — and CLAUDE_CODE_USE_VERTEX=1 routes through Google Cloud's Agent Platform. Each has a supporting cast — ANTHROPIC_VERTEX_PROJECT_ID for your GCP project, for instance, though it's overridden by GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, or the project baked into your GOOGLE_APPLICATION_CREDENTIALS file. That override chain catches people out constantly.

Behaviour toggles

Compaction, cost warnings, telemetry, thinking budget, and timeouts each have a switch. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 bundles the autoupdater, feedback, error-reporting, and telemetry opt-outs into the single setting a security team will ask for.

These are the quality-of-life claude code environment variables — the ones you set once and forget:

• DISABLE_AUTO_COMPACT=1 — stops automatic compaction near the context limit. /compact still works manually. Set this when you want explicit control over when your context gets squashed.
• DISABLE_COST_WARNINGS=1 — silences cost warning messages.
• DISABLE_TELEMETRY=1 — opts out of telemetry. It also disables feature-flag fetching, so some flagged features may quietly become unavailable. That trade-off is worth knowing before you set it org-wide.
• CLAUDE_CODE_ENABLE_TELEMETRY=1 — the opposite direction: turns on OpenTelemetry collection. Required before configuring OTel exporters.
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 — a single switch equivalent to setting DISABLE_AUTOUPDATER, DISABLE_FEEDBACK_COMMAND, DISABLE_ERROR_REPORTING, and DISABLE_TELEMETRY together. This is the one to hand your security team.
• MAX_THINKING_TOKENS — overrides the extended thinking budget. The ceiling is the model's max output tokens minus one.
• BASH_DEFAULT_TIMEOUT_MS — default timeout for long-running bash commands (default 120000, i.e. 2 minutes). BASH_MAX_TIMEOUT_MS caps what the model itself may set (default 600000).
• API_TIMEOUT_MS — API request timeout (default 600000). Raise it on slow networks or when routing through a proxy.

Network and proxies

HTTP_PROXY, HTTPS_PROXY, and NO_PROXY follow the standard Unix conventions, and Claude Code honours them. On a corporate machine that trio plus a raised API_TIMEOUT_MS clears up most connectivity misery.

The proxy claude code environment variables follow the standard Unix conventions, and Claude Code respects them. HTTP_PROXY and HTTPS_PROXY specify proxy servers for network connections; NO_PROXY lists domains and IPs that should bypass the proxy entirely. On a corporate machine, this trio plus API_TIMEOUT_MS solves most connectivity misery.

The variables worth memorising

Twelve cover nearly everything: the three auth and routing names, two model defaults, the two cloud flags, auto-compact, the nonessential-traffic switch, the two timeout knobs, and the proxy trio.

If you only learn a dozen claude code environment variables, make it these:

How to set claude code environment variables properly

A shell export lasts one terminal session; an env block in a settings file applies to every launch however it started. Which settings file you pick decides whether the values reach you, the project, or the whole organisation.

Two places, two different lifespans. A shell export lasts for that terminal session. A settings file entry applies every time claude runs, no matter how it was launched — which is what you want for anything a team should share. The env block is only one key in that file, so it's worth knowing how settings.json is structured before you start adding variables to it.

# Shell: this terminal session only
export ANTHROPIC_BASE_URL="https://gateway.internal.example.com"
export API_TIMEOUT_MS="1200000"
claude
 
# Make it permanent: add those lines to ~/.zshrc or ~/.bashrc
# Windows PowerShell equivalent:
#   $env:API_TIMEOUT_MS = "1200000"

// .claude/settings.json — checked in, applies to everyone on the project
{
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "DISABLE_AUTO_COMPACT": "1"
  }
}

Which file you pick decides who gets the variables:

Precedence, in the order that bites you

• Where a behaviour has both an env var and a settings field, the env var wins. ANTHROPIC_MODEL beats the model setting.
• Where the same variable is in both your shell and a settings env block, the settings file wins. Claude Code writes each env entry into the process environment at startup, replacing what the shell handed it.
• Between settings files, managed settings beat project settings, which beat user settings.
• CLI flags vary per feature — --model and /model override ANTHROPIC_MODEL.

Read that second bullet twice. It's backwards from what most tools do, and it's why echo $ANTHROPIC_MODEL in your shell can disagree with what Claude Code actually used.

The security bit

Never put a real API key in .claude/settings.json — it is a checked-in file, so the key ships to everyone with repo access and to every fork. Use settings.local.json, a secret manager, or subscription login.

Never commit a real API key. .claude/settings.json is a checked-in file — putting ANTHROPIC_API_KEY in its env block ships your key to everyone with repo access and to every fork. Use .claude/settings.local.json (gitignored), a secret manager, or better yet skip the key entirely and use the subscription login. Of all the claude code environment variables, this is the only one that can genuinely cost you money if it leaks — if you need a key-free setup for other reasons, there are ways to run Claude Code without logging in.

The short version

Learn ANTHROPIC_API_KEY and why to unset it, ANTHROPIC_BASE_URL as routing rather than model choice, ANTHROPIC_MODEL, the proxy trio, and the two timeout knobs. Share team values through .claude/settings.json, and restart after every change.

You don't need to learn all of the claude code environment variables. Learn ANTHROPIC_API_KEY (and why to unset it), ANTHROPIC_BASE_URL (routing, not model choice), ANTHROPIC_MODEL, the proxy trio, and the two timeout knobs. Put anything the whole team needs in .claude/settings.json under env, keep secrets out of it, and remember that a restart is required.

For the authoritative list — and it is genuinely long — see the official environment variables reference. For how the env block interacts with everything else in your config, the settings documentation is the place to look.