Zero to Agent

Português

中文
English
Español
Français
हिन्दी
العربية
Русский

Português

中文
English
Español
Français
हिन्दी
العربية
Русский

Variáveis de Ambiente: Painel de Controle de Sistema ​

📚 Navegação da Série: O capítulo anterior 41 Tarefas Paralelas ensinou a isolar tarefas concorrentes para que múltiplos Claudes pudessem trabalhar em paralelo. Este capítulo aborda as definições de infraestrutura — as variáveis de ambiente gerenciam como o Claude Code se conecta aos modelos de IA, os tempos limites (timeouts) de rede e as regras de envio de dados. Essas opções não estão em menus visuais, mas sim configuradas no shell e nos arquivos settings.json. Vamos detalhar o funcionamento de cada uma.

Dizem por aí que variáveis de ambiente são "apenas para usuários avançados". Sinceramente, essa afirmação acabou confundindo muita gente.

Muitos desenvolvedores configuram modelos de IA, rotas de proxy ou tempos limites repetindo comandos interativos como /model a cada nova sessão, tendo que refazer as configurações no terminal no dia seguinte. O principal motivo para não automatizar essas configurações costuma ser a percepção de que a manipulação de variáveis de ambiente é complexa e pode quebrar a CLI.

No entanto, nos capítulos anteriores — na configuração da API key (Capítulo 4), integração com modelos locais (Capítulo 5), gestão de limites de contexto (Capítulo 19) e desligamento de telemetria (Capítulo 21) — toda a base técnica baseou-se na leitura e gravação de variáveis de ambiente. Você já utiliza esse mecanismo no seu dia a dia, mesmo sem um guia de referência completo de suas opções.

Variáveis de ambiente funcionam como um painel de configurações salvas para uso contínuo. Entender quais variáveis são mais comuns e como configurá-las sem riscos otimiza o tempo de uso da CLI.

Ao ler este capítulo, você obterá:

  • O conceito das variáveis de ambiente no Claude Code e por que configurá-las.
  • Um comparativo das três formas de definição (temporária no shell, persistente no arquivo de perfil do shell e via bloco env no settings.json) para escolher a mais adequada.
  • A diferenciação dos escopos de aplicação dos quatro tipos de arquivos settings.json (quais devem ser comitados no Git e quais contêm segredos locais).
  • Uma lista de variáveis recomendadas agrupadas por utilidade: chaves de autenticação, limites de tempo de rede, telemetria e caminhos de diretórios locais.
  • As regras de prioridade e precedência de leitura de configurações do sistema (o que prevalece quando o mesmo parâmetro é configurado em locais diferentes).
  • Um teste prático para definir uma variável temporária e validar sua leitura pela CLI do Claude Code.

01 O Papel das Variáveis de Ambiente no Claude Code ​

Variáveis de ambiente são pares de chave e valor lidos no momento em que o Claude Code é inicializado, definindo configurações de rede, credenciais de autenticação, limites de requisições e comportamentos do sistema.

Enquanto comandos como /model, claude mcp add ou /config ajustam parâmetros da sessão ativa no terminal, as variáveis de ambiente determinam diretrizes persistentes aplicadas em todas as inicializações do sistema. Por exemplo: definir o proxy padrão de rede, configurar o tempo limite das chamadas para 20 minutos ou garantir o bloqueio do envio de dados de telemetria de forma definitiva.

A documentação oficial define a utilidade desse recurso:

Variáveis de ambiente permitem ajustar o comportamento interno do Claude Code, abrangendo a seleção do modelo de IA, caminhos de autenticação, redirecionamentos de rede e ativação de recursos da CLI.

Analogia: Perfis de cafeteira inteligente. Você pode configurar a cafeteira manualmente a cada xícara — escolhendo o volume de água, intensidade do grão e temperatura da bebida. Contudo, você também pode salvar um perfil personalizado com as opções desejadas. Ao acionar esse perfil, a cafeteira aplica as configurações automaticamente. As variáveis de ambiente funcionam como esse perfil salvo: elas consolidam as regras de execução do Claude Code para que a CLI as aplique na inicialização do sistema, evitando digitações repetidas de parâmetros.

