YouTipClaude Code Env
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 shell via `export`
* In the `env` field of `~/.claude/settings.json`
* In the project-level `.claude/settings.json`
* Through the IDE plugin's settings interface
> Environment variable priority from high to low: 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 Variables
| Variable Name | Description | Value |
| --- | --- | --- |
| `ANTHROPIC_API_KEY` | Claude API key (obtained from claude.ai) | API key string |
| `ANTHROPIC_BASE_URL` | Target URL for API requests (used for proxies or custom endpoints) | URL address |
| `ANTHROPIC_AUTH_TOKEN` | Authentication token (used for VS Code plugin and similar scenarios) | Token string |
### Configuration Examples
## Example
# Set in 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 to use | `claude-opus-4-5`, `claude-sonnet-4-5`, `claude-haiku-3-5`, etc. |
| `ANTHROPIC_SMALL_FAST_MODEL` | Model used for fast response mode (for simple tasks) | Model name |
| `CLAUDE_CODE_SUBAGENT_MODEL` | Uniformly set the model for all subagents | Model name |
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Disable experimental features when using Anthropic Messages format with Bedrock or Vertex | `1` |
### Usage Scenarios
Subagents inherit the main conversation's model by default. Through `CLAUDE_CODE_SUBAGENT_MODEL`, you can uniformly set models, delegating simple tasks to Haiku and complex analysis to Sonnet, thereby optimizing 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 built-in Git-related system prompts (higher priority than `includeGitInstructions` in settings.json) | `1` |
| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | Enable PowerShell tool on Windows (requires `defaultShell: "powershell"` setting) | `1` |
| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Skip automatic IDE extension installation (replaces `autoInstallIdeExtension` setting) | `1` |
| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Disable background task functionality | `1` |
* * *
## Permission and Security Variables
| Variable Name | Description | Value |
| --- | --- | --- |
| `CLAUDE_CODE_PERMISSION_MODE` | Set default permission mode (see subagent chapter 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 Mode Details
* `default`: Normal permission prompts, 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 Debug 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 | `otlp`, etc. |
* * *
## 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` | Name of the MCP tool being called | String |
| `CLAUDE_CODE_MCP_TOOL_ARGS` | Arguments passed to the MCP tool | JSON string |
* * *
## Workflow Related Variables
| Variable Name | Description | Value |
| --- | --- | --- |
| `CLAUDE_CODE_WORKTREE_CLEANUP_PERIOD_DAYS` | Automatic cleanup period for orphaned worktrees | Days |
| `CLAUDE_CODE_DISABLE_WORKTREE_AUTO_CLEANUP` | Disable automatic worktree 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 in `settings.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 configure via the `environmentVariables` setting:
## 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 through enterprise internal proxy
export ANTHROPIC_BASE_URL="https://proxy.company.com/anthropic/v1"
export ANTHROPIC_API_KEY="your-api-key"
### Scenario 2: Cost Optimization 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
Environment variable priority (from high to low):
1. Command line `export` settings
2. Project-level `.claude/settings.json`
3. User-level `~/.claude/settings.json`
4. Claude Code defaults
> Variables configured in `settings.json` 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.
* * *
## Viewing Current Configuration
Use the `/config` command to view the current complete configuration:
/config
This will display all currently effective settings, including environment variables and configurations in settings.json.
* * *
## Best Practices
### 1. Sensitive Information Handling
* Do not hardcode API keys and other sensitive information in settings.json
* Use environment variables or shell configuration files (`~/.bashrc`, `~/.zshrc`)
* Ensure files containing sensitive information are not in git version control
### 2. Environment-Based Configuration
* Local development: Use more permissive permission modes
* CI/CD: Use read-only mode `plan`
* Production debugging: Enable `CLAUDE_CODE_DEBUG`
### 3. Centralized Management
* General configurations go in `~/.claude/settings.json`
* Project-specific configurations go in the project's `.claude/settings.json`
* Sensitive configurations provided via shell environment variables or CI Secrets
* * *
## Frequently Asked Questions
**Q: Which takes priority, 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?**
Set the `ANTHROPIC_BASE_URL` environment variable to point to your proxy or custom endpoint.
**Q: How do I control which model subagents use?**
You can uniformly set the model for all subagents via `CLAUDE_CODE_SUBAGENT_MODEL`, or specify individually in each subagent's frontmatter.
**Q: How do I enable PowerShell on Windows?**
Set the environment variable `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`, and also set `defaultShell: "powershell"` in settings.json.
**Q: How do I disable all slash commands?**
Set the environment variable `CLAUDE_CODE_DISABLE_SLASH_COMMANDS=1`.