Skip to main content
Claude Code suporta várias configurações de rede e segurança empresariais através de variáveis de ambiente. Isso inclui rotear o tráfego através de servidores proxy corporativos, confiar em Autoridades de Certificação (CA) personalizadas e autenticar com certificados de Transport Layer Security (mTLS) mútuo para segurança aprimorada. Defina essas variáveis de ambiente antes de iniciar Claude Code. As variáveis exportadas no seu shell são lidas uma vez na inicialização, portanto uma sessão em execução não detecta alterações posteriores no seu ambiente de shell.
Todas as variáveis de ambiente mostradas nesta página também podem ser configuradas em settings.json.

​
Configuração de proxy

​
Variáveis de ambiente

Claude Code respeita variáveis de ambiente de proxy padrão. Em sessões do Claude Desktop onde o aplicativo gerencia a conexão do provedor, Claude Code as lê apenas de configurações gerenciadas e ~/.claude/settings.json; consulte autenticação mTLS para as regras de escopo.
Variantes em minúsculas também funcionam, e Claude Code usa a primeira que está definida na ordem https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY. Claude Code nunca envia suas conexões WebSocket para localhost, ::1 ou 127.0.0.0/8 através do proxy, portanto você não precisa de uma entrada de loopback em NO_PROXY para elas.
Claude Code não suporta proxies SOCKS.

​
Autenticação básica

Se seu proxy exigir autenticação básica, inclua credenciais na URL do proxy:
Evite codificar senhas em scripts. Use variáveis de ambiente ou armazenamento seguro de credenciais.
Para proxies que exigem autenticação avançada (NTLM, Kerberos, etc.), considere usar um serviço LLM Gateway que suporte seu método de autenticação.

​
Armazenamento de certificados CA

Por padrão, Claude Code confia tanto em seus certificados CA Mozilla agrupados quanto no armazenamento de certificados do seu sistema operacional. Ler o armazenamento do SO requer um runtime com tls.getCACertificates: o instalador nativo sempre possui, e instalações npm precisam do Node 22.15 ou posterior. Em versões mais antigas do Node, apenas o conjunto agrupado e NODE_EXTRA_CA_CERTS se aplicam. Proxies de inspeção TLS empresariais funcionam sem configuração adicional quando seu certificado raiz é instalado no armazenamento de confiança do SO e o runtime pode lê-lo. CLAUDE_CODE_CERT_STORE aceita uma lista separada por vírgulas de fontes. Os valores reconhecidos são bundled para o conjunto de CA Mozilla enviado com Claude Code e system para o armazenamento de confiança do sistema operacional. O padrão é bundled,system. Para confiar apenas no conjunto de CA Mozilla agrupado:
Para confiar apenas no armazenamento de certificados do SO:
CLAUDE_CODE_CERT_STORE não possui uma chave de esquema dedicada em settings.json. Defina-a através do bloco env em ~/.claude/settings.json ou diretamente no ambiente do processo.

​
Certificados CA personalizados

Se seu ambiente empresarial usa uma CA personalizada, configure Claude Code para confiar nela diretamente:

​
Autenticação mTLS