Cenários práticos em que o uso de variáveis é recomendado:

  • Uso de modelos locais (como DeepSeek): define o modelo e a URL base de forma definitiva, eliminando a configuração interativa na inicialização (conforme Capítulo 5).
  • Conexões com instabilidade de rede: permite estender o tempo limite de chamadas (timeout) padrão de 10 minutos para evitar falhas de execução.
  • Políticas de conformidade empresarial: garante o desligamento global do envio de dados de telemetria no terminal da máquina (Capítulo 21).
  • Gestão de múltiplas contas de usuário: permite alternar a pasta física de logs e históricos da CLI conforme o perfil em uso.

Variáveis de ambiente organizam regras que devem ser configuradas uma única vez e aplicadas de forma contínua em todo o sistema.

💡 Resumo em uma frase: Variáveis de ambiente configuram parâmetros de inicialização do Claude Code (autenticação, endpoints, limites de tempo e telemetria), definindo regras permanentes que evitam a repetição de configurações no terminal.

02 Três Formas de Configuração: Do Uso Temporário à Persistência ​

As variáveis podem ser configuradas em três locais diferentes. A escolha do local determina o tempo de validade da configuração e seu escopo de alcance.

A documentação diferencia os escopos de forma direta:

Variáveis configuradas diretamente no terminal (shell) são válidas apenas para a sessão ativa daquele console, enquanto definições inseridas nos arquivos de configuração aplicam-se a todas as execuções do comando claude.

Comparativo das três formas de definição por escopo:

Opção 1: Temporária via Terminal (Shell Export) ​

Defina a variável no terminal antes de chamar a CLI. A configuração expira ao fechar a janela do terminal ativa.

No macOS, Linux ou WSL:

bash
export API_TIMEOUT_MS="1200000"
claude

No Windows PowerShell:

powershell
$env:API_TIMEOUT_MS = "1200000"
claude

Use esta opção para validações rápidas — como testar um tempo limite estendido de forma pontual ou alternar um endereço de proxy sem persistir a alteração no sistema.

Opção 2: Persistente via Perfil do Shell (Configuração da Máquina) ​

Para aplicar a configuração em todas as janelas de terminal abertas no sistema, insira o comando export no arquivo de perfil do seu shell local. No macOS (com Zsh), o arquivo padrão é ~/.zshrc; no Linux (com Bash), costuma ser ~/.bashrc:

bash
# Adicionar ao final do arquivo ~/.zshrc
export API_TIMEOUT_MS="1200000"

Após salvar, execute source ~/.zshrc no terminal ativo ou abra uma nova janela para ler a alteração. Esta opção define parâmetros globais da máquina aplicados a todos os projetos abertos no sistema.

Para persistir variáveis no terminal do Windows, utilize o comando setx API_TIMEOUT_MS "1200000" no Prompt de Comando (CMD) ou run [Environment]::SetEnvironmentVariable("API_TIMEOUT_MS", "1200000", "User") no PowerShell, abrindo um novo terminal após a gravação para aplicar.

Opção 3: Persistente via Bloco env no settings.json (Configuração de Projeto) ​

Esta é a abordagem recomendada para vincular configurações a perfis de projeto. A CLI lê as informações no momento da inicialização:

O Claude Code acessa as configurações diretamente dos arquivos JSON locais, aplicando as regras independentemente de como a CLI foi acionada.

