Agente de IA no terminal atrás de proxy e firewall da empresa: como configurar HTTPS_PROXY, certificado interno e domínios liberados

Fala aí, beleza? 🙂

Instalou o agente no terminal, tudo certinho, e na primeira execução ele trava num erro de conexão

Ou aparece o clássico self-signed certificate in certificate chain, e você fica olhando pra tela tentando entender o que certificado tem a ver com um CLI de IA

Ou então o login abre o navegador, a autenticação acontece, o navegador diz que deu tudo certo, e o terminal continua esperando pra sempre 😛

Se isso está rolando na máquina da empresa, o culpado quase nunca é a ferramenta

É a rede: proxy obrigatório na saída, inspeção TLS reemitindo os certificados com a CA interna e firewall com allowlist incompleta

Aqui eu vou por sintoma, com Claude Code e Codex CLI lado a lado, mais as configurações de npm e Node pra quem instalou via npm e nem chegou a abrir o agente

Bora resolver?

Sintoma 1: o agente não conecta e a rede exige proxy

O sintoma é o mais seco de todos: falha de conexão logo na inicialização ou no primeiro comando, numa máquina que só sai pra internet passando pelo proxy da empresa

A causa é simples de enunciar: o cliente HTTP do agente não tem rota direta pra fora, e ninguém contou pra ele qual é o caminho

Só pra alinhar antes de seguir: o proxy aqui é o da REDE, aquele que intercepta a saída da máquina inteira, e não tem nada a ver com proxy que economiza contexto do agente, que é outro papo

A solução no Claude Code:

A documentação de configuração de rede do Claude Code diz que ele respeita as variáveis de ambiente padrão de proxy

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

HTTPS_PROXY é a recomendada, HTTP_PROXY entra como alternativa quando HTTPS não está disponível e NO_PROXY fica pras exceções

export HTTPS_PROXY=https://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY=  # hosts que não devem passar pelo proxy

Agora o ponto que derruba MUITA gente: essas variáveis são lidas uma única vez, na inicialização

Ou seja, exportar com a sessão já aberta não resolve nada, a sessão em execução não pega a mudança

Exporta primeiro, abre o agente depois, beleza?

E pra alcançar sessões em segundo plano, as mesmas variáveis podem ir no bloco env do settings.json, seja o ~/.claude/settings.json ou o managed settings

{
  "env": {
    "HTTPS_PROXY": "https://proxy.example.com:8080"
  }
}

A solução no Codex CLI:

O cliente HTTP do Codex respeita as variáveis de proxy padrão do Unix, conforme a documentação de configuração avançada do Codex: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY e NO_PROXY

Repara que aqui entra o ALL_PROXY, que não aparece na lista do Claude Code

export HTTPS_PROXY=https://proxy.example.com:8080
export ALL_PROXY=https://proxy.example.com:8080

Como prevenir:

Escreve SEMPRE o esquema na URL do proxy

Se a URL não puder ser interpretada, por exemplo faltando o http://, o Claude Code interrompe a inicialização com um erro nomeando exatamente a variável que precisa ser corrigida

Isso é ótimo, viu? O erro te entrega o culpado de bandeja em vez de virar um timeout misterioso

Sintoma 2: ‘self-signed certificate in certificate chain’ por inspeção TLS

Esse aqui é o erro mais assustador e o mais chato de explicar pro time

Ele aparece no agente, aparece no npm install, aparece em qualquer coisa que faça HTTPS a partir daquela máquina

A causa:

A rede faz inspeção TLS: o proxy abre a conexão no meio do caminho e reemite os certificados assinados com a CA da empresa

Pra ferramenta, isso é indistinguível de alguém se passando pelo servidor, e ela recusa

A própria página de erros comuns do npm aponta nessa direção: se as soluções sugeridas não resolverem o erro de certificado autoassinado, a causa provável é um proxy interceptando SSL na rede

A solução no Claude Code:

