Claude Code environment variables: official docs (API_KEY, BASE_URL)

Quick answer

Set ANTHROPIC_API_KEY in your shell rc or a .env file. Claude Code reads the variable on launch:

export ANTHROPIC_API_KEY="sk-ant-api03-..."

Need a corporate proxy or a different model? Use ANTHROPIC_BASE_URL and ANTHROPIC_MODEL. Full details below.

What are environment variables and where does Claude Code read them?

An environment variable is a named value stored in your shell session, readable by any program that runs within it. Think of it as a sticky note attached to every process: when Claude Code starts, it reads all the sticky notes and adjusts its behaviour accordingly.

Claude Code reads environment variables from four sources, in this order:

1. System environment (/etc/environment, /etc/profile.d/) — machine-wide, set by admins
2. Shell rc files (~/.bashrc, ~/.zshrc, ~/.profile) — per-user persistent settings
3. .env file in the current project directory — per-project overrides (loaded automatically)
4. VS Code claudeCode.environmentVariables setting — editor-level injection (see dedicated section below)

CLI flags and matching settings.json keys take precedence over environment variables when a direct equivalent exists.

Authentication variables

ANTHROPIC_API_KEY

# Persist in your shell rc file
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxx"

# One-shot override for a single command
ANTHROPIC_API_KEY="sk-ant-..." claude --print "hello"

# GitHub Actions: pass from encrypted secret
env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

ANTHROPIC_AUTH_TOKEN

export ANTHROPIC_AUTH_TOKEN="bearer-token-from-your-proxy"

Some corporate AI gateways use their own token format instead of Anthropic's standard header. Set this when your proxy returns 401 Unauthorized even with a valid ANTHROPIC_API_KEY.

ANTHROPIC_BASE_URL

# Corporate AI gateway
export ANTHROPIC_BASE_URL="https://ai-gateway.company.com/anthropic"

# Local mock server for testing
export ANTHROPIC_BASE_URL="http://localhost:8080"

This variable overrides the customApiUrl field in settings.json. Useful when you route API traffic through a company-managed proxy or a regional endpoint.

ANTHROPIC_MODEL / CLAUDE_MODEL

# Use Haiku for speed and cost savings
export CLAUDE_MODEL="claude-haiku-4-5"

# Use Opus for complex reasoning tasks
export CLAUDE_MODEL="claude-opus-4-6"

# Per-command override without touching your rc file
CLAUDE_MODEL="claude-opus-4-6" claude --print "hard task"

ANTHROPIC_MODEL is an accepted alias for CLAUDE_MODEL. Both work identically. Stick with CLAUDE_MODEL in new setups to align with the official docs.

Common model identifiers:

• claude-haiku-4-5: Fast and cheap, good for automation
• claude-sonnet-4-6: Recommended balance of capability and cost
• claude-opus-4-6: Highest reasoning depth, highest cost

CLAUDE_CODE_USE_BEDROCK

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION="us-east-1"
# AWS credentials via standard AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY
# or via IAM role if running on EC2/ECS

When set, Claude Code uses the AWS SDK for authentication. Your ANTHROPIC_API_KEY is ignored; AWS credentials are used instead.

CLAUDE_CODE_USE_VERTEX

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION="us-central1"
export ANTHROPIC_VERTEX_PROJECT_ID="your-gcp-project-id"
# Authenticate via gcloud application-default login

Behaviour variables

MAX_THINKING_TOKENS

# Reduce budget to lower costs on routine tasks
export MAX_THINKING_TOKENS=10000

# Full budget for architecture or complex debugging sessions
export MAX_THINKING_TOKENS=31999

# Effectively disable deep reasoning (minimum value)
export MAX_THINKING_TOKENS=1000

Only active when alwaysThinkingEnabled: true in settings.json, or when Extended Thinking is triggered manually. Reducing this value shortens the internal chain-of-thought and lowers the associated token cost.

BASH_MAX_OUTPUT_LENGTH

# Default — good for most commands
export BASH_MAX_OUTPUT_LENGTH=10000

# Raise for commands that produce verbose output (build logs, test suites)
export BASH_MAX_OUTPUT_LENGTH=50000

# Lower to protect the context window on token-heavy models
export BASH_MAX_OUTPUT_LENGTH=5000

When a command produces more output than this limit, Claude Code truncates the result and adds a notice. This prevents a single cat large-file.log from filling the entire context window.

BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS

export BASH_DEFAULT_TIMEOUT_MS=120000   # 2 min default per command
export BASH_MAX_TIMEOUT_MS=600000       # 10 min hard cap (user can override up to this)

Raise BASH_DEFAULT_TIMEOUT_MS when running slow builds or long test suites inside Claude Code sessions. The BASH_MAX_TIMEOUT_MS is the ceiling that users cannot exceed when manually overriding the timeout in a conversation.

CLAUDE_CODE_MAX_OUTPUT_TOKENS

# Cap responses for cost control in automation
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096

# Allow long responses for code generation tasks
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000

DISABLE_AUTOUPDATER

export DISABLE_AUTOUPDATER=1

Always set this in CI/CD. Auto-updates during a pipeline run can change behaviour unexpectedly. Pair with a pinned install: npm install -g @anthropic-ai/claude-code@x.y.z.

DISABLE_TELEMETRY

export DISABLE_TELEMETRY=1

DISABLE_ERROR_REPORTING

export DISABLE_ERROR_REPORTING=1

DISABLE_COST_WARNINGS

export DISABLE_COST_WARNINGS=1

Useful in non-interactive scripts where cost banner output would pollute stdout parsing.

CLAUDE_CONFIG_DIR

# Per-project isolated config
export CLAUDE_CONFIG_DIR="$(pwd)/.claude-config"

# Shared org config on a CI agent
export CLAUDE_CONFIG_DIR="/opt/claude-code/config"

# Throw-away config for ephemeral containers
export CLAUDE_CONFIG_DIR="/tmp/claude-ci-$$"

CLAUDE_CODE_DISABLE_TERMINAL_TITLE

export CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1

Helpful for tmux users and terminal multiplexers that use the title string for tracking panes.

Network and proxy variables

HTTP_PROXY / HTTPS_PROXY

# Unauthenticated proxy
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

# Authenticated proxy (URL-encode special characters in password)
export HTTPS_PROXY="http://jdoe:p%40ssword@proxy.company.com:8080"

# SOCKS5 proxy
export HTTPS_PROXY="socks5://proxy.company.com:1080"

In corporate networks, these are the most common variables to configure. Claude Code uses them for all outbound requests, including API calls to api.anthropic.com.

NO_PROXY

export NO_PROXY="localhost,127.0.0.1,::1,*.corp.example.com"

# Combine with HTTPS_PROXY
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,*.intranet.company.com"

MCP variables

MCP_TIMEOUT / MCP_TOOL_TIMEOUT

export MCP_TIMEOUT=30000         # Allow 30 s for slow MCP servers to start
export MCP_TOOL_TIMEOUT=120000   # Allow 2 min for long-running tool calls

MAX_MCP_OUTPUT_TOKENS

export MAX_MCP_OUTPUT_TOKENS=50000

claudeCode.environmentVariables in VS Code

The official Claude Code VS Code extension exposes claudeCode.environmentVariables, a JSON object injected into every Claude Code process started from the editor. This is the cleanest way to configure per-workspace values without touching global shell files.

Open your settings.json (User-level or Workspace-level) and add:

{
  "claudeCode.environmentVariables": {
    "ANTHROPIC_BASE_URL": "https://ai-gateway.company.com/anthropic",
    "CLAUDE_MODEL": "claude-sonnet-4-6",
    "DISABLE_AUTOUPDATER": "1",
    "BASH_MAX_OUTPUT_LENGTH": "30000",
    "NO_PROXY": "localhost,127.0.0.1,*.intranet"
  }
}

The setting name uses camelCase: claudeCode.environmentVariables. The inner keys are case-sensitive — ANTHROPIC_API_KEY is not the same as anthropic_api_key.

Persisting variables across environments

Shell rc files (local development)

# Add to ~/.bashrc or ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export CLAUDE_MODEL="claude-sonnet-4-6"
export DISABLE_TELEMETRY=1

Run source ~/.zshrc (or open a new terminal) after editing.

systemd user service

If you run Claude Code as a systemd service:

# ~/.config/systemd/user/claude-code.service
[Service]
Environment=ANTHROPIC_API_KEY=sk-ant-api03-...
Environment=CLAUDE_MODEL=claude-sonnet-4-6
Environment=DISABLE_AUTOUPDATER=1

Or use EnvironmentFile=/etc/claude-code/env to load from a separate file and keep the service unit free of secrets.

Docker

