Claude Code Environment Variables

Environment variables are an important way to control Claude Code's behavior, allowing flexible adjustment of various settings without editing configuration files. This chapter details all environment variables supported by Claude Code, their purposes, configuration methods, and common usage scenarios.

Environment Variables Overview

Claude Code uses environment variables to control behavior. These variables can be set in the following ways:

  • Directly in the shellexport
  • In~/.claude/settings.jsonofenvConfigure in the field
  • At the project level.claude/settings.jsonConfigure in
  • Configure through the IDE plugin settings interface

Environment variable priority from highest to lowest: command line > project-level settings.json > user-level settings.json > shell environment variables. Variables configured in settings.json are automatically passed to the Claude process.

Authentication-Related Variables

Variable Name Description Value
ANTHROPIC_API_KEY Claude API key (obtained from claude.ai) API key string
ANTHROPIC_BASE_URL Target address for API requests (used for proxy or custom endpoints) URL address
ANTHROPIC_AUTH_TOKEN Authentication token (used for scenarios such as VS Code plugin) Token string

Configuration Examples

Example

# Set in the shell
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"

Example

// Configure in settings.json
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxxxx",
    "ANTHROPIC_BASE_URL": "https://custom-proxy.com/v1"
  }
}

Model Configuration Variables

Variable Name Description Value
ANTHROPIC_MODEL Default model used claude-opus-4-5、claude-sonnet-4-5、claude-haiku-3-5wait
ANTHROPIC_SMALL_FAST_MODEL Model used in fast response mode (for simple tasks) Model name
CLAUDE_CODE_SUBAGENT_MODEL Uniformly set the model used by all subagents Model name
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS Disable experimental features when using the Anthropic Messages format with Bedrock or Vertex 1

Usage Scenarios

Subagents inherit the main conversation's model by default. ThroughCLAUDE_CODE_SUBAGENT_MODELyou can configure them uniformly, assigning simple tasks to Haiku and complex analysis to Sonnet to optimize costs:

Example

# Main conversation uses Opus for complex reasoning, subagents uniformly use Sonnet
export ANTHROPIC_MODEL="claude-opus-4-5"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5"

Tool and Command Variables

