Como configurar HTTPS_PROXY para Cursor e Claude Code em uma rede corporativa

Se a sua empresa bloqueia o tráfego de saída através de um proxy corporativo, assistentes de IA como Cursor e Claude Code simplesmente param de responder: a autocompletação congela, o CLI retorna ETIMEDOUT ou problema de certificado SSL. Vamos analisar como configurar corretamente as variáveis de ambiente HTTPS_PROXY, configurar a autenticação e evitar erros comuns que fazem com que os desenvolvedores gastem horas depurando as configurações de rede em vez do código.

Por que assistentes de IA precisam de proxy em uma rede corporativa

Cursor e Claude Code não são modelos locais. Eles constantemente acessam APIs externas: Cursor se conecta aos seus servidores de indexação de código e às APIs dos modelos (OpenAI, Anthropic, Google, dependendo do provedor escolhido), enquanto Claude Code — se conecta diretamente à API da Anthropic via HTTPS. Em uma rede corporativa, o acesso direto à internet geralmente é bloqueado por um firewall, e todo o tráfego de saída deve passar por um servidor proxy (Squid, Zscaler, Blue Coat, Fortinet FortiProxy ou um gateway corporativo interno). Sem as variáveis de ambiente configuradas corretamente, o aplicativo simplesmente não sabe que o tráfego deve ser redirecionado através do proxy e tenta se conectar à internet diretamente — resultando em timeouts.

Uma dificuldade adicional é que o Cursor é construído sobre o Electron (basicamente, é Chromium + Node.js), enquanto o Claude Code é um aplicativo CLI em Node.js. Cada um tem sua própria lógica para ler as configurações do proxy: o Electron herda parcialmente as configurações do sistema operacional, enquanto os processos Node.js leem as variáveis de ambiente HTTP_PROXY/HTTPS_PROXY diretamente ou através de bibliotecas como undici e node-fetch. Isso gera confusão: as configurações estão definidas, mas a ferramenta "não as vê".

Variáveis HTTP_PROXY, HTTPS_PROXY e NO_PROXY: como funciona

A maneira clássica de especificar um proxy para aplicativos de console Node.js, Python e Go é através de variáveis de ambiente. A diferença entre HTTP_PROXY e HTTPS_PROXY é fundamental: o primeiro é usado para solicitações via protocolo HTTP, enquanto o segundo é para solicitações HTTPS (e quase todo o tráfego dos assistentes de IA é feito via HTTPS). É recomendável definir ambos, mesmo que o tráfego real seja apenas HTTPS — algumas bibliotecas fazem solicitações HTTP de serviço no início.

export HTTP_PROXY="http://proxy.company.local:8080"
export HTTPS_PROXY="http://proxy.company.local:8080"
export NO_PROXY="localhost,127.0.0.1,.company.local"

Observe que, mesmo para tráfego HTTPS, o esquema no endereço do proxy é especificado como http://, e não https:// — este é o endereço do próprio servidor proxy, e não do recurso de destino. A conexão com o proxy via HTTP é normal; a criptografia para o servidor final ainda funciona através do mecanismo de tunelamento CONNECT.

A variável NO_PROXY é necessária para excluir endereços internos da empresa da proxy — caso contrário, solicitações para repositórios git internos, Jira ou serviços de desenvolvimento locais também passarão pelo proxy externo e podem não ser encontradas ou podem ser lentas. Um ponto importante: algumas bibliotecas são sensíveis ao caso das variáveis. Para maior segurança, defina ambas as versões — em maiúsculas e minúsculas:

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export no_proxy="$NO_PROXY"

Configuração de proxy para Cursor

O Cursor utiliza parcialmente as configurações de proxy do sistema operacional (especialmente no macOS e Windows), mas para um funcionamento estável em uma rede corporativa é melhor configurá-lo explicitamente através de variáveis de ambiente e, se necessário, através do arquivo de configuração do aplicativo.

No macOS e Linux, a maneira mais fácil é adicionar a exportação das variáveis no arquivo de perfil do shell, para que sejam carregadas a cada inicialização do terminal de onde o Cursor é iniciado:

# ~/.zshrc ou ~/.bash_profile
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"
export NO_PROXY="localhost,127.0.0.1,*.company.local"

Após alterar o arquivo de perfil, execute source ~/.zshrc e reinicie completamente o Cursor (não apenas minimize a janela — finalize o processo através do Monitor de Atividade ou do gerenciador de tarefas, pois aplicativos Electron armazenam em cache o ambiente na inicialização).

No Windows, as variáveis são mais facilmente definidas através das configurações de ambiente do sistema (Painel de Controle → Sistema → Configurações Avançadas do Sistema → Variáveis de Ambiente) ou através do PowerShell para salvamento permanente:

