Claude Code: Variáveis de Ambiente e Configuração de Dev
Última atualização: 2026-08-31
Variáveis de ambiente são o "painel de controle" do Claude Code — API keys, seleção de modelo, preferências de saída, tudo controlado por env vars.
💡 Dica: Variáveis de ambiente têm a maior prioridade, sobrepõem CLAUDE.md e settings.json. Melhor para configuração dinâmica (API Key, seleção de modelo).
📋 Pré-requisitos: Capítulo 21 - Prática: Extensão Chrome e Tarefas Paralelas
1. O Que Você Vai Aprender
- Todas as variáveis de ambiente explicadas
- Melhores práticas de configuração dev
- Alternância multi-ambiente
- Configuração de debug e diagnóstico
- Gerenciamento de configuração de equipe
2. Variáveis de Ambiente Explicadas
(1) Variáveis Centrais
| Variável | Obrigatória | Descrição | Exemplo |
|---|---|---|---|
ANTHROPIC_API_KEY |
✅ | API key | sk-ant-api03-xxx |
ANTHROPIC_BASE_URL |
❌ | API URL | https://api.deepseek.com |
CLAUDE_MODEL |
❌ | Modelo padrão | claude-sonnet-4-20250514 |
(2) Variáveis de Controle de Comportamento
| Variável | Descrição | Padrão |
|---|---|---|
CLAUDE_STYLE |
Estilo de saída | default |
CLAUDE_LANGUAGE |
Idioma de saída | en |
CLAUDE_AUTO_TEST |
Auto-teste após modificação | false |
CLAUDE_AUTO_COMMIT |
Auto-commit de mudanças | false |
CLAUDE_MAX_TURNS |
Máximo de rodadas de iteração | 50 |
CLAUDE_TIMEOUT |
Timeout de operação (segundos) | 300 |
(3) Variáveis de Debug
| Variável | Descrição | Padrão |
|---|---|---|
CLAUDE_DEBUG |
Habilitar log de debug | false |
CLAUDE_HOOK_DEBUG |
Log de debug de hooks | false |
CLAUDE_LOG_LEVEL |
Nível de log | info |
CLAUDE_LOG_FILE |
Caminho do arquivo de log | - |
3. Melhores Práticas de Configuração Dev
(1) Prioridade de Configuração
TEXT
📖 Somente leitura
1. Parâmetros de linha de comando --model claude-opus-4-20250514
2. Variáveis de ambiente CLAUDE_MODEL=claude-opus-4-20250514
3. .env do projeto Variáveis no arquivo .env
4. CLAUDE.md do projeto Config em nível de projeto
5. Configurações globais ~/.claude/settings.json
6. CLAUDE.md global ~/.claude/CLAUDE.md
7. Valores padrão Defaults integrados
(2) Gerenciamento de Arquivo .env
BASH
# .env
ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
CLAUDE_MODEL=claude-sonnet-4-20250514
CLAUDE_STYLE=concise
# Garantir .env no .gitignore
echo ".env*" >> .gitignore
▶ Exemplo 1: Usar direnv para Auto-Alternação
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"
# Entrar no diretório → auto-carregar config correspondente
4. Gerenciamento Multi-Ambiente
(1) Matriz de Ambientes
| Ambiente | API Key | Modelo | Estilo | Debug |
|---|---|---|---|---|
| Dev | Dev Key | Sonnet | verbose | on |
| Test | Test Key | Sonnet | default | off |
| CI | CI Key | Sonnet | JSON | off |
| Pessoal | Pessoal | Opus | concise | off |
(2) Soluções de Alternância
BASH
# Aliases do shell
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 (recomendado)
# Cada diretório de projeto auto-carrega .envrc correspondente
# Arquivo de config
claude --env-file ./configs/production.env
▶ Exemplo 2: Config Compartilhada de Equipe
BASH
# .env.example (commitado no git, sem secrets)
ANTHROPIC_API_KEY=your-api-key-here
CLAUDE_MODEL=claude-sonnet-4-20250514
CLAUDE_STYLE=concise
CLAUDE_AUTO_TEST=true
# Cada desenvolvedor copia e preenche
cp .env.example .env
# Editar .env com API Key pessoal
5. Debug e Diagnóstico
BASH
# Habilitar debug completo
export CLAUDE_DEBUG=true
export CLAUDE_LOG_LEVEL=debug
export CLAUDE_HOOK_DEBUG=1
export CLAUDE_LOG_FILE=/tmp/claude-debug.log
# Executar Claude Code
claude "test task"
# Ver logs
tail -f /tmp/claude-debug.log
6. Exemplo Completo: Config Dev Completa
BASH
# ~/.zshrc (config global)
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"
export CLAUDE_MODEL="claude-sonnet-4-20250514"
export CLAUDE_STYLE="concise"
export CLAUDE_AUTO_TEST="true"
# .envrc do projeto
export CLAUDE_MODEL="claude-opus-4-20250514" # Este projeto usa Opus
export CLAUDE_MAX_TURNS="30"
# ~/.claude/settings.json
{
"output": { "showDiff": true, "autoTest": true },
"permissions": { "autoApprove": ["Read", "Write"] }
}
❓ Perguntas Frequentes
P: Prioridade variável de ambiente vs CLAUDE.md? R: Variáveis de ambiente vencem. CLAUDE.md para preferências/convenções; env vars para config de runtime (como API Key).
P: API Key em .env é seguro? R: Para dev local sim, mas garanta que
.envestá no.gitignore. Use Secrets para CI.
P: Qual valor para
CLAUDE_MAX_TURNS? R: 20-30 para uso diário. 50 para tarefas complexas. Muito pequeno pode parar tarefas prematuramente.
P: Como verificar se env vars estão funcionando? R: Execute
/configno Claude Code, ouecho $ANTHROPIC_API_KEY.
📖 Resumo
- Env vars centrais:
ANTHROPIC_API_KEY,CLAUDE_MODEL,CLAUDE_STYLE - Prioridade: CLI > env vars > .env > CLAUDE.md > settings
- direnv para auto-troca de config em nível de diretório
.env.exampleno git,.envno .gitignore- Variáveis de debug apenas habilitar quando solucionando problemas
📝 Exercícios
- Básico (⭐): Configure
CLAUDE_STYLEeCLAUDE_LANGUAGE, verifique mudanças na saída. - Intermediário (⭐⭐): Use direnv para dois projetos com API Key e modelo diferentes, verifique auto-alternação.
- Avançado (⭐⭐⭐): Desenhe config de ambiente em nível de equipe cobrindo dev/teste/CI com segurança de secrets.