Variable Name Description Value
CLAUDE_CODE_DISABLE_SLASH_COMMANDS Disable all slash commands 1
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS Disable the built-in Git-related system prompts (priority higher than the one in settings.jsonincludeGitInstructions） 1
CLAUDE_CODE_USE_POWERSHELL_TOOL Enable PowerShell tools on Windows (requiresdefaultShell: "powershell"setting) 1
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL Skip automatic IDE extension installation (alternativeautoInstallIdeExtensionsetting) 1
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS Disable background task functionality 1

Permissions and Security Variables

Variable name Description Value
CLAUDE_CODE_PERMISSION_MODE Set default permission mode (see subagent section for details) default、acceptEdits、dontAsk、bypassPermissions、plan
CLAUDE_CODE_ALLOWED_TOOLS Whitelist of tools allowed for Claude to use (comma-separated) Tool list
CLAUDE_CODE_DISALLOWED_TOOLS Blacklist of tools prohibited for Claude to use Tool list

Permission Modes Explained

  • default: Normal permission prompt, ask before each operation
  • acceptEdits: Automatically accept file edits without confirmation
  • dontAsk: Automatically reject unauthorized operations without interrupting execution
  • bypassPermissions: Skip all permission checks (only for fully trusted environments)
  • plan: Read-only planning mode, no write operations

Example

# Use read-only mode in CI environment
export CLAUDE_CODE_PERMISSION_MODE="plan"
export CLAUDE_CODE_ALLOWED_TOOLS="Read,Grep,Glob,Bash(gh *)"

Logging and Debugging Variables

Variable name Description Value
CLAUDE_CODE_DEBUG Enable debug output 1
CLAUDE_CODE_ENABLE_TELEMETRY Enable telemetry data collection 1
OTEL_METRICS_EXPORTER OpenTelemetry metrics exporter otlpwait

Session and History Variables

Variable name Description Value
CLAUDE_CODE_DISABLE_HISTORY Disable conversation history saving 1
CLAUDE_CODE_SESSION_TIMEOUT Session timeout (seconds) Number
CLAUDE_CODE_MAX_SESSIONS Maximum number of saved sessions Number

MCP-Related Variables

When Claude Code executes MCP tools, the following environment variables are set:

Variable name Description Value
CLAUDE_CODE_MCP_SERVER_NAME MCP server name String
CLAUDE_CODE_MCP_TOOL_NAME MCP tool name being called String
CLAUDE_CODE_MCP_TOOL_ARGS Parameters passed to the MCP tool JSON string

Workflow-Related Variables

Variable name Description Value
CLAUDE_CODE_WORKTREE_CLEANUP_PERIOD_DAYS Auto-cleanup cycle for orphaned worktrees Days
CLAUDE_CODE_DISABLE_WORKTREE_AUTO_CLEANUP Disable worktree auto-cleanup 1

GitHub Actions-Specific Variables

Variable name Description Value
ANTHROPIC_VERTEX_PROJECT_ID Vertex AI project ID (set by authentication step when using Vertex) GCP project ID
CLOUD_ML_REGION Vertex AI region Region code (e.g.,us-east5）

settings.json Configuration Method

All environment variables can be configured insettings.json, which is more declarative and portable:

Example

{
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-4-5",
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-3-5",
    "CLAUDE_CODE_PERMISSION_MODE": "plan",
    "CLAUDE_CODE_ALLOWED_TOOLS": "Read,Grep,Glob,Bash",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

VS Code Plugin Configuration

When using the Claude Code plugin in VS Code, you can configureenvironmentVariablessettings:

Example

{
  "claudeCode.environmentVariables": [
    {
      "name": "ANTHROPIC_BASE_URL",
      "value": "https://custom-proxy.com/api"
    },
    {
      "name": "ANTHROPIC_AUTH_TOKEN",
      "value": "your-token-here"
    },
    {
      "name": "ANTHROPIC_MODEL",
      "value": "claude-sonnet-4-5"
    }
  ]
}

Common Usage Scenarios

Scenario 1: Using a Proxy or Custom API Endpoint

Example

# Access Claude API via enterprise internal proxy
export ANTHROPIC_BASE_URL="https://proxy.company.com/anthropic/v1"
export ANTHROPIC_API_KEY="your-api-key"

Scenario 2: Optimizing Cost Configuration

Example

# Main conversation uses Sonnet, subagents uniformly use Haiku
export ANTHROPIC_MODEL="claude-sonnet-4-5"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-haiku-3-5"

Scenario 3: CI/CD Environment Security Configuration

Example

# Use read-only mode in CI environment
export CLAUDE_CODE_PERMISSION_MODE="plan"
export CLAUDE_CODE_DISABLE_HISTORY="1"
export CLAUDE_CODE_ALLOWED_TOOLS="Read,Grep,Glob,Bash(gh *)"

Scenario 4: Windows PowerShell Environment

Example

# Enable PowerShell on Windows
$env:CLAUDE_CODE_USE_POWERSHELL_TOOL = "1"
# Set defaultShell in settings.json

Priority and Override

Priority of environment variables (from high to low):

  1. Command lineexportSettings
  2. Project level.claude/settings.json
  3. User level~/.claude/settings.json
  4. Claude Code default values

Insettings.jsonVariables configured in will override shell environment variables with the same name. This is because settings.json is explicitly read when the Claude Code process starts, giving it higher priority.

View Current Configuration

Use/configThe command can view the current full configuration:

/config

This will display all currently effective settings, including environment variables and configurations in settings.json.

Best Practices

1. Handling Sensitive Information

  • Sensitive information such as API keys should not be hardcoded in settings.json
  • Use environment variables or shell configuration files (~/.bashrc、~/.zshrc）
  • Ensure files containing sensitive information are not in git version control

2. Configure by Environment

  • Local development: use a more permissive permission mode
  • CI/CD: use read-only modeplan
  • Production debugging: enableCLAUDE_CODE_DEBUG

3. Centralized Management

  • Common configuration goes in~/.claude/settings.json
  • Project-specific configuration goes in the project directory's.claude/settings.json
  • Sensitive configuration is provided via shell environment variables or CI Secrets

FAQ

Q: Which takes precedence, environment variables or settings.json?

Variables configured in settings.json have higher priority and will override shell environment variables with the same name.

Q: How do I make Claude Code use a different API endpoint?

SetANTHROPIC_BASE_URLthe environment variable to point to your proxy or custom endpoint.

Q: How do subagents control which model they use?

You canCLAUDE_CODE_SUBAGENT_MODELset the model for all subagents uniformly, or specify it individually in each subagent's frontmatter.

Q: How do I enable PowerShell on Windows?

Set the environment variableCLAUDE_CODE_USE_POWERSHELL_TOOL=1, and also set it in settings.jsondefaultShell: "powershell"。

Q: How do I disable all slash commands?

SetCLAUDE_CODE_DISABLE_SLASH_COMMANDS=1the environment variable.

Other Extensions