O Claude Code usa NODE_EXTRA_CA_CERTS apontando pra um arquivo PEM com a CA raiz da empresa

Esses certificados são SOMADOS à lista de confiança, não substituem nada

export NODE_EXTRA_CA_CERTS=/caminho/para/ca-empresa.pem

Existe também o CLAUDE_CODE_CERT_STORE, que aceita uma lista separada por vírgula com dois valores reconhecidos: bundled (o conjunto de CAs Mozilla que acompanha o Claude Code) e system (o repositório de confiança do sistema operacional)

Por padrão ele já confia nos dois, então mexer aqui só faz sentido quando você quer restringir ou forçar um comportamento específico

A solução no Codex CLI:

No Codex o nome muda: a documentação de autenticação do Codex manda usar CODEX_CA_CERTIFICATE apontando pro bundle PEM, e define ANTES do login

export CODEX_CA_CERTIFICATE=/caminho/para/corporate-root-ca.pem
codex login

Quando CODEX_CA_CERTIFICATE não está definida, o Codex recorre ao SSL_CERT_FILE

E tem um detalhe bom: essa mesma configuração de CA vale pro login, pras requisições HTTPS normais e também pras conexões WebSocket seguras

O detalhe do Node que morde:

A página de configuração de rede empresarial do Node.js é clara: quando NODE_EXTRA_CA_CERTS está definida, as CAs raiz conhecidas são estendidas com os certificados extras do arquivo, que precisa estar em formato PEM com um ou mais certificados confiáveis

E ela é lida SÓ quando o processo inicia

Mudar o valor em tempo de execução via process.env não tem efeito nenhum no processo atual, mesma lógica das variáveis de proxy

Tome cuidado com mais uma: nem os certificados conhecidos nem os extras são usados quando a propriedade ca é especificada explicitamente num cliente ou servidor TLS/HTTPS

Se algum script interno do seu time define ca na mão, ele sobrescreve tudo e o seu PEM vira decoração

Como prevenir:

No npm, a orientação oficial é preferir configurar uma CA ou um arquivo de CA para uso com o proxy em vez de desabilitar a proteção SSL

Desligar verificação é solução de dez minutos que vira dívida de segurança pro resto do ano

Sintoma 3: o npm falha antes mesmo de instalar o agente

Esse caso é engraçado de tão comum: nem existe sessão do agente ainda, a instalação já quebrou

A causa é que o npm tem configuração PRÓPRIA de proxy e de confiança, ele não herda mágica de lugar nenhum

A solução:

A config do npm tem a chave https-proxy, que é o proxy usado pras requisições HTTPS de saída

E se as variáveis de ambiente HTTPS_PROXY, https_proxy, HTTP_PROXY ou http_proxy estiverem definidas, as configurações de proxy são honradas pela biblioteca subjacente make-fetch-happen

Todos os arquivos de configuração do npm são listas em formato ini, com parâmetros chave = valor, e um .npmrc na raiz do projeto define valores específicos daquele projeto

https-proxy = https://proxy.example.com:8080

Falta o firewall: registry.npmjs.org precisa estar liberado pra instalações via npm, a não ser que a empresa espelhe o registro internamente

E calma que a allowlist completa, com os domínios dos dois lados, tem seção própria aqui embaixo

Como prevenir:

Quando a CA da empresa já está instalada no sistema operacional, dá pra combinar NODE_USE_SYSTEM_CA com NODE_EXTRA_CA_CERTS

Com os dois ativos, o Node confia nas CAs embutidas, nas CAs do sistema e ainda nos certificados adicionais do arquivo

export NODE_USE_SYSTEM_CA=1
export NODE_EXTRA_CA_CERTS=/caminho/para/ca-empresa.pem

Se o teu time já mantém agentes de IA em automações internas, vale padronizar isso no ambiente do serviço e não só no teu shell, porque processo que roda sozinho não tem ninguém pra exportar variável na mão

