Claude Code Environment Variables Worth Setting
Claude Code environment variables by job: auth, model, proxy, timeouts, telemetry and updates, plus how to set them in your shell or settings.json.
Josh Pocock8 min read
AI Coding
Env variables
Stride AI Academy
Claude Code environment variables let you change how it signs in, which model it uses, where requests go, how long commands can run and what it sends home. You can export them in your shell before running claude, or put them under the env key in a settings file so they apply to every session. The settings file wins in most sessions when both set the same variable.
This guide covers how to set Claude Code env vars on each system, which value wins, and the variables most worth knowing, grouped by job: auth, model, proxy, timeouts, telemetry and updates. The full list is long, so this is a curated set. Everything here was checked against Claude Code's environment variables reference, network configuration docs, model configuration docs and settings reference on November 22, 2026.
How to set Claude Code environment variables
In your shell
Set the variable, then launch claude from the same window. On Mac, Linux or WSL:
export API_TIMEOUT_MS="1200000"
claudeAdd the export line to ~/.bashrc or ~/.zshrc to keep it. In Windows PowerShell:
$env:API_TIMEOUT_MS = "1200000"
claudeTo keep it in PowerShell, run [Environment]::SetEnvironmentVariable("API_TIMEOUT_MS", "1200000", "User") and open a new terminal. In CMD, use set for one window or setx to keep it. Shell variables are read once at startup, so restart Claude Code after changing one.
In settings.json
Put variables under env in a settings file and they apply however claude was launched:
{
"env": {
"API_TIMEOUT_MS": "1200000",
"BASH_DEFAULT_TIMEOUT_MS": "300000"
}
}Which file you use decides who gets them. ~/.claude/settings.json is you everywhere, .claude/settings.json is everyone in the project, and .claude/settings.local.json is you in one project.
Rules from the docs:
- Values are copied as written. No shell expands
~or$HOME, so write full paths. - Saving the file updates a running session, except for features that read their variables once at startup, such as OpenTelemetry monitoring.
- You can't unset a variable from a file. To cancel a shell export you don't control, set it to
"". - Project files can't set some variables, such as
CLAUDE_CONFIG_DIRand the OpenTelemetry exporter variables. Use your shell or user settings for those.
Which value wins
When a variable is set in both your shell and a settings file env block, the settings file value applies in most sessions. Between settings files, normal settings precedence applies, so managed settings beat user and project files.
Flags and commands vary by feature. The docs give two examples worth remembering:
--modeland/modeloverrideANTHROPIC_MODEL.CLAUDE_CODE_EFFORT_LEVELoverrides--effortand/effort.
For on/off variables, 1, true, yes or on turns a behavior on and 0, false, no or off turns it off. Three variables are exceptions: DISABLE_TELEMETRY, DISABLE_ERROR_REPORTING and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC treat any non-empty value, even 0, as on. Unset them to turn the behavior back off.
Auth variables
| Variable | What it does |
|---|---|
ANTHROPIC_API_KEY |
Sends an API key instead of using your subscription, even when you're logged in |
ANTHROPIC_AUTH_TOKEN |
Custom Authorization header value, prefixed with Bearer |
CLAUDE_CODE_OAUTH_TOKEN |
A claude.ai OAuth token for scripts and CI, made with claude setup-token |
CLAUDE_CODE_USE_BEDROCK |
Use Amazon Bedrock |
CLAUDE_CODE_USE_VERTEX |
Use Google Cloud's Agent Platform |
CLAUDE_CODE_USE_FOUNDRY |
Use Microsoft Foundry |
The one to watch is ANTHROPIC_API_KEY. In interactive mode you approve it once, then it overrides your Pro, Max or Ultra plan and bills at API rates. In -p mode it's used straight away. To go back to your plan, run unset ANTHROPIC_API_KEY. Our Claude API key guide covers creating and storing one, and the docs suggest the apiKeyHelper setting over a plain-text key in env.
Model variables
| Variable | What it does |
|---|---|
ANTHROPIC_MODEL |
The model for the session. --model and /model override it |
ANTHROPIC_DEFAULT_MODEL |
The model new sessions start on when nothing else picks one. Needs v2.1.236 or later |
ANTHROPIC_DEFAULT_OPUS_MODEL |
The model ID the opus alias points to |
ANTHROPIC_DEFAULT_SONNET_MODEL |
The model ID the sonnet alias points to |
ANTHROPIC_DEFAULT_HAIKU_MODEL |
The model ID the haiku alias points to, also used for background work |
ANTHROPIC_DEFAULT_FABLE_MODEL |
The model ID the fable alias points to |
CLAUDE_CODE_SUBAGENT_MODEL |
Default model for subagents, agent team teammates and workflow agents with no model set |
CLAUDE_CODE_EFFORT_LEVEL |
Effort: low, medium, high, xhigh or max. auto sends no effort level |
CLAUDE_CODE_DISABLE_FAST_MODE |
Set to 1 to turn fast mode off |
ANTHROPIC_MODEL and ANTHROPIC_DEFAULT_MODEL behave differently. ANTHROPIC_MODEL forces the model on every launch, whatever you saved with /model. ANTHROPIC_DEFAULT_MODEL only applies when no flag, variable or settings file picks a model, so a /model choice still sticks. Our guide to changing the model in Claude Code walks through the full order.
CLAUDE_CODE_SUBAGENT_MODEL is handy for cost: set it to haiku and helpers with no model of their own run on Haiku. A model set in an agent's own definition still wins.
Proxy, gateway and certificate variables
| Variable | What it does |
|---|---|
HTTPS_PROXY |
HTTPS proxy server. The docs recommend it over HTTP_PROXY |
HTTP_PROXY |
HTTP proxy, if HTTPS isn't available |
NO_PROXY |
Hosts that skip the proxy, space- or comma-separated, or * for all |
ANTHROPIC_BASE_URL |
Sends API requests to a proxy or LLM gateway instead of the default endpoint |
ANTHROPIC_CUSTOM_HEADERS |
Extra request headers, one Name: Value per line |
NODE_EXTRA_CA_CERTS |
Path to your company's CA certificate file |
CLAUDE_CODE_CERT_STORE |
Which CA sources to trust: bundled, system or both (the default) |
CLAUDE_CODE_CLIENT_CERT and CLAUDE_CODE_CLIENT_KEY |
Client certificate and key for mTLS |
A typical corporate setup looks like this:
export HTTPS_PROXY=https://proxy.example.com:8080
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pemFrom the network docs: lowercase versions work too, SOCKS proxies aren't supported, and basic auth goes in the URL as http://username:password@proxy.example.com:8080. For NTLM or Kerberos, the docs suggest an LLM gateway that supports it. By default Claude Code trusts both its bundled certificates and your operating system's store, so a company TLS proxy whose root certificate is installed on the machine usually works with no extra setup.
ANTHROPIC_BASE_URL changes where requests go, not which model answers. One side effect from the reference: since v2.1.196, Remote Control is off when it points anywhere other than api.anthropic.com. To run Claude Code against other backends, see our guide to Claude Code with Ollama and OpenRouter.
Timeout variables
| Variable | Default | What it limits |
|---|---|---|
API_TIMEOUT_MS |
600000 (10 minutes) | How long each API attempt waits for response headers |
BASH_DEFAULT_TIMEOUT_MS |
120000 (2 minutes) | A foreground Bash or PowerShell command |
BASH_MAX_TIMEOUT_MS |
600000 (10 minutes) | The longest timeout Claude can set for a command |
MCP_TIMEOUT |
30000 (30 seconds) | MCP server startup |
MCP_TOOL_TIMEOUT |
100000000 (about 28 hours) | MCP tool execution |
CLAUDE_CODE_MAX_RETRIES |
10 | Retries for failed API requests |
Raise API_TIMEOUT_MS on slow networks or behind a proxy, and BASH_DEFAULT_TIMEOUT_MS if your builds take longer than two minutes. HTTP and SSE MCP servers also have a 60-second per-request limit, which you raise by setting MCP_TOOL_TIMEOUT above 60000.
Telemetry, privacy and traffic variables
| Variable | What it turns off |
|---|---|
DISABLE_TELEMETRY |
Telemetry, plus feature-flag fetching |
DISABLE_ERROR_REPORTING |
Error reporting |
DISABLE_COST_WARNINGS |
Cost warning messages |
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC |
Auto-updates, telemetry, error reporting, /feedback, release notes and other nonessential traffic |
The reference says telemetry events don't include your code, file paths or Bash commands. Turning off feature-flag fetching also turns off some features, and the docs list which ones under "Features that need feature-flag fetching." Remember that these three treat even 0 as on.
Update variables
| Variable | What it does |
|---|---|
DISABLE_AUTOUPDATER |
Stops background updates. claude update still works |
DISABLE_UPDATES |
Blocks every update, including claude update and claude install |
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE |
Lets Claude Code run the Homebrew or WinGet upgrade for you |
Our guide to updating Claude Code covers channels and version pinning alongside these.
Other variables worth knowing
CLAUDE_CONFIG_DIRmoves the config folder from~/.claude. The docs' example runs a second account side by side:alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'. In a settings file, write the full path.DISABLE_AUTO_COMPACTset to1stops automatic compaction./compactstill works.
Check what's set
Print a variable in the same shell with echo $API_TIMEOUT_MS on Mac or Linux, or echo $env:API_TIMEOUT_MS in PowerShell. Inside Claude Code, /status shows your model, account and the settings files that loaded. For the commands you'll use alongside these, see the Claude Code cheat sheet.
Learn to build with Claude Code
The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code setups, and the Claude Code community is where members compare theirs.
FAQ
How do I set environment variables in Claude Code?
Export them in your shell before running claude, or add them under the env key in a settings file such as ~/.claude/settings.json. Settings file values apply every time Claude Code runs, however it was launched.
What does ANTHROPIC_MODEL do?
It sets the model for each session you launch. --model and /model override it, and it overrides the model key in your settings files. Use ANTHROPIC_DEFAULT_MODEL instead if you want a fallback that your /model choice can replace.
How do I use Claude Code behind a proxy?
Set HTTPS_PROXY to your proxy's URL, list hosts to skip in NO_PROXY, and point NODE_EXTRA_CA_CERTS at your company's CA certificate if it uses one. SOCKS proxies aren't supported.
How do I turn off Claude Code telemetry?
Set DISABLE_TELEMETRY to 1. Note that even 0 or false keeps it off, so unset the variable to turn telemetry back on. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC turns off telemetry along with auto-updates and other nonessential traffic.
Why is Claude Code billing my API key instead of my plan?
ANTHROPIC_API_KEY is set in your environment, and it overrides your subscription once you approve it. In -p mode it's used without asking. Run unset ANTHROPIC_API_KEY and restart Claude Code.
How do I make Bash commands time out later?
Set BASH_DEFAULT_TIMEOUT_MS to a longer value in milliseconds, such as 300000 for five minutes. BASH_MAX_TIMEOUT_MS sets the longest timeout Claude can choose for a single command.