json
{
  "env": {
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

A estrutura do settings.json foi detalhada no Capítulo 31. O campo env funciona como um dicionário específico para armazenar variáveis de ambiente locais do projeto ou usuário.

Comparativo das opções de configuração:

MétodoValidade no SistemaPersistência após fechar o terminalCenário Recomendado
Export no terminalApenas na aba ativa.NãoTestes pontuais e diagnósticos.
Perfil do shell (.zshrc)Global do usuário no sistema operacional.SimConfigurações de hardware locais da máquina.
Bloco env no JSONConforme o escopo do arquivo settings.json.SimConfigurações do projeto compartilhadas com a equipe.

Prática recomendada: use o export no terminal para testar o comportamento de uma nova variável; uma vez validado, salve a configuração no bloco env do settings.json adequado. O JSON permite segmentar a aplicação da variável (apenas para você, para a equipe ou em um projeto específico), flexibilidade que não é possível ao configurar perfis globais do shell da máquina.

💡 Resumo em uma frase: Variáveis podem ser configuradas de forma temporária no terminal (via export), permanente no perfil do sistema operacional (como .zshrc) ou no bloco env do settings.json (focado no escopo do projeto).

03 Escopos do settings.json: Compartilhamento vs. Privacidade ​

O bloco settings.json pode ser gravado em quatro diretórios diferentes, determinando o escopo de leitura da variável (Capítulo 31).

Atenção especial ao escopo de compartilhamento: salvar chaves de acesso pessoais ou URLs de proxies privados em arquivos do settings.json que são versionados no Git disponibilizará esses dados confidenciais para toda a equipe ou em repositórios públicos.

Analogia: Quadro de avisos da recepção vs. Bloco de notas pessoal. Um informativo sobre as políticas da empresa colado na parede da recepção é visível a todos os funcionários e visitantes — esse é o arquivo comitado no Git. Já um rascunho de senhas no seu bloco de notas pessoal fica guardado na sua gaveta, acessível apenas por você — esse é o arquivo local não versionado. A escolha do arquivo determina se a informação é compartilhada com o grupo ou mantida sob seu controle exclusivo.

Diretórios de escopo do settings.json e suas aplicações:

Arquivo de ConfiguraçãoEscopo de LeituraRelação com Versionamento (Git)
~/.claude/settings.jsonAplicado a todas as pastas de projeto do seu usuário local.Não versionado (salvo na pasta Home pessoal).
.claude/settings.jsonAplicado a todos os usuários que baixarem a pasta do projeto.Versionado no Git (comitado no repositório).
.claude/settings.local.jsonAplicado apenas à sua máquina física dentro da pasta do projeto.Não versionado (ignorado pelo Git local).
Configurações corporativasAplicadas a todos os computadores gerenciados pela equipe de TI da empresa.Gerenciado centralmente por administradores de sistema.

Regra de segurança: credenciais de acesso, caminhos de diretórios locais e tokens pessoais devem ser salvos no arquivo .claude/settings.local.json do projeto ou na pasta Home (~/.claude/settings.json). Use o arquivo .claude/settings.json da raiz apenas para regras corporativas e padrões de projeto que devem ser compartilhados com o time de engenharia.

Tipo da VariávelArquivo Adequado para Gravação
Parâmetros pessoais e preferências do usuário em todos os repositórios.~/.claude/settings.json (Pasta Home)
Padrões de desenvolvimento globais da equipe de engenharia..claude/settings.json (Raiz do projeto - Git)
Configurações de API específicas do projeto que utilizam chaves privadas..claude/settings.local.json (Raiz do projeto - Local)

💡 Resumo em uma frase: O arquivo settings.json divide-se em níveis de escopo (global do usuário, compartilhado no Git e local do projeto); mantenha segredos e credenciais de acesso em arquivos locais não rastreados pelo Git (.local.json).

04 Variáveis Recomendadas por Categoria ​

Abaixo constam as principais variáveis utilizadas no dia a dia com a CLI, divididas por funcionalidade:

1. Conexão e Modelos de IA ​

Configuram a autenticação com servidores de IA e endpoints customizados (conforme Capítulos 4 e 5):

  • ANTHROPIC_API_KEY: Chave de autenticação da conta Anthropic. Nota: configurar esta variável fará com que o Claude Code utilize o faturamento via API, ignorando a assinatura ativa da conta (Pro/Max) no terminal. Para reverter o comportamento e usar a cota da assinatura, remova a chave executando unset ANTHROPIC_API_KEY.
  • ANTHROPIC_BASE_URL: Endpoint de redirecionamento de chamadas. Utilizado para conectar a proxies locais, gateways corporativos ou servidores de modelos locais.
  • ANTHROPIC_MODEL: Define o modelo de IA padrão inicializado nas sessões. Pode ser sobrescrito pelo comando /model ou parâmetro --model no terminal.

2. Padrões de Tempos Limites (Timeouts) ​

Evitam erros de rede causados por instabilidades ou proxies corporativos:

VariávelFunçãoPadrão do Sistema
API_TIMEOUT_MSTempo limite para obter resposta da API do modelo (em milissegundos).600000 (10 minutos)
BASH_DEFAULT_TIMEOUT_MSTempo limite padrão de execução de comandos Bash no terminal.120000 (2 minutos)

Dica de configuração: Não atribua valores excessivamente altos à variável API_TIMEOUT_MS (como acima de 2147483647), pois isso causará estouro de inteiros nos scripts internos da CLI, gerando erros imediatos em todas as chamadas.

3. Telemetria e Privacidade ​

Desativam o envio automático de dados de telemetria da CLI (Capítulo 21):

  • DISABLE_TELEMETRY=1: Desativa o envio de dados analíticos de comportamento de uso. A documentação oficial detalha que a telemetria não coleta códigos, caminhos físicos ou comandos executados.
  • DO_NOT_TRACK=1: Segue a convenção de privacidade comum de ferramentas de terminal. Ativar esta variável equivale a marcar DISABLE_TELEMETRY=1.

O parâmetro CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 desativa de forma unificada as checagens de atualizações automáticas, formulários de feedback, relatórios de erros de execução e estatísticas de telemetria, otimizando a CLI para ambientes isolados sem acesso direto à internet.

4. Gestão de Contas e Contexto ​

Ajustes avançados de pastas e limites locais:

  • CLAUDE_CONFIG_DIR: Redireciona a pasta física onde a CLI armazena dados de sessões, MCP e históricos (por padrão, ~/.claude). Útil para gerenciar contas corporativas e pessoais na mesma máquina física:
bash
# Atalho no shell para carregar as configurações corporativas de forma isolada
alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'
  • DISABLE_AUTO_COMPACT=1: Desativa a compressão automatizada de contexto quando a sessão atinge o limite de tokens da IA (Capítulo 19). A compressão continuará ativa apenas de forma manual pelo comando /compact.

Nota de inicialização: O Claude Code lê as variáveis de ambiente apenas na inicialização. Se você modificar uma variável de ambiente ou arquivo JSON, será necessário reiniciar a sessão ativa (/exit) para aplicar a nova configuração.

💡 Resumo em uma frase: As variáveis essenciais cobrem chaves de acesso, endpoints, timeouts, privacidade e pastas de dados; alterações exigem fechar e reiniciar a CLI do Claude Code para que a leitura seja realizada.

05 Regras de Prioridade e Precedência de Leitura ​

Caso o mesmo parâmetro (como o modelo de IA) esteja configurado em diferentes locais, o Claude Code aplica a seguinte prioridade de leitura:

A documentação oficial define a regra geral de precedência:

Havendo duplicidade de parâmetros entre variáveis de ambiente e campos JSON do arquivo settings, a variável de ambiente terá prioridade de leitura. Exemplo: ANTHROPIC_MODEL sobrepõe o campo model do arquivo settings.

No entanto, para garantir o controle das sessões de chat, as escolhas diretas do terminal pelo desenvolvedor têm precedência sobre os parâmetros do sistema:

Os parâmetros --model e comandos /model sobrepõem as diretrizes da variável ANTHROPIC_MODEL.

A ordem de precedência decrescente para configurações de modelo de IA é definida como:

text
Atalho de terminal (--model) / Comando no chat (/model)  [Prioridade Máxima]
                           ↓
Variável de Ambiente no terminal (ANTHROPIC_MODEL)
                           ↓
Campo model no arquivo settings.json                      [Prioridade Mínima]

Ordem de prioridade de configuração:

Método de ConfiguraçãoNível de PrioridadeJustificativa
Comando interativo no terminal/chatMáximoDefine a intenção do desenvolvedor para a sessão ativa.
Variável de AmbienteMédioConfiguração do usuário na máquina.
Campo JSON do settings.jsonMínimoConfiguração padrão do repositório/projeto.

Essa hierarquia permite que você mantenha padrões globais configurados no JSON do projeto e alterne temporariamente o modelo na sessão ativa via /model sem precisar editar arquivos de configuração do sistema.

💡 Resumo em uma frase: As opções digitadas no terminal (/model) têm prioridade máxima sobre as variáveis de ambiente do sistema, que por sua vez se sobrepõem às configurações padrões salvas nos arquivos settings.json.

06 Prática: Validando a Leitura de Variáveis de Ambiente ​

Realizaremos um teste básico configurando a variável BASH_DEFAULT_TIMEOUT_MS (tempo limite de comandos Bash) no terminal para validar sua leitura pelo Claude Code.

Requisitos: Claude Code instalado e operacional.

Passo 1: Verificar o comportamento padrão inicial

Abra uma sessão padrão da CLI no seu console:

bash
claude

Na janela de chat, consulte o valor lido pela IA:

text
Qual e o tempo limite em milissegundos da variavel BASH_DEFAULT_TIMEOUT_MS ativa nesta sessao? Se nao constar valor no sistema, indique o padrao.

Resultado esperado: O Claude informa que a variável não está definida explicitamente no ambiente, adotando o tempo padrão do sistema de 120000 (2 minutos). Encerre a sessão digitando /exit.

Passo 2: Configurar a variável no terminal

Defina o tempo limite para 5 minutos (300000 milissegundos) no seu console antes de inicializar a CLI:

No macOS/Linux:

bash
export BASH_DEFAULT_TIMEOUT_MS="300000"
claude

No Windows (PowerShell):

powershell
$env:BASH_DEFAULT_TIMEOUT_MS = "300000"
claude

Passo 3: Confirmar a leitura da variável modificada

Envie a mesma pergunta no chat:

text
Qual e o tempo limite em milissegundos da variavel BASH_DEFAULT_TIMEOUT_MS ativa nesta sessao?

Resultado esperado: O Claude identifica o valor alterado no ambiente do terminal e informa o tempo limite de 300000 milissegundos (5 minutos), confirmando que a alteração de escopo temporário foi aplicada com sucesso. Encerre a sessão.

Passo 4: Validar a expiração temporária

Abra uma nova aba do terminal do seu sistema operacional (ou reinicie o terminal), digite claude (sem definir variáveis de exportação) e repita a consulta.

Resultado esperado: O valor retorna para o tempo limite padrão de 120000 milissegundos, confirmando que a definição temporária via terminal expira ao fechar a janela de execução.

Esta validação comprova o ciclo de leitura das variáveis. Se desejar persistir a configuração para todas as sessões do projeto, salve o parâmetro no arquivo .claude/settings.local.json sob a chave env.

💡 Resumo em uma frase: O teste prático comprova a hierarquia de leitura configurando a variável no terminal, validando a atualização do tempo limite no chat e confirmando que o valor retorna ao padrão após fechar a sessão.

07 Resumo ​

As variáveis de ambiente controlam as definições do sistema no Claude Code, permitindo ajustar a conexão com provedores de IA, timeouts de rede e políticas de compartilhamento de dados de forma persistente.

Conceitos centrais revisados neste capítulo:

TópicoDetalhe
EscopoDividido em variáveis temporárias (terminal), persistentes do usuário (~/.zshrc) ou de projetos (JSON).
SegurançaCredenciais, tokens e chaves privadas de APIs devem ser mantidos em arquivos locais não compartilhados no Git (.local.json).
AutenticaçãoA variável ANTHROPIC_API_KEY altera o tráfego da CLI para faturamento via API, ignorando assinaturas de conta Pro/Max ativas.
TimeoutsAjuste API_TIMEOUT_MS e BASH_DEFAULT_TIMEOUT_MS para evitar quebras por lentidão ou proxies corporativos.
HierarquiaO terminal interativo (/model) tem prioridade máxima, seguido pelas variáveis do sistema e, por último, os campos JSON.

Compreender o papel destas variáveis simplifica a automação e otimiza a integração do Claude Code no seu ambiente local de desenvolvimento.

O próximo capítulo, 43 "Fluxo de Trabalho Git", ensinará a integrar o Claude Code no controle de versão do projeto. Veremos como configurar o agente para redigir mensagens de commit, analisar alterações parciais de código, criar branches e interagir com repositórios Git de forma segura. Nos vemos no próximo capítulo!

Leituras Recomendadas ​