[System.Environment]::SetEnvironmentVariable('HTTPS_PROXY','http://user:[email protected]:8080','User')
[System.Environment]::SetEnvironmentVariable('HTTP_PROXY','http://user:[email protected]:8080','User')
[System.Environment]::SetEnvironmentVariable('NO_PROXY','localhost,127.0.0.1','User')

Se após isso o Cursor ainda não se conecta à API dos modelos, verifique as configurações do proxy dentro do próprio aplicativo: Configurações → Rede (ou Geral) — pode haver um campo separado Proxy URL, que sobrescreve as variáveis do sistema. Em algumas versões do Cursor, também é necessário ativar explicitamente a opção "Usar configurações de proxy do sistema".

Configuração de proxy para Claude Code

Claude Code é uma ferramenta CLI em Node.js, executada via npm/npx, portanto, lê diretamente as variáveis de ambiente da sessão do terminal em que foi chamada. Isso simplifica a configuração: basta exportar as variáveis antes da execução.

export HTTPS_PROXY="http://user:[email protected]:8080"
export HTTP_PROXY="http://user:[email protected]:8080"
claude

Se você estiver executando o Claude Code como parte de um pipeline CI ou de um script, passe as variáveis explicitamente no comando de execução, para evitar dependência do ambiente global do shell:

HTTPS_PROXY="http://proxy.company.local:8080" \
HTTP_PROXY="http://proxy.company.local:8080" \
claude --print "Verifique os testes no projeto"

Para uma configuração permanente, é mais conveniente fixar as variáveis em um arquivo .env na raiz do projeto e carregá-lo através de direnv ou suporte embutido ao dotenv, se seu shell o suportar. Isso é especialmente útil quando diferentes projetos exigem diferentes configurações de proxy (por exemplo, um projeto funciona com uma API interna, enquanto outro — com serviços externos).

Autenticação em proxy corporativo

A maioria dos proxies corporativos exige autenticação — Basic Auth, Digest ou NTLM. Para Basic Auth, o login e a senha podem ser incorporados diretamente na URL do proxy, como mostrado acima: http://user:[email protected]:8080. Um ponto importante — se a senha contém caracteres especiais (@, #, %), eles precisam ser codificados em URL, caso contrário, o parser da string do proxy falhará na fronteira entre o login e o host.

# Se a senha for P@ssw0rd#2024, codificamos os caracteres especiais:
# @ -> %40, # -> %23
export HTTPS_PROXY="http://user:P%40ssw0rd%[email protected]:8080"

É mais complicado com a autenticação NTLM (frequentemente usada em conjunto com Microsoft ISA Server, Forefront TMG ou Fortinet) — Node.js e a maioria dos clientes HTTP não suportam NTLM "nativamente". Nesse caso, a solução padrão é levantar um proxy intermediário local que assume o handshake NTLM e, em seguida, fornece um proxy HTTP "limpo" para o aplicativo. Para isso, frequentemente se utiliza cntlm ou px (um proxy NTLM local em Python). O esquema é simples: Cursor/Claude Code → localhost:3128 (cntlm) → proxy NTLM corporativo → internet.

# Exemplo de configuração do cntlm (/etc/cntlm.conf)
Username    seu_login
Domain      EMPRESA
Password    sua_senha_ou_hash
Proxy       proxy.company.local:8080
Listen      3128

# Após iniciar o cntlm, especificamos o endereço local:
export HTTPS_PROXY="http://127.0.0.1:3128"
export HTTP_PROXY="http://127.0.0.1:3128"

Certificados e MITM: problema de SSL em uma rede corporativa

Se a empresa implementou um produto como Zscaler, Netskope ou qualquer outro filtro web com inspeção SSL, o tráfego é descriptografado no proxy e assinado com o certificado CA Root corporativo. Node.js (e, portanto, também Claude Code, e a maior parte dos módulos internos do Cursor) por padrão confia apenas em seu conjunto embutido de certificados raiz e lançará um erro UNABLE_TO_VERIFY_LEAF_SIGNATURE ou certificado autoassinado na cadeia de certificados.

A solução é exportar o certificado CA corporativo (geralmente pode ser obtido no departamento de TI ou extraído do armazenamento de certificados do navegador) e indicar ao Node.js o caminho para ele através da variável NODE_EXTRA_CA_CERTS:

export NODE_EXTRA_CA_CERTS="/etc/ssl/certs/company-root-ca.pem"

É altamente desaconselhável desativar globalmente a verificação de certificados através de NODE_TLS_REJECT_UNAUTHORIZED=0 — isso remove a proteção contra ataques MITM para todo o processo, incluindo conexões legítimas. Use essa flag apenas para diagnóstico ocasional e sempre retorne a proteção.

