Claude Code: Environment Variables and Dev Configuration
Last updated: 2026-08-31
Environment variables are Claude Code's "control panel" — API keys, model selection, output preferences, all controlled through env vars.
💡 Tip: Environment variables have the highest priority, overriding CLAUDE.md and settings.json. Best for dynamic configuration (API Key, model selection).
📋 Prerequisites: Chapter 21 - Practical: Chrome Extension and Parallel Tasks
1. What You'll Learn
- All environment variables explained
- Dev configuration best practices
- Multi-environment switching
- Debug and diagnostic configuration
- Team configuration management
2. Environment Variables Explained
(1) Core Variables
| Variable | Required | Description | Example |
|---|---|---|---|
ANTHROPIC_API_KEY |
✅ | API key | sk-ant-api03-xxx |
ANTHROPIC_BASE_URL |
❌ | API URL | https://api.deepseek.com |
CLAUDE_MODEL |
❌ | Default model | claude-sonnet-4-20250514 |
(2) Behavior Control Variables
| Variable | Description | Default |
|---|---|---|
CLAUDE_STYLE |
Output style | default |
CLAUDE_LANGUAGE |
Output language | en |
CLAUDE_AUTO_TEST |
Auto-test after modification | false |
CLAUDE_AUTO_COMMIT |
Auto-commit changes | false |
CLAUDE_MAX_TURNS |
Max iteration turns | 50 |
CLAUDE_TIMEOUT |
Operation timeout (seconds) | 300 |
(3) Debug Variables
| Variable | Description | Default |
|---|---|---|
CLAUDE_DEBUG |
Enable debug logging | false |
CLAUDE_HOOK_DEBUG |
Hook debug logging | false |
CLAUDE_LOG_LEVEL |
Log level | info |
CLAUDE_LOG_FILE |
Log file path | - |
3. Dev Configuration Best Practices
(1) Configuration Priority
TEXT
📖 Display only
1. Command line params --model claude-opus-4-20250514
2. Environment variables CLAUDE_MODEL=claude-opus-4-20250514
3. Project .env Variables in .env file
4. Project CLAUDE.md Project-level config
5. Global settings ~/.claude/settings.json
6. Global CLAUDE.md ~/.claude/CLAUDE.md
7. Default values Built-in defaults
(2) .env File Management
BASH
# .env
ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
CLAUDE_MODEL=claude-sonnet-4-20250514
CLAUDE_STYLE=concise
# Ensure .env in .gitignore
echo ".env*" >> .gitignore
▶ Example 1: Using direnv for Auto-Switching
BASH
# project-a/.envrc
export ANTHROPIC_API_KEY="sk-ant-api03-project-a"
export CLAUDE_MODEL="claude-sonnet-4-20250514"
# project-b/.envrc
export ANTHROPIC_API_KEY="sk-deepseek-xxxxx"
export ANTHROPIC_BASE_URL="https://api.deepseek.com"
export CLAUDE_MODEL="deepseek-chat"
# Enter directory → auto-load corresponding config
4. Multi-Environment Management
(1) Environment Matrix
| Environment | API Key | Model | Style | Debug |
|---|---|---|---|---|
| Dev | Dev Key | Sonnet | verbose | on |
| Test | Test Key | Sonnet | default | off |
| CI | CI Key | Sonnet | JSON | off |
| Personal | Personal | Opus | concise | off |
(2) Switching Solutions
BASH
# Shell aliases
alias claude-dev='ANTHROPIC_API_KEY=$DEV_KEY CLAUDE_DEBUG=true claude'
alias claude-ci='ANTHROPIC_API_KEY=$CI_KEY claude --headless --output json'
# direnv (recommended)
# Each project directory auto-loads corresponding .envrc
# Config file
claude --env-file ./configs/production.env
▶ Example 2: Team Shared Configuration
BASH
# .env.example (committed to git, no secrets)
ANTHROPIC_API_KEY=your-api-key-here
CLAUDE_MODEL=claude-sonnet-4-20250514
CLAUDE_STYLE=concise
CLAUDE_AUTO_TEST=true
# Each developer copies and fills in
cp .env.example .env
# Edit .env with personal API Key
5. Debug and Diagnostics
BASH
# Enable full debugging
export CLAUDE_DEBUG=true
export CLAUDE_LOG_LEVEL=debug
export CLAUDE_HOOK_DEBUG=1
export CLAUDE_LOG_FILE=/tmp/claude-debug.log
# Run Claude Code
claude "test task"
# View logs
tail -f /tmp/claude-debug.log
6. Comprehensive Example: Complete Dev Configuration
BASH
# ~/.zshrc (global config)
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"
export CLAUDE_MODEL="claude-sonnet-4-20250514"
export CLAUDE_STYLE="concise"
export CLAUDE_AUTO_TEST="true"
# Project .envrc
export CLAUDE_MODEL="claude-opus-4-20250514" # This project uses Opus
export CLAUDE_MAX_TURNS="30"
# ~/.claude/settings.json
{
"output": { "showDiff": true, "autoTest": true },
"permissions": { "autoApprove": ["Read", "Write"] }
}
❓ FAQ
Q Environment variable vs CLAUDE.md priority?
A Environment variables win. CLAUDE.md for preferences/conventions; env vars for runtime config (like API Key).
Q Is API Key in .env safe?
A For local dev yes, but ensure
.env is in .gitignore. Use Secrets for CI.Q What value for
CLAUDE_MAX_TURNS?A 20-30 for daily use. 50 for complex tasks. Too small may stop tasks prematurely.
Q How to verify env vars are working?
A Run
/config in Claude Code, or echo $ANTHROPIC_API_KEY.📖 Summary
- Core env vars:
ANTHROPIC_API_KEY,CLAUDE_MODEL,CLAUDE_STYLE - Priority: CLI > env vars > .env > CLAUDE.md > settings
- direnv for directory-level auto config switching
.env.examplein git,.envin .gitignore- Debug vars only enable when troubleshooting
📝 Exercises
- Basic (⭐): Configure
CLAUDE_STYLEandCLAUDE_LANGUAGE, verify output changes. - Intermediate (⭐⭐): Use direnv for two projects with different API Key and model, verify auto-switching.
- Advanced (⭐⭐⭐): Design team-level environment config covering dev/test/CI with secret security.