Para ambientes corporativos que exigem autenticação por certificado de cliente:
Claude Code lê os arquivos de certificado e chave na inicialização e os relê cada vez que aplica configurações, como quando sua organização altera o bloco env em configurações gerenciadas no meio da sessão. Para rotacionar o certificado e a chave, substitua os arquivos nos mesmos caminhos. Claude Code detecta a substituição em uma sessão em execução sem necessidade de reinicialização. Quando uma solicitação de API falha com um erro no nível de conexão, como uma redefinição de conexão ou um erro de handshake TLS, ele relê ambos os arquivos e tenta novamente a solicitação com o novo par. Antes da v2.1.232, Claude Code não relinha em erros de conexão, portanto mantinha o par que já havia carregado até aplicar configurações novamente ou você reiniciar. Claude Code relê os arquivos em resposta a solicitações com falha, não observando-os para detectar alterações:
  • Tempo: Claude Code não faz nada no momento em que você substitui os arquivos. Ele apresenta o novo par na tentativa após uma falha qualificada, ou na próxima solicitação após aplicar configurações, o que vier primeiro.
  • Rejeições de gateway: Claude Code relê quando seu gateway redefine a conexão ou rejeita o handshake TLS depois de parar de aceitar o par antigo. Ele não relê quando o gateway conclui o handshake e responde com um erro HTTP. Nesse caso, Claude Code carrega o novo par quando aplica configurações novamente ou quando você o reinicia.
  • Rotações parcialmente gravadas: quando Claude Code relê enquanto sua rotação está no meio da gravação, como ler um certificado e chave que não correspondem um ao outro, ele mantém o par anterior e relê na próxima falha.
  • Exportadores de telemetria OTLP: Claude Code mantém o certificado que os exportadores carregaram no primeiro uso, portanto reinicie Claude Code para que um certificado rotacionado alcance seu coletor de telemetria.
  • Desativar o recarregamento: defina CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION=1 para desativar a releitura de erro de conexão. Claude Code então detecta arquivos rotacionados apenas quando aplica configurações novamente ou na próxima inicialização.
Para confirmar que Claude Code detectou uma rotação, inicie a sessão com registro de depuração e procure por Stale connection — reloaded rotated mTLS client material no log. Claude Code não registra essa linha quando detecta a rotação ao aplicar configurações, portanto uma linha ausente sozinha não significa que a rotação falhou. Substitua os arquivos antes do par atual expirar para que Claude Code não carregue um par já expirado na próxima inicialização. Em sessões na nuvem, o ambiente de hospedagem gerencia a conexão com a API, portanto Claude Code ignora as seguintes variáveis quando vêm de um bloco env do arquivo de configurações:
  • CLAUDE_CODE_CLIENT_CERT
  • CLAUDE_CODE_CLIENT_KEY
  • CLAUDE_CODE_CLIENT_KEY_PASSPHRASE
  • NODE_EXTRA_CA_CERTS
  • NODE_TLS_REJECT_UNAUTHORIZED
  • CLAUDE_CODE_OAUTH_SCOPES
Claude Code anota cada chave ignorada no log de depuração da sessão. Em sessões do Claude Desktop onde o aplicativo gerencia a conexão do provedor, como a aba Code em um provedor de terceiros e sessões Cowork, Claude Code lê essas variáveis e as variáveis de proxy HTTP_PROXY, HTTPS_PROXY e NO_PROXY apenas de configurações gerenciadas e ~/.claude/settings.json: ele as ignora nos arquivos de configurações próprios de um repositório, portanto um repositório verificado não pode redirecionar o caminho TLS ou proxy de uma sessão cujas credenciais vêm do aplicativo. Em uma sessão local, SSH ou WSL Code tab conectada através de claude.ai, o aplicativo não gerencia a conexão, e Claude Code lê essas variáveis de cada escopo de configurações, como qualquer sessão de terminal; sessões na nuvem seguem as regras de sessão na nuvem acima onde quer que você as inicie. Antes da v2.1.217, Claude Code ignorava essas variáveis em todos os arquivos de configurações quando o aplicativo gerenciava a conexão.

​
Verificar sua configuração

Você geralmente descobre um endereço de proxy incorreto ou um caminho de certificado inválido a partir de um erro de conexão ou certificado em uma solicitação posterior, já que Claude Code não valida a maioria dessas configurações quando as lê. A única configuração que verifica na inicialização é a URL do proxy: quando não consegue analisar o valor, como um que está faltando o esquema http://, Claude Code interrompe o lançamento com um erro nomeando a variável a ser corrigida. Para confirmar que sua configuração foi carregada antes de enviar uma solicitação, inicie Claude Code com registro de depuração:
A saída de depuração vai para ~/.claude/debug/<session-id>.txt em vez do terminal, ou para um caminho que você define com --debug-file <path>. No log, procure pelas linhas que confirmam que cada arquivo foi carregado:
Se Claude Code não conseguir ler um desses arquivos, o log mostra uma linha Failed to read ou Failed to load com o motivo em vez disso. Você também pode executar /status em uma sessão interativa e verificar estas linhas:
  • Proxy: mostra a URL do proxy ativo e marca um valor que não consegue analisar como inválido e ignorado.
  • mTLS client cert e mTLS client key: aparecem apenas quando os arquivos foram carregados, portanto uma linha ausente significa que o carregamento falhou e o log de depuração tem o motivo.
  • Additional CA cert(s): mostra o caminho NODE_EXTRA_CA_CERTS sem verificar se o arquivo foi carregado, portanto confirme este no log de depuração.

