Claude Code Environment Variables Reference (2026): Every Config Flag Explained

Claude Code is configured almost entirely through environment variables and a project-level settings.json file, not a GUI. If you've ever wondered which variable controls the model, the API endpoint, or the thinking-token budget, this is the reference: every commonly used flag, what it does, and where to set it.

Core Environment Variables

These are the variables you'll touch most often. Set them in your shell profile (.zshrc/.bashrc), a .env file loaded by your terminal, or directly before launching claude.

settings.json vs Environment Variables

Environment variables are best for secrets and per-machine overrides (API keys, base URLs). For project-shared config that should live in version control, use .claude/settings.json at the repo root — it supports most of the same keys in camelCase form (e.g. model, maxOutputTokens) plus permission rules and hook definitions. Precedence, from highest to lowest: command-line flags → environment variables → project settings.json → user-level ~/.claude/settings.json → built-in defaults. If a teammate says “it works on my machine,” check for a stray env var overriding the committed settings file.

Common Configuration Mistakes

A few issues account for most support threads:

• Setting ANTHROPIC_BASE_URL without matching auth. Most relays expect ANTHROPIC_AUTH_TOKEN rather than ANTHROPIC_API_KEY — check the relay's docs, since mixing them silently falls back to a 401.
• Wrong model id after a version bump. Model names change (Sonnet 5, Opus 5, Fable 5 all shipped in 2026) — a stale ANTHROPIC_MODEL value throws a 404 rather than a friendly error on some backends.
• Proxy variables set globally but not exported. If HTTPS_PROXY is only defined in an interactive shell RC file, background CI runners or cron jobs won't see it — export it explicitly in the job definition.
• Forgetting NO_PROXY for local relays. If you run a relay on 127.0.0.1, add it to NO_PROXY or requests get routed through your corporate proxy and fail.

Verifying Your Configuration

After changing any of the above, don't just assume it took effect — verify it. Run claude config list (or check the startup banner) to confirm which model and base URL are actually active for the current session; Claude Code prints the effective base URL on first connect in a fresh terminal. If a request fails with an auth error right after switching relays, first rule out a leftover ANTHROPIC_API_KEY still exported alongside a new ANTHROPIC_AUTH_TOKEN — mixing the two is the single most common cause of confusing 401s after a relay migration. A clean way to test in isolation is to unset both variables, export only the ones the new provider expects, then run one throwaway prompt before resuming real work.

Pointing Claude Code at a Cheaper Relay

Because Claude Code just reads ANTHROPIC_BASE_URL and an auth variable, switching providers is a two-line change — no code edits, no SDK swap. This is exactly how people cut costs without giving up the native Claude Code UX: set the base URL to a relay endpoint, keep the same CLI commands, hooks, and subagents you already built.

This is the setup we use with Safa API: one ANTHROPIC_BASE_URL value gives you Claude Opus 5 / Sonnet 5 at a lower per-token price than direct billing, with prompt caching supported end-to-end so repeated system prompts and long file context stay cheap. No US credit card required — pay by Alipay — and the same account/API key also works as an OpenAI-compatible endpoint if you want GPT or Gemini models in the same project without juggling separate keys.

export ANTHROPIC_BASE_URL="https://aisafa.xyz/v1"
export ANTHROPIC_AUTH_TOKEN="sk-your-safa-key"
claude

Frequently Asked Questions

Does changing ANTHROPIC_BASE_URL break Claude Code's built-in tools (subagents, hooks, MCP)?

No. Base URL only changes where model requests are sent; local features like subagents, hooks, and MCP servers run entirely client-side and are unaffected as long as the relay is OpenAI/Anthropic-API compatible.

Can I set different models for different projects?

Yes — put model in each project's .claude/settings.json instead of a global env var, and each repo will use its own default model.

Why does Claude Code ignore my env var change until I restart?

Claude Code reads environment variables once at process start. After editing your shell profile or exporting a new value, open a new terminal session (or run exec zsh/exec bash) before launching claude again.