Sintoma 4: o login por navegador abre mas nunca conclui

O navegador abre, você autentica, a tela diz que deu certo

E o terminal? Parado, piscando, esperando o fim do mundo 😀

A causa:

O navegador não alcança o servidor de callback local

É o cenário clássico de WSL2, sessão SSH e contêiner: quem abre o navegador está de um lado, quem escuta a porta está do outro

A solução no Claude Code:

A documentação de identidade e acesso do Claude Code trata isso direto: quando o navegador mostra um código de login em vez de redirecionar de volta, é só colar esse código no prompt do terminal

E se o navegador nem abrir sozinho, a tecla c copia a URL de login pra você abrir onde quiser

A solução no Codex CLI:

O servidor de callback local do Codex é localhost na porta 1455

Dá pra usar o fluxo padrão de navegador em máquina remota fazendo encaminhamento dessa porta entre a máquina local e o host remoto

E quando o ambiente é remoto ou headless, ou quando a rede local bloqueia o callback em localhost, a recomendação é a autenticação por código de dispositivo, que está em beta

codex login --device-auth

O mesmo fluxo aparece como opção ‘Sign in with Device Code’ na tela de login

Como prevenir:

Em CI e scripts, onde navegador simplesmente não existe, o caminho no Claude Code é gerar um token OAuth de longa duração

claude setup-token

Esse token é impresso no terminal e NÃO fica salvo, então copia na hora pra variável CLAUDE_CODE_OAUTH_TOKEN

O recurso exige plano Pro, Max, Team ou Enterprise

Sintoma 5: o firewall bloqueia domínios ou o handshake WebSocket

Aqui o sintoma é mais sutil: proxy configurado, CA no lugar, e mesmo assim uma conexão cai do nada, ou o filtro web devolve uma resposta estranha, ou um recurso específico simplesmente não funciona

A causa costuma ser allowlist incompleta ou inspeção interferindo numa conexão de longa duração

O lado Anthropic:

A documentação do Claude Code publica uma lista de URLs que devem ser liberadas no proxy e nas regras de firewall, e isso pesa ainda mais em ambientes conteinerizados ou restritos

Entre os hosts citados na página estão:

• api.anthropic.com
• platform.claude.com
• bridge.claudeusercontent.com
• claude.ai
• downloads.claude.ai (instalador nativo e auto-update)
• registry.npmjs.org (instalações via npm ou bun, salvo se a empresa espelhar o registro)

A lista também traz dois hosts de intake do Datadog, que carregam apenas telemetria operacional opcional

Se o teu time de segurança não quiser abrir esses dois, dá pra desativar os dois de uma vez com CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC

O lado OpenAI:

Aqui o ponto nevrálgico é WebSocket

A orientação oficial é liberar tráfego WebSocket na porta TCP 443 e permitir o handshake padrão Upgrade: websocket no proxy, firewall ou secure web gateway, porque recursos do ChatGPT e do Codex usam WebSocket seguro além de HTTPS

E se o teu firewall não consegue liberar tráfego WebSocket por caminho de URL, a recomendação é permitir os upgrades de WebSocket para chatgpt.com na porta TCP 443

Tem mais: os controles de inspeção TLS, descriptografia SSL, filtragem web e enforcement de proxy não devem bloquear, reescrever nem encerrar prematuramente o handshake WebSocket ou a conexão de longa duração que nasce dele

E, quando possível, a orientação é desabilitar a inspeção SSL para os domínios públicos da OpenAI, já que a descriptografia na rede pode gerar erros de SSL e atrapalhar o acesso

Como prevenir:

A OpenAI mantém o artigo oficial Network recommendations for ChatGPT errors on web and apps, que lista os domínios que não devem ser bloqueados na rede da empresa e reforça que a filtragem de web/URL não deve responder com conteúdo inesperado

Eu não vou reproduzir os domínios aqui de cabeça, justamente pra não te fazer abrir regra errada: pega a lista na fonte e leva pro time de rede