​
Aplicar configurações de rede a agentes em segundo plano

Agentes em segundo plano não são executados dentro do terminal que os despacharam. Um processo supervisor por usuário inicia sob demanda, sobrevive ao seu shell e hospeda cada sessão claude agents, --bg e /background. Veja Como as sessões em segundo plano são hospedadas. Isso muda como a configuração nesta página chega a essas sessões.

​
Defina variáveis de rede em configurações, não no shell

O supervisor é um processo compartilhado por cada terminal. Ele herda o ambiente de qualquer shell que o inicie primeiro, e um supervisor instalado pelo SO não recebe nenhum ambiente de shell. Se você exportar um proxy, caminho de CA ou variável mTLS apenas no seu shell, ele chega aos agentes em segundo plano quando esse shell aconteceu de iniciar a frio o supervisor, e silenciosamente não chega quando um shell diferente fez isso. Coloque as mesmas variáveis no bloco env de ~/.claude/settings.json ou configurações gerenciadas. Cada variável nesta página pode ser definida lá, e as configurações são a única configuração que chega a cada sessão em segundo plano em cada máquina.

​
Configure um inicializador corporativo como uma configuração

Algumas organizações exigem que cada processo Claude Code inicie através de um inicializador corporativo que aplica sandboxing, controles de rede ou injeção de credenciais. O supervisor e seus workers iniciam Claude Code de um caminho fixo em vez de procurar claude em PATH, então cada agente em segundo plano ignora um wrapper que você coloca anteriormente em PATH. Defina a configuração processWrapper para prefixar o supervisor, seus workers e os outros processos em segundo plano listados em O que o inicializador cobre com seu inicializador. A variável de ambiente equivalente CLAUDE_CODE_PROCESS_WRAPPER tem precedência quando ambas são definidas, e está sujeita à mesma regra: entregue-a através de configurações gerenciadas ou ~/.claude/settings.json, não uma exportação de shell. Execute Claude Code atrás de um inicializador corporativo cobre o contrato que o inicializador deve satisfazer, o que faz e não faz, e como implementá-lo.
Um supervisor já em execução mantém a configuração de inicialização com a qual foi iniciado. Após implantar a configuração do inicializador, execute claude daemon stop --any para que o próximo claude agents ou --bg inicie um supervisor que a honre. Um serviço instalado leva claude daemon stop sem --any.

​
Watchdogs de inatividade de streaming

Claude Code executa quatro temporizadores independentes que abortam uma resposta de modelo de streaming quando fica silenciosa, para que uma conexão morta falhe e tente novamente em vez de ficar pendurada. O prazo de primeiro byte cobre a espera pelos cabeçalhos de resposta, antes de qualquer parte da resposta ter chegado. Cada um dos outros três monitora uma resposta ativa para um sinal diferente. Configure os temporizadores com estas variáveis, cada uma detalhada na referência de variáveis de ambiente:
  • CLAUDE_ENABLE_STREAM_WATCHDOG e CLAUDE_ENABLE_BYTE_WATCHDOG forçam o watchdog correspondente ligado com 1 ou desligado com 0, dentro das conexões que a tabela lista; nenhuma variável estende um watchdog para um tipo de conexão que não cobre. CLAUDE_ENABLE_BYTE_WATCHDOG definido como 0 também desativa o prazo de primeiro byte.
  • CLAUDE_STREAM_IDLE_TIMEOUT_MS define o tempo limite de ambos os watchdogs. Claude Code aumenta valores abaixo de 5 minutos para 5 minutos, e limita o valor a 30 minutos para o watchdog de nível de byte.
  • CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS define o tempo limite do watchdog de nível de byte sem alterar o do watchdog de nível de evento, limitado entre 10 segundos e 30 minutos, e tem precedência sobre CLAUDE_STREAM_IDLE_TIMEOUT_MS para esse watchdog.
  • CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS define o prazo de primeiro byte diretamente. Deixe-o não definido e Claude Code usa o tempo limite do watchdog de nível de byte, então CLAUDE_STREAM_IDLE_TIMEOUT_MS e CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS também alteram o prazo. Para os limites, a permissão de upload, o limite API_TIMEOUT_MS, e quanto tempo a tentativa aguarda após um aborto sem resposta, veja Nenhuma resposta da API.
  • API_FORCE_IDLE_TIMEOUT definido como 0 desativa o tempo limite de inatividade do corpo, e definido como 1 o ativa para cada provedor. Os watchdogs executam independentemente dele, então para permitir que um stream pause mais tempo do que seus limites, também aumente ou desative-os.
