Claude Code environment variables: how to set them and the ones that matter

Claude Code environment variables are settings you pass through the environment instead of a config key: set them with export NAME=value before running claude, or under the env key in ~/.claude/settings.json so they apply to every session. The ones most people need cover authentication (ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN), the model (ANTHROPIC_MODEL), cloud providers (CLAUDE_CODE_USE_BEDROCK), timeouts (API_TIMEOUT_MS, BASH_DEFAULT_TIMEOUT_MS) and privacy (DISABLE_TELEMETRY).

The full table on Anthropic's environment variables page runs to several hundred rows. This guide, checked against that page on 26 October 2026, covers how to set variables, which value wins, and the variables worth knowing.

How do you set environment variables for Claude Code?

There are two ways, and they behave differently.

In your shell. Export the variable, then start claude. It lasts for that terminal session; add the line to ~/.zshrc or ~/.bashrc to keep it.

export API_TIMEOUT_MS="1200000"
claude

On Windows PowerShell use $env:API_TIMEOUT_MS = "1200000", and in CMD use set API_TIMEOUT_MS=1200000. Use setx or [Environment]::SetEnvironmentVariable to make it permanent, then open a new terminal.

In a settings file. Add the variable under env. Claude Code reads it straight from the file, so it applies however claude was launched.

{
  "env": {
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

Which file you pick decides who it applies to:

Two details from the docs trip people up. First, no shell processes these values, so ~ and $HOME stay as typed; write absolute paths. Second, saving the file updates a running session, but removing a variable only takes effect the next time you launch claude. Our settings guide explains the file hierarchy.

Which value wins when a variable is set twice?

• Shell vs settings file: in most sessions the settings file wins, because Claude Code writes each env entry over the inherited shell value.
• Between settings files: normal settings precedence, so managed settings beat user and project settings.
• Project files can't set everything. CLAUDE_CONFIG_DIR and the OpenTelemetry exporter variables are ignored in project and local settings.
• Variables vs flags: it depends on the feature. --model and /model override ANTHROPIC_MODEL, but CLAUDE_CODE_EFFORT_LEVEL overrides --effort and /effort.
• Can't unset a stale variable? Set it to an empty string in env, such as "CLAUDE_CODE_USE_VERTEX": "". Claude Code treats that as unset for provider selection.

For on/off variables, 1, true, yes or on turn a behavior on, and 0, false, no or off turn it off. The exceptions are DISABLE_TELEMETRY, DISABLE_ERROR_REPORTING and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: any non-empty value, even 0, switches them on. Unset them to switch back.

Which variables control authentication?

When several credentials exist, the authentication docs give this order: cloud provider variables, then ANTHROPIC_AUTH_TOKEN, then ANTHROPIC_API_KEY, then apiKeyHelper, then CLAUDE_CODE_OAUTH_TOKEN, then Anthropic profile credentials, and finally your /login subscription. A forgotten ANTHROPIC_API_KEY in your shell profile is the classic reason a subscriber suddenly sees API charges.

Which variables choose the model and provider?

Pinning the alias variables is how teams on Bedrock or Agent Platform map opus and sonnet to model IDs their account can use. See our Bedrock and Vertex guide, LLM gateway guide and models guide.

Which variables change timeouts, output and tokens?

Long builds and test suites are the usual reason to raise BASH_DEFAULT_TIMEOUT_MS. Numeric variables accept forms such as 2e3 or 64_000. Raising CLAUDE_CODE_MAX_OUTPUT_TOKENS shrinks the room left before auto-compaction, which our context window guide explains.

Which variables control privacy, updates and networking?

Turning off feature-flag fetching has a cost. The docs list features that stop working, including Remote Control with CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC set, claude import and the advisor tool. The network configuration page notes that Claude Code does not support SOCKS proxies. For OpenTelemetry setup, see our monitoring guide.

Which variables help with everyday setup and debugging?

A popular pattern from the docs runs two accounts side by side:

alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

Many of these have matching CLI flags; see our CLI reference. Inside containers, containerEnv in devcontainer.json is the usual place to set them, as our Docker guide shows.

Where should you keep these settings?

Put personal preferences in ~/.claude/settings.json, team defaults in the committed .claude/settings.json, and secrets in neither: keep API keys and tokens in your shell, a secrets manager or your CI's secret store. If you reuse the same instructions across projects, such as a setup checklist for new repos, Kipt can hold them as prompts in a private GitHub repo you own, next to your Agent Skills.