Fix Claude Code Environment Variable Configuration Errors

## Overview

Claude Code is configured through a layer of environment variables on top of its settings files. Variables can come from your shell, from the `env` block in a `settings.json` file, or from CLI flags, and they generally take precedence over the matching settings field. Claude Code reads variables at startup, so changes take effect on the next launch.

When something is misconfigured, the symptoms are usually one of: the wrong account or API key is in use, the wrong model is selected, a proxy/gateway endpoint isn't being honored, or a value you set in one file is being silently overridden by another scope. This guide covers how to set the documented variables correctly and how to diagnose which layer is winning.

## Setting environment variables

You can set variables in your shell before launching Claude Code:

```bash
# macOS, Linux, WSL
export ANTHROPIC_API_KEY="sk-ant-..."
export ANTHROPIC_MODEL="claude-sonnet-4-5"
export API_TIMEOUT_MS="1200000"
claude
```

```powershell
# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-..."
$env:API_TIMEOUT_MS = "1200000"
claude
```

To apply the same variables to every session and to the subprocesses Claude Code spawns, set them under the `env` key in `settings.json` (for example `~/.claude/settings.json` for user scope, or `.claude/settings.json` in a project):

```json
{
  "env": {
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "DISABLE_TELEMETRY": "1"
  }
}
```

For dynamically generated credentials (temporary or rotating keys), use the `apiKeyHelper` setting instead of a static key. It points at a script run in `/bin/sh`; its output is sent as the `X-Api-Key` and `Authorization: Bearer` headers, and the refresh interval is controlled by `CLAUDE_CODE_API_KEY_HELPER_TTL_MS`:

```json
{
  "apiKeyHelper": "/path/to/generate_temp_api_key.sh"
}
```

> One important gotcha: variables in `settings.json` `env` do **not** propagate to MCP child processes. Set per-server `env` inside `.mcp.json` instead.

## Common environment variables

These are documented variables from the Claude Code environment variables reference. They are a subset focused on auth, model selection, endpoints, and the most common runtime knobs.

| Variable | What it does |
| :-- | :-- |
| `ANTHROPIC_API_KEY` | API key sent as the `X-Api-Key` header. When set, it overrides a Claude Pro/Max/Team/Enterprise subscription; in interactive mode you approve it once. |
| `ANTHROPIC_AUTH_TOKEN` | Custom value for the `Authorization` header (prefixed with `Bearer `). |
| `ANTHROPIC_BASE_URL` | Override the API endpoint to route through a proxy or gateway. |
| `ANTHROPIC_MODEL` | Override the default model for the session. |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Haiku-class model used for background tasks. |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Sonnet-class model to use. |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Opus-class model to use. |
| `CLAUDE_CODE_USE_BEDROCK` | Route requests through Amazon Bedrock. |
| `CLAUDE_CODE_USE_VERTEX` | Route requests through Google Vertex AI. |
| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Refresh interval (ms) for credentials generated by `apiKeyHelper`. |
| `API_TIMEOUT_MS` | Timeout for API requests (default 600000 / 10 min). Raise it on slow networks or proxies. |
| `BASH_DEFAULT_TIMEOUT_MS` | Default timeout for long-running Bash commands (default 120000 / 2 min). |
| `BASH_MAX_TIMEOUT_MS` | Maximum timeout the model can set for Bash commands (default 600000 / 10 min). |
| `MAX_THINKING_TOKENS` | Token budget for extended thinking; set to `0` to disable on models that support it. |
| `CLAUDE_CODE_EFFORT_LEVEL` | Effort level for the session (`low`, `medium`, `high`, `xhigh`, `max`, `auto`); takes precedence over `/effort` and the `effortLevel` setting. |
| `USE_BUILTIN_RIPGREP` | Set to `0` to use a system-installed `ripgrep` instead of the bundled binary. |
| `DISABLE_TELEMETRY` | Set to `1` to disable telemetry. |
| `DISABLE_AUTOUPDATER` | Set to `1` to disable automatic updates. |
| `CLAUDE_CONFIG_DIR` | Override the configuration directory (defaults to `~/.claude`); useful for isolating a clean config. |

For the complete list (Bedrock/Vertex/Foundry endpoints, TLS/mTLS certs, UI/terminal flags, and feature toggles), see the environment variables reference linked at the end.

## Troubleshooting

Start inside Claude Code with `/doctor`, which validates your configuration files and surfaces invalid keys, schema errors, and installation health. When it reports issues, press `f` to hand the diagnostic report to Claude and walk through fixes. If `claude` won't start at all, run `claude doctor` from your shell instead.

**A value you set seems ignored.** Settings merge across managed, user, project, and local scopes. Managed settings always win; otherwise the closer scope overrides the broader one in the order local, then project, then user. Environment variables and CLI flags act as a further override layer on top of settings. Run `/status` to see which settings sources are active (including whether managed settings are in effect). A frequent cause is the same key being set in `settings.local.json`, which overrides `settings.json`.

**Variables added globally are ignored.** `permissions`, `hooks`, and `env` belong in `~/.claude/settings.json`. If you put them in `~/.claude.json` (which only holds app state and UI toggles) they won't apply.

**MCP server starts without expected variables.** Variables in `settings.json` `env` don't propagate to MCP child processes. Move them to a per-server `env` block in `.mcp.json`. To see server stderr, run `claude --debug mcp`.

**Isolate the problem with a clean configuration.** Launch `claude --safe-mode` to disable all customizations (CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands) while keeping auth, model selection, and permissions working. If the problem disappears, one of those surfaces is the cause. To bypass everything under `~/.claude` as well, create a fresh private temporary directory, point `CLAUDE_CONFIG_DIR` at an empty subdirectory inside it, and launch from a folder with no project config:

```bash
clean_root="$(mktemp -d)" && chmod 700 "$clean_root"
mkdir "$clean_root/config" "$clean_root/work"
cd "$clean_root/work" && CLAUDE_CONFIG_DIR="$clean_root/config" claude
```

On Linux and Windows you'll be prompted to log in again in the clean session because credentials live under the config directory; on macOS they're in the Keychain and carry over. Never use a fixed path in a shared temporary directory for this test, because another local user could pre-create or tamper with it. If the problem persists even here, the cause is outside your user and project configuration — check for environment variables affecting Claude Code and managed settings via `/status`.

**Search isn't finding files.** If the bundled `ripgrep` can't run on your system, install your platform's `ripgrep` package and set `USE_BUILTIN_RIPGREP=0`.

For broader installation, login, and connectivity problems, see the troubleshooting and debug-your-configuration pages linked below.