Text of code.claude.com › docs › en › env-vars as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Environment variables - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. Environment variables can control Claude Code behavior such as model selection, authentication, request routing, and feature toggles. Many of the same behaviors can also be configured through a settings file field, a CLI flag , or an in-session command like /model .

This page covers how to: Set environment variables in your shell or in a settings file Check which value applies when a behavior can be set more than one way Look up the variables Claude Code reads See which features stop working when a variable turns feature-flag fetching off Set environment variables A variable you set in your shell lasts for that terminal session, while a variable in a settings file applies every time claude runs.

Set variables in your shell Set the variable before launching claude : macOS, Linux, WSL Windows PowerShell Windows CMD export API_TIMEOUT_MS = "1200000" claude To set it for every session, add the export line to ~/.bashrc , ~/.zshrc , or your shell’s profile file. $ env: API_TIMEOUT_MS = "1200000" claude To set it for every session, run [Environment]::SetEnvironmentVariable("API_TIMEOUT_MS", "1200000", "User") and open a new terminal. set API_TIMEOUT_MS = 1200000 claude To set it for every session, run setx API_TIMEOUT_MS "1200000" and open a new terminal.

The assignment line prints nothing on success. To confirm the variable is set, print it in the same shell: macOS, Linux, WSL Windows PowerShell Windows CMD echo $API_TIMEOUT_MS echo $ env: API_TIMEOUT_MS echo %API_TIMEOUT_MS% Set variables in settings files Add variables under the env key in a settings.json file, creating the file if it doesn’t exist. Claude Code reads them directly from the file, so they take effect no matter how claude was launched.

A running session applies new and changed values to its environment when you save the file, but a feature that reads its variables once at startup, such as OpenTelemetry monitoring , keeps its startup values until you relaunch. Removing a variable from the file doesn’t unset it in a running session; the removal takes effect the next time you launch claude . ~/.claude/settings.json { "env" : { "API_TIMEOUT_MS" : "1200000" , "BASH_DEFAULT_TIMEOUT_MS" : "300000" } } Claude Code copies these values into its environment as written.

No shell processes them, so shorthand such as ~ or $HOME stays as typed. For a variable that takes a path, such as CLAUDE_CONFIG_DIR , write the absolute path: "CLAUDE_CONFIG_DIR": "/home/you/.claude-work" . The file you choose controls who the variables apply to: File Applies to ~/.claude/settings.json You, in every project .claude/settings.json Everyone working in the project, checked into source control .claude/settings.local.json You, in this project only, gitignored when Claude Code saves a setting to it; add it to your gitignore if you create it by hand Managed settings Everyone in your organization, deployed by an admin See Settings files for where each file lives and Settings precedence for how they combine when more than one sets the same variable.

Precedence Some behaviors have both an environment variable and a dedicated settings key, and which one Claude Code reads first differs per key. For ANTHROPIC_MODEL and CLAUDE_CODE_AUTO_CONNECT_IDE , Claude Code reads the variable first and uses the model or autoConnectIde setting only when the variable is unset. For the pair you’re setting, check the variable’s row below and the key’s entry on the settings reference .

When the same variable is set in both your shell and a settings file env block, the settings file value applies in most sessions. Claude Code writes each env entry into the process environment, replacing the value inherited from the shell. How env values interact with your shell covers the sessions that keep the inherited value instead, and the env setting says when it applies them. A few variables are special-cased; the env setting lists the exceptions.

In a settings file you can set a variable but you can’t remove one. To override a variable you can’t unset, such as a stale CLAUDE_CODE_USE_VERTEX exported by a shell profile you don’t control, set it to an empty string in the env block: "CLAUDE_CODE_USE_VERTEX": "" . Claude Code treats the empty value as unset for provider selection. Subprocesses still inherit the empty value. Between settings files, env values follow settings precedence , so a managed settings entry overrides the same variable in user or project settings.

Project and local settings can’t set some variables, such as CLAUDE_CONFIG_DIR and the OpenTelemetry exporter variables. Variables Claude Code ignores in env lists them, along with the OpenTelemetry off values that still apply. How an environment variable interacts with CLI flags and in-session commands varies per feature: --model and /model override ANTHROPIC_MODEL , while CLAUDE_CODE_EFFORT_LEVEL overrides --effort and /effort .

When a variable interacts with another configuration source, its row in the Variables list states the precedence or links to the page that documents it. Claude Code reads shell environment variables at startup, so changes to them take effect the next time you launch claude . Variables set under the env key in settings files are reapplied to a running session when the file changes, with the startup-only exception described in Set variables in settings files .

Variables Numeric variables such as timeouts, token budgets, and retry counts accept scientific notation and digit-separator spellings in addition to plain digits, except where a variable’s row notes it takes plain digits only. For example, Claude Code reads 2e3 as 2000 and 64_000 as 64000. Before v2.1.211, these spellings could silently set a much smaller value, such as 1e6 setting a timeout to 1. For variables that turn a behavior on or off, set 1 , true , yes , or on to turn it on and 0 , false , no , or off to turn it off, in any casing.

Some variables read only whether you set them at all, so any non-empty value including 0 turns the behavior on, and you turn the behavior off by unsetting the variable or setting it to an empty value. These variables work that way: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC DISABLE_TELEMETRY DISABLE_ERROR_REPORTING CLAUDE_CODE_TMUX_TRUECOLOR IS_DEMO Each variable’s row also states its own rule. Variable Purpose ANTHROPIC_API_KEY API key sent as X-Api-Key header.

When set, this key is used instead of your Claude Pro, Max, Ultra, Team, or Enterprise subscription even if you are logged in. In non-interactive mode ( -p ), the key is always used when present. In interactive mode, you are prompted to approve the key once before it overrides your subscription. To use your subscription instead, run unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN Custom value for the Authorization header (the value you set here will be prefixed with Bearer ) ANTHROPIC_AWS_API_KEY Workspace API key for Claude Platform on AWS , generated in the AWS Console.

Sent as x-api-key and takes precedence over AWS SigV4 ANTHROPIC_AWS_BASE_URL Override the Claude Platform on AWS endpoint URL. Use for custom regions or when routing through an LLM gateway . Defaults to https://aws-external-anthropic.{region}.api.aws . Claude Code resolves the region with the same precedence as on Amazon Bedrock ANTHROPIC_AWS_WORKSPACE_ID Required for Claude Platform on AWS . Sent on every request as the anthropic-workspace-id header ANTHROPIC_BASE_URL Override the API endpoint to route requests through a proxy or gateway.

For what happens when that gateway rejects MCP tool search, see Tool search through an LLM gateway . As of v2.1.196, Remote Control is disabled when this points at a host other than api.anthropic.com , matching its behavior on Amazon Bedrock, Google Cloud’s Agent

The rest of this page is on the live site.