Quando um watchdog aborta um stream travado, Claude Code trata o aborto como uma falha no meio do stream, e o que você vê depende de quão longe a resposta tinha chegado. Claude Code tenta novamente a solicitação ou encerra a rodada com um erro, mantém a saída concluída e mostra um aviso de resposta incompleta, ou encerra a rodada normalmente. Tentativas automáticas diz onde cada resultado se aplica. Em uma sessão não interativa, e para a resposta de um subagente em qualquer sessão, Claude Code pode primeiro solicitar ao Claude que continue a resposta cortada; a entrada desse aviso diz quando faz isso e quando você ainda vê o aviso. Quando o prazo de primeiro byte dispara, nenhuma resposta começou, então não há saída parcial para manter. Para como Claude Code reenvia a solicitação e quando a rodada termina em vez disso, veja Nenhuma resposta da API.

​
Requisitos de acesso à rede

Claude Code requer acesso aos seguintes URLs. Coloque-os na lista de permissões em sua configuração de proxy e regras de firewall, especialmente em ambientes de rede containerizados ou restritos. A verificação de conectividade de configuração de primeira execução aponta para aqui quando não consegue alcançar api.anthropic.com ou platform.claude.com; consulte Não é possível conectar aos serviços Anthropic para as mensagens da verificação e etapas de recuperação. Se você instalar Claude Code através de npm ou gerenciar sua própria distribuição binária, os usuários finais não precisam dos usos do instalador nativo e atualizador automático de downloads.claude.ai, mas instalações npm e bun precisam de seu registro de pacotes, registry.npmjs.org, a menos que sua organização o espelhe. Os outros usos na tabela se aplicam independentemente do método de instalação. Os dois hosts de ingestão do Datadog carregam apenas telemetria operacional opcional, e definir CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC desabilita ambos. Sessões em provedores de terceiros nunca enviam para esses hosts, mesmo quando uma plataforma define CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST e as métricas de telemetria são ativadas por padrão. Consulte Serviços de telemetria para tudo que Claude Code envia e como desabilitá-lo antes de finalizar sua lista de permissões. Ao usar Amazon Bedrock, Agent Platform do Google Cloud, Microsoft Foundry ou uma sessão de gateway de aplicativos Claude conectada, o tráfego de modelo e autenticação vão para seu provedor ou gateway em vez de api.anthropic.com, claude.ai ou platform.claude.com. A ferramenta WebFetch ainda chama api.anthropic.com para sua verificação de segurança de domínio a menos que você defina skipWebFetchPreflight: true em configurações. Ao rotear através de um gateway LLM com ANTHROPIC_BASE_URL, a verificação de disponibilidade do modo rápido ainda chama api.anthropic.com em vez da URL base do gateway. A verificação honra um proxy HTTP configurado, portanto, quando um bloqueio de rede é a causa, uma entrada de lista de permissões para api.anthropic.com no proxy é a solução. Um bloqueio de rede falha na verificação apenas quando o host é inacessível mesmo através do proxy, e o modo rápido então relata um erro de conectividade. O mesmo erro de conectividade aparece quando a verificação apresenta uma credencial emitida pelo gateway que Anthropic rejeita; a lista de permissões não ajuda lá, já que nada está bloqueado. Consulte usar modo rápido atrás de proxies e gateways LLM para as variáveis que o restauram.