# Pass at build time (non-secret config only)
ARG CLAUDE_MODEL=claude-sonnet-4-6
ENV CLAUDE_MODEL=$CLAUDE_MODEL
ENV DISABLE_AUTOUPDATER=1
ENV BASH_MAX_OUTPUT_LENGTH=30000

# Pass secrets at runtime — never bake them into the image
docker run \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -e CLAUDE_MODEL=claude-haiku-4-5 \
  my-claude-image

Secrets managers

For production pipelines, avoid storing raw API keys in shell files. Retrieve them at runtime:

# AWS Secrets Manager
export ANTHROPIC_API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id prod/anthropic-api-key \
  --query SecretString \
  --output text)

# HashiCorp Vault
export ANTHROPIC_API_KEY=$(vault kv get -field=value secret/anthropic)

Security checklist

• Add .env to .gitignore and to .gitignore_global to prevent accidental commits.
• Never hardcode ANTHROPIC_API_KEY in Dockerfile, CI YAML, or any committed file.
• Use repository secrets (GitHub Secrets, GitLab CI variables) for CI/CD pipelines.
• Rotate your API key every 90 days as a minimum. Rotate immediately if exposure is suspected.
• Audit who has read access to files that contain the key (~/.bashrc, /etc/environment).

# Minimal .gitignore entries
.env
.env.local
.env.*.local
*.key

Precedence order

When the same setting exists in multiple sources, Claude Code resolves them in this order. Later sources win:

CLI flags always win. settings.json values override environment variables when a direct equivalent key exists.

Troubleshooting

Check which variables are visible to Claude Code

# List all variables containing "claude" or "anthropic" (case-insensitive)
env | grep -iE "claude|anthropic|proxy"

# Verify the key format (should start with sk-ant-)
echo $ANTHROPIC_API_KEY | cut -c1-12

Confirm a variable is set in a new shell

# Open a new shell and test
bash -c 'echo $ANTHROPIC_API_KEY'

If this is empty but your current session has the value, the export is missing from your rc file (the variable may be defined without export).

Debug startup issues

# Verbose output showing which config files are loaded
claude --version

# Check that the API key reaches Anthropic (will fail gracefully if network is unavailable)
claude --print "hello" 2>&1 | head -20

Variable is set but ignored

Possible causes:

• The variable is defined but not exported (VAR=value vs export VAR=value)
• A settings.json key with higher priority is overriding it
• A typo in the variable name (use env | grep to verify exact spelling)
• In VS Code, the Workspace settings.json is overriding User settings.json with a conflicting value

# Verify the variable is exported, not just set
export -p | grep ANTHROPIC

ANTHROPIC_BASE_URL is ignored

Check that HTTPS_PROXY is not intercepting and rerouting the request. Add the base URL's hostname to NO_PROXY:

export ANTHROPIC_BASE_URL="https://ai-gateway.company.com/anthropic"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="ai-gateway.company.com,localhost,127.0.0.1"

Complete reference table

*Unless authenticated via claude login (Claude.ai Max account)

Configuration examples

Local development

# ~/.zshrc or ~/.bashrc
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export CLAUDE_MODEL="claude-sonnet-4-6"
export MAX_THINKING_TOKENS=10000
export DISABLE_TELEMETRY=1

CI/CD (GitHub Actions)

# .github/workflows/claude.yml
jobs:
  claude-task:
    runs-on: ubuntu-latest
    env:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      CLAUDE_MODEL: claude-haiku-4-5
      DISABLE_AUTOUPDATER: "1"
      DISABLE_COST_WARNINGS: "1"
      CLAUDE_CODE_MAX_OUTPUT_TOKENS: "4096"
      BASH_MAX_OUTPUT_LENGTH: "20000"
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @anthropic-ai/claude-code@latest
      - run: claude --print --max-turns 5 "Review code quality"

Corporate network with proxy

# /etc/environment or system profile
ANTHROPIC_API_KEY="sk-ant-..."
ANTHROPIC_BASE_URL="https://ai-gateway.company.com"
HTTPS_PROXY="http://web-proxy.company.com:8080"
NO_PROXY="localhost,127.0.0.1,ai-gateway.company.com,*.internal.company.com"
DISABLE_AUTOUPDATER=1
CLAUDE_CONFIG_DIR="/opt/claude-code/config"

FAQ

Next steps

• settings.json: complete guide: All configuration keys and their precedence over environment variables
• CLI reference: All flags for the claude command
• Cheatsheet: Quick reference for slash commands and keyboard shortcuts