Claude Code x Codex CLI: o que cada um espera da sua rede

Tabela de consulta rápida, só com o que está documentado de cada lado

Quando aparece ‘não consta’, é porque a informação existe pra um produto e não foi confirmada pro outro, e detalhe de uma ferramenta não vale pra outra

Ainda não funciona: como confirmar o que está de fato carregado

Cenário chato: está tudo configurado, você jura que está, e o erro continua igualzinho

Na prática, quase sempre a configuração existe mas não está sendo aplicada ao processo certo

Roda essa sequência de checagem:

1. Confirme que as variáveis foram exportadas ANTES de abrir o agente, e não depois. O erro comum aqui é exportar numa aba e abrir o agente em outra, ou exportar com a sessão já rodando, que é justamente o caso em que a leitura única no startup já passou
2. Se a sessão roda em segundo plano, coloque as variáveis no bloco env do ~/.claude/settings.json ou no managed settings, porque o shell interativo não alcança esse processo
3. No Claude Code, olhe o log de debug: o NODE_EXTRA_CA_CERTS aparece lá mostrando o caminho, mas isso NÃO verifica se o arquivo foi realmente carregado. A confirmação precisa sair do log de debug, então não pare no ‘a variável está lá’ e siga lendo
4. Cheque a versão do Node antes de contar com o repositório de certificados do sistema. Ler esse store exige um runtime com tls.getCACertificates: o instalador nativo sempre tem, e instalações via npm precisam de Node 22.15 ou superior
5. Se o Node for antigo, aceite o que sobra: valem apenas o conjunto embutido e o NODE_EXTRA_CA_CERTS. O erro comum deste passo é passar a tarde inteira mexendo no store do sistema num runtime que nem consegue lê-lo

Quando o bloqueio vem do próprio agente: sandbox e políticas de domínio

Tem um caso que confunde demais: a rede está liberada, o proxy está certo, e mesmo assim o agente não alcança um endereço

Aí o bloqueio não é da empresa, é do PRÓPRIO agente

Sandbox do Claude Code:

O Claude Code roda em sandbox com restrições de rede e de sistema de arquivos, e aceita configuração de rede customizada pra você escolher a quais domínios ele pode se conectar a partir do sandbox

Então vale a pergunta antes do drama: o domínio está bloqueado no firewall ou está fora da configuração do sandbox?

Política de domínio no Codex:

Em deploys gerenciados do Codex CLI dá pra configurar políticas de rede por domínio, permitindo acesso só conforme a política configurada, com entradas do tipo "api.openai.com" = "allow"

E se liga nesse alerta, que é ouro pra time de plataforma: no Codex, o tráfego de apps e conectores NÃO é controlado pelo proxy de rede de comandos em sandbox nem pela lista de domínios permitidos dele

Ou seja, sua allowlist de sandbox não é o perímetro inteiro, e tratar ela como se fosse é pedir pra tomar surpresa depois

Conclusão

A ordem de ataque é quase sempre a mesma, e seguir ela economiza horas:

1. Proxy primeiro, com HTTPS_PROXY e amigos exportados antes de abrir a sessão
2. Depois a CA da empresa, com NODE_EXTRA_CA_CERTS no Claude Code ou CODEX_CA_CERTIFICATE no Codex antes do login
3. Depois a allowlist do firewall e o handshake WebSocket
4. Por último o login, com código colado no terminal, port forwarding, device code ou token pra CI

E a regra que eu repetiria em voz alta na daily: exporta ANTES de abrir a sessão, porque leitura única no startup não perdoa 😀

O próximo passo saudável é levar a lista de hosts e a orientação sobre WebSocket e inspeção TLS pro time de segurança, com link da fonte, em vez de sair desligando verificação SSL na marra

Um libera direito, o outro desliga proteção pra sempre… a diferença aparece lá na frente

Até o próximo post!

Matheus Battisti