​
Listas de permissões de IP da organização e saída de proxy

Se sua organização tiver lista de permissões de IP ativada para Claude, roteia bridge.claudeusercontent.com através da mesma saída de proxy que claude.ai e api.anthropic.com, por exemplo, colocando-o no mesmo segmento de aplicativo Zscaler ou política de direcionamento Netskope. Se você não conseguir roteá-lo dessa forma, adicione o endereço de saída que seu proxy usa para esse host à lista de permissões de IP da sua organização, mas apenas quando esse endereço for dedicado à sua organização: um intervalo de saída de proxy compartilhado também admite outros clientes do fornecedor de proxy. Anthropic verifica conexões com bridge.claudeusercontent.com contra a lista de permissões de IP da sua organização usando o endereço de onde chegam. Se seu proxy enviar tráfego para esse host através de um endereço que não esteja nessa lista de permissões, Claude Code não conseguirá se conectar à extensão Claude no Chrome mesmo que o resto do Claude Code funcione.

​
Listas de permissões e firewalls do GitHub

Claude Code na web em ambientes hospedados pela Anthropic e Code Review se conectam aos seus repositórios a partir da infraestrutura gerenciada pela Anthropic; sessões em um ambiente auto-hospedado se conectam de dentro de sua rede, a menos que o executor opte pelo proxy git Anthropic, que busca do lado da Anthropic. Se sua organização GitHub Enterprise Cloud restringe o acesso por endereço IP, ative herança de lista de permissões de IP para GitHub Apps instalados e também adicione uma entrada de lista de permissões para os endereços IP de saída da Anthropic. A herança cobre apenas as solicitações que o GitHub App Claude faz como uma instalação, não as solicitações que faz em nome de seus usuários. Para outros firewalls, consulte os endereços IP da API Anthropic. Para instâncias GitHub Enterprise Server auto-hospedadas atrás de um firewall, coloque na lista de permissões os endereços IP de saída da Anthropic para que a infraestrutura Anthropic possa alcançar seu host GHES para clonar repositórios e postar comentários de revisão. Sessões em um ambiente auto-hospedado alcançam seu host GHES de dentro de sua rede, portanto essa exposição se aplica apenas a sessões hospedadas pela Anthropic, a fluxos pré-sessão hospedados, como o seletor de repositório, e a executores auto-hospedados que optam pelo proxy git Anthropic, que busca do lado da Anthropic. Para um host GHES que é roteável apenas dentro de sua rede, o conector SCM carrega os fluxos pré-sessão hospedados sobre uma conexão de saída, portanto a lista de permissões não é necessária para eles.

​
Desktop e claude.ai

A tabela anterior cobre a CLI autônoma. O aplicativo Claude Desktop e claude.ai em um navegador carregam seu código de aplicativo e conteúdo do usuário de hosts CDN Anthropic adicionais, incluindo assets-proxy.anthropic.com e as outras origens *.claudeusercontent.com que servem artifacts nesses aplicativos. Permitir claude.ai enquanto bloqueia esses hosts produz uma página em branco em vez de um erro. Consulte requisitos de acesso à rede na página Desktop. Um artifact que carrega uma fonte tipográfica do Google Fonts também solicita fonts.googleapis.com e fonts.gstatic.com. Ambos os hosts são opcionais. Se você bloqueá-los, os artifacts são renderizados em fontes tipográficas de fallback. Bloqueie com uma rejeição rápida em vez de uma queda silenciosa para que a solicitação de fonte falhe imediatamente em vez de atrasar a primeira renderização da página. Os artifacts também podem carregar bibliotecas JavaScript, como React ou um pacote de gráficos, de cdnjs.cloudflare.com, cdn.jsdelivr.net, cdn.tailwindcss.com e code.jquery.com, e de nenhum outro host externo. Se você bloquear esses hosts, as partes de um artifact que dependem de uma biblioteca não funcionam, e diferentemente de uma fonte bloqueada, uma biblioteca bloqueada não tem fallback. Bloqueie com uma rejeição rápida aqui também, para que uma solicitação de biblioteca bloqueada falhe imediatamente em vez de ficar pendurada até expirar.

​
Recursos adicionais