Erros comuns e suas soluções

Erro	Causa	Solução
ETIMEDOUT / ECONNREFUSED	As variáveis de proxy não foram exportadas na sessão em que o aplicativo está em execução	Verifique echo $HTTPS_PROXY no mesmo terminal, reinicie o aplicativo completamente
407 Proxy Authentication Required	Login/senha não especificados ou desatualizados	Atualize as credenciais na string do proxy, codifique em URL os caracteres especiais da senha
certificado autoassinado na cadeia de certificados	O proxy corporativo MITM substitui o certificado	Especifique NODE_EXTRA_CA_CERTS com o CA Root corporativo
O proxy funciona no terminal, mas não no Cursor	Cursor não foi iniciado no terminal correto ou através de um atalho sem ambiente	Inicie o Cursor com o comando do terminal com as variáveis exportadas, ou defina as variáveis globalmente no sistema
NTLM authentication failed	O cliente não suporta o handshake NTLM	Levante um proxy intermediário cntlm ou px entre o aplicativo e o proxy corporativo

Verificação de conexão via curl

Antes de investigar por que o Cursor ou Claude Code não está funcionando, certifique-se de que o próprio proxy está acessível e está redirecionando corretamente o tráfego HTTPS. Para isso, use o curl — ele lê as mesmas variáveis de ambiente e permite localizar rapidamente o problema sem iniciar aplicativos pesados.

# Verificação de acessibilidade do proxy e autenticação
curl -v -x "http://user:[email protected]:8080" https://api.anthropic.com

# Verificação considerando o certificado corporativo
curl -v --cacert /etc/ssl/certs/company-root-ca.pem \
  -x "http://user:[email protected]:8080" \
  https://api.anthropic.com

Se o curl obtiver uma resposta com sucesso (mesmo 401 ou 403 — isso é normal, significa que o handshake TLS foi bem-sucedido), e o Claude Code ainda não se conecta — o problema não está na rede, mas sim no fato de que o processo não vê as variáveis de ambiente. Se o curl também falhar com um erro de certificado ou timeout — o problema está no nível da rede ou do proxy, e as ferramentas não têm relação com isso.

Quando um proxy externo é necessário em vez do corporativo

Às vezes, a tarefa não se limita ao acesso da rede corporativa para o exterior. Desenvolvedores que testam integrações com APIs geograficamente dependentes, verificam o comportamento do serviço de diferentes países ou depuram políticas de rate-limit dos provedores de modelos, enfrentam o problema de que o proxy corporativo fornece o mesmo IP corporativo para todas as solicitações. Em tais cenários, é conveniente direcionar o tráfego de teste através de um proxy externo em paralelo com o ambiente de trabalho principal.

Para sessões de teste estáveis e de longa duração com risco mínimo de bloqueio por IP, são adequados proxies residenciais — eles utilizam endereços IP reais de provedores domésticos e se parecem com tráfego de usuário comum, o que é importante ao verificar respostas API geograficamente específicas. Se for necessário reproduzir o comportamento de um cliente móvel ou testar cenários sensíveis ao tipo de rede, vale a pena considerar proxies móveis. E para testes massivos e paralelos de solicitações a APIs públicas, onde a velocidade e o custo do tráfego são mais importantes do que a camuflagem como um usuário comum, geralmente são suficientes proxies de datacenter.

Importante: esse proxy externo é configurado da mesma forma através das variáveis HTTPS_PROXY/HTTP_PROXY, mas para um ambiente de teste ou um perfil de terminal separado, para não misturá-lo com o tráfego de trabalho principal através do gateway corporativo. Se a política corporativa exigir que todo o tráfego da empresa passe apenas pelo proxy interno, o uso de um externo deve ser aprovado pelo TI/Security — muitas empresas proíbem explicitamente a evasão do gateway corporativo sem permissão.

Checklist de configuração

Conclusão

A maioria dos problemas com Cursor e Claude Code atrás de um proxy corporativo se resume a três coisas: as variáveis de ambiente não chegam ao processo, a autenticação está configurada incorretamente, ou o certificado MITM corporativo não foi adicionado aos confiáveis. Verificando esses três pontos em ordem — através de curl, e não diretamente pelo aplicativo — você economiza horas de depuração e localiza rapidamente a causa.

Se a tarefa vai além da rede corporativa e você precisa testar o comportamento da API de diferentes regiões ou de diferentes tipos de IP, recomendamos experimentar proxies residenciais — eles fornecem tráfego estável e menos suspeito para serviços externos em comparação com endereços de datacenter comuns.