O cURL está presente em cerca de 20 bilhões de instalações no mundo todo — ele já vem integrado ao macOS, à maioria das distribuições Linux e, por padrão, ao Windows 10/11. Ainda assim, se você perguntar a dez desenvolvedores como encaminhar corretamente uma requisição cURL por meio de um proxy, provavelmente vai receber dez respostas um pouco diferentes — e metade delas vai falhar assim que autenticação ou SOCKS entrar em cena.
É justamente essa lacuna que eu quero fechar aqui. A maioria dos tutoriais mostra um comando, diz que funciona e segue em frente. Eles não mostram como confirmar se o proxy realmente está fazendo alguma coisa (spoiler: às vezes, não está), e com certeza não explicam os códigos de erro que aparecem na primeira pequena variação fora do cenário ideal. Este guia cobre tudo — proxies HTTP/HTTPS, SOCKS4/SOCKS5/socks5h, variáveis de ambiente (e suas pegadinhas bem específicas), uma tabela de solução de problemas de verdade e o que fazer quando cURL e proxy simplesmente já não dão conta do recado.
O que é cURL e por que usá-lo com proxy?
cURL é uma ferramenta de linha de comando para transferir dados de e para uma URL. Só isso — sem interface gráfica, sem enfeites, apenas um programa que fala HTTP, HTTPS, FTP e alguns outros protocolos. A forma mais simples de usá-lo é:
curl https://example.com
Isso busca a página e despeja o HTML bruto no terminal. Útil por si só, mas o verdadeiro motivo pelo qual desenvolvedores e usuários técnicos de negócio recorrem ao cURL é testar APIs, extrair dados, verificar conteúdo com restrição geográfica e executar requisições dentro de pipelines de CI/CD.
Um proxy fica entre sua máquina e o servidor de destino, encaminhando sua requisição em seu nome. O destino vê o IP do proxy, não o seu. Isso faz diferença por motivos legítimos: testar como seu site aparece de outro país, contornar limites de taxa durante QA ou rotear tráfego por um gateway corporativo exigido pela empresa. O cURL suporta toda a gama de protocolos de proxy — HTTP, HTTPS, SOCKS4 e SOCKS5 — e as flags que você vai ver repetidamente neste guia são -x / --proxy (o endereço do proxy), -v (saída detalhada, sua melhor amiga na depuração) e -k (pula a verificação SSL, algo que você basicamente nunca deve usar fora de testes).
Uma observação rápida antes de avançarmos: este guia trata da mecânica de rede ao usar um proxy com cURL. Ele não autoriza ignorar os termos de serviço de um site-alvo ou a política de segurança da sua organização. Um proxy muda o caminho da rede — não muda o que é permitido ou legal.
Antes de começar
Dificuldade: Iniciante a Intermediário
Tempo necessário: ~15 minutos para percorrer os exemplos principais
O que você vai precisar:
- cURL instalado (verifique com
curl --version— se você usa macOS, Linux ou Windows 10/11, é bem provável que ele já esteja lá) - Credenciais do proxy fornecidas pelo provedor: host, porta, protocolo (HTTP/HTTPS/SOCKS) e nome de usuário/senha, se necessário
- Um terminal (Terminal no macOS, qualquer shell no Linux, PowerShell ou CMD no Windows)
Se, por algum motivo, o cURL não estiver instalado, a solução é simples: brew install curl no macOS via Homebrew, sudo apt install curl no Debian/Ubuntu ou sudo yum install curl no RHEL/CentOS. No Windows, ele vem junto com o sistema desde o build 17063 do Windows 10.
Ao longo deste guia vou usar valores de exemplo — proxy.example:8080 para o endereço do proxy e user:pwd para as credenciais. Troque isso pelos dados reais do seu proxy e nunca cole credenciais verdadeiras no histórico do shell, em uma captura de tela ou em uma mensagem no Slack. Já vi mais senhas de proxy vazarem em canais do Slack do que gostaria de admitir.
Como usar cURL com proxy HTTP ou HTTPS
Esta é a configuração mais comum e a que você vai usar na imensa maioria das tarefas com proxy.
Usando a flag -x / --proxy
A sintaxe básica é esta:
curl -x "http://user:pwd@proxy.example:8080" "https://httpbin.org/ip"
-x e --proxy fazem exatamente a mesma coisa — use a que for mais fácil de lembrar. Como HTTP é o esquema de proxy padrão do cURL, tecnicamente você pode até omitir o prefixo http:// e escrever apenas proxy.example:8080. Ainda assim, eu deixaria isso explícito, porque daqui a seis meses você vai agradecer pela clareza.
Coloque a URL inteira entre aspas duplas. Se a sua senha contiver @, # ou &, uma string sem aspas pode ser modificada pelo shell antes mesmo de o cURL vê-la.
Conectando por meio de um proxy HTTPS
Alguns provedores fazem a conexão até o proxy via TLS, e não apenas a conexão do proxy até o destino. Isso é diferente de acessar um site HTTPS — o protocolo do proxy e o protocolo do destino são variáveis independentes. Para especificar isso:
curl -x "https://user:pwd@proxy.example:8080" "https://httpbin.org/ip"
Se aparecer um erro de certificado aqui, resista à tentação de simplesmente colocar -k e seguir em frente. Essa flag desativa totalmente a verificação de certificado SSL, o que até pode servir para um teste local rápido, mas é uma péssima ideia para qualquer coisa que toque produção ou dados reais de usuários. Se você estiver lidando com um proxy corporativo que intercepta TLS (uma configuração MITM, comum em ambientes empresariais), a correção certa é importar o certificado CA do proxy, e não desligar a verificação.
Autenticação com --proxy-user
Você também pode separar as credenciais em uma flag própria, em vez de colocá-las na URL:
curl -x "http://proxy.example:8080" --proxy-user "user:pwd" "https://httpbin.org/ip"
Repare que o -U maiúsculo não é o mesmo que a autenticação do site de destino (-u / --user, em minúsculo) — confundir esses dois é uma forma fácil de mandar sua senha de proxy para o destino errado. Em ambientes corporativos que usam NTLM ou Digest em vez de Basic, adicione --proxy-ntlm ou --proxy-digest junto com --proxy-user.
Como usar cURL com proxy SOCKS: SOCKS4 vs. SOCKS5 vs. socks5h
Proxies SOCKS operam em um nível mais baixo que proxies HTTP — eles não se importam com o protocolo que você está tunelando, o que os torna úteis para tráfego não HTTP, circuitos Tor e qualquer situação sensível à privacidade. Muitos guias concorrentes resumem isso em um comando e pronto. Isso é um erro, porque as diferenças entre SOCKS4, SOCKS5 e socks5h:// realmente importam.
| Recurso | SOCKS4 | SOCKS5 | socks5h:// |
|---|---|---|---|
| Suporte a TCP | Sim | Sim | Sim |
| Suporte a UDP | Não | Sim | Sim |
| Autenticação | Não | Sim | Sim |
| Resolução remota de DNS | Não | Não (DNS local) | Sim (o proxy resolve) |
| Compatível com Tor | Não | Arriscado (vazamento de DNS) | Sim |
A linha da resolução de DNS é a que realmente pega muita gente. Com socks5://, sua máquina resolve o hostname antes de entregar a conexão ao proxy — o que significa que seu resolvedor DNS local (e, por extensão, seu provedor de internet) vê exatamente qual domínio você está tentando acessar, mesmo que o tráfego HTTP real passe pelo proxy. O socks5h:// corrige isso ao fazer o proxy resolver o hostname, evitando qualquer vazamento local sobre o destino. É por isso que a documentação do Tor insiste em socks5h:// — usar socks5:// puro compromete uma boa parte do anonimato que o Tor deveria oferecer.
Veja cada variação no cURL:
curl --socks4 "proxy.example:1080" "http://example.com"
curl -x "socks5://user:pwd@proxy.example:1080" "http://example.com"
curl -x "socks5h://user:pwd@proxy.example:1080" "http://example.com"
A menos que você tenha um motivo específico para não fazer isso, use socks5h:// por padrão. Não custa nada a mais e elimina um vazamento que você provavelmente nunca perceberia.
Definindo proxy com variáveis de ambiente (e evitando as armadilhas)
Colocar -x em cada comando fica cansativo muito rápido. Variáveis de ambiente permitem definir o proxy uma vez por sessão de shell e fazer com que todas as chamadas seguintes do cURL herdem essa configuração automaticamente — o manual do cURL documenta http_proxy, HTTPS_PROXY, ALL_PROXY e NO_PROXY como o conjunto suportado.
O básico
export http_proxy="http://user:pwd@proxy.example:8080"
export HTTPS_PROXY="http://user:pwd@proxy.example:8080"
export ALL_PROXY="socks5h://proxy.example:1080"
Aqui está o ponto que confunde as pessoas o tempo todo: o nome da variável se refere ao protocolo da URL de destino, não ao protocolo do proxy. Então http_proxy controla requisições para URLs http://, e HTTPS_PROXY controla requisições para URLs https:// — você pode apontar ambas para o mesmo servidor proxy HTTP, e isso é totalmente normal.
Ignorando com NO_PROXY
export NO_PROXY="localhost,127.0.0.1,.internal.example"
Separado por vírgulas, e o ponto inicial em .internal.example funciona como curinga para qualquer subdomínio. NO_PROXY sobrepõe o resto — mesmo que -x esteja definido explicitamente na linha de comando, uma correspondência em NO_PROXY vai ignorar o proxy para aquela requisição.
As armadilhas que realmente pegam as pessoas
- Esquecer
export. Se você apenas digitarhttp_proxy=http://...semexport, a variável fica somente no shell atual e é totalmente invisível para o cURL como processo filho. Na minha experiência, esse é o motivo mais comum por trás de chamados do tipo “o proxy não está funcionando”. - Sensibilidade a maiúsculas e minúsculas. O cURL verifica especificamente primeiro a variável em minúsculas
http_proxye dá prioridade a ela se ambas as versões existirem. Algumas outras ferramentas só leem a versão em maiúsculas. Se você estiver depurando por que uma variável “não está sendo lida”, procure uma duplicata com capitalização diferente. - A armadilha do alias do PowerShell. No PowerShell 5.1, digitar
curlnão chama o cURL de verdade — ele executaInvoke-WebRequest, uma ferramenta completamente diferente, com flags diferentes. Se sua flag-xestiver gerando erros estranhos no Windows, digitecurl.exeexplicitamente para garantir que você está de fato executando o cURL. - Diferenças de sintaxe no Windows. No CMD, usa-se
set http_proxy=...; no PowerShell, usa-se$env:http_proxy = "...". Misturar essas sintaxes entre sessões de terminal é uma maneira fácil de perder uma tarde. - Variáveis antigas.
unset http_proxyeunset https_proxylimpam uma configuração de proxy obsoleta que está encaminhando — e falhando — silenciosamente em todas as requisições.
Para alternar rapidamente, alguns aliases no seu .bashrc economizam bastante tempo:
alias proxyon='export http_proxy="http://proxy.example:8080"; export https_proxy="http://proxy.example:8080"'
alias proxyoff='unset http_proxy; unset https_proxy'
Fazendo o cURL usar proxy sempre (arquivo de configuração)
Se você fica atrás de um proxy corporativo em 95% do tempo, um arquivo .curlrc (em sistemas Unix-like, na sua pasta pessoal) ou _curlrc (no Windows, na pasta app-data) define um padrão persistente sem mexer em variáveis de ambiente:
proxy="http://proxy.example:8080"
Para qualquer requisição pontual em que você precise ignorá-lo, --noproxy "*" sobrepõe a configuração apenas para aquela execução. A precedência normalmente segue: flag na linha de comando > variável de ambiente > arquivo de configuração, então -x na linha de comando sempre vence em caso de conflito.
Uma cautela importante: não coloque uma senha em texto puro dentro do .curlrc se esse arquivo estiver em um lugar que possa ser sincronizado, fazer backup ou ser enviado por engano a um repositório. Para pipelines de CI, use o gerenciador de segredos da sua plataforma e injete as credenciais como variáveis de ambiente mascaradas.
Como verificar se o proxy realmente está funcionando
Esta é a parte que quase todos os outros guias pulam — e a que mais economiza tempo de depuração. Configurar um proxy e assumir que ele está roteando o tráfego é como passar horas resolvendo problemas em um scraper que nunca usou proxy de verdade.
Método 1: comparar o IP de saída
Execute a mesma requisição de eco de IP duas vezes — uma direta e outra via proxy — e compare:
curl https://httpbin.org/ip
curl -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip
Se os dois comandos retornarem o mesmo endereço IP, seu proxy não está fazendo nada. Verifique a sintaxe da flag, suas variáveis de ambiente ou se NO_PROXY está correspondendo ao destino por engano.
Método 2: ler a saída detalhada
Adicione -v a qualquer requisição com proxy e o cURL vai imprimir o handshake completo:
curl -v -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip
Procure por uma linha como * Connected to proxy.example (xx.xx.xx.xx) port 8080, seguida de > CONNECT httpbin.org:443 HTTP/1.1 e, por fim, < HTTP/1.1 200 Connection established. Essa sequência — conectar ao proxy e depois abrir o túnel CONNECT até o destino — é o método HTTP CONNECT em ação, exatamente o que deve acontecer quando um destino HTTPS é roteado por um proxy HTTP. Se a linha CONNECT nunca aparecer, a flag de proxy não está sendo aplicada. Um cuidado aqui: use -v apenas enquanto estiver depurando ativamente e oculte a saída antes de compartilhar em qualquer lugar — o modo verboso pode exibir credenciais do proxy em texto puro.
Método 3: comparar lado a lado
Para testes geográficos, salve as duas saídas em arquivos e compare com diff:
curl https://httpbin.org/ip > direct.json
curl -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip > proxied.json
diff direct.json proxied.json
Se os corpos da resposta (ou os cabeçalhos, no caso de conteúdo com restrição geográfica) forem diferentes, você terá confirmação visual de que o proxy realmente alterou o caminho da sua rede — uma maneira rápida e de baixo esforço de encerrar qualquer dúvida antes de investigar mais a fundo.
Solução de problemas de erros comuns de proxy no cURL
A maioria dos guias faz rodeios aqui e menciona -k uma vez. Esse assunto merece uma tabela de referência de verdade.
| Erro | Causa provável | Correção |
|---|---|---|
curl: (7) Failed to connect | Host/porta do proxy incorretos, ou o proxy está fora do ar | Verifique o endereço; teste a conectividade bruta com telnet host port ou nc -zv host port |
407 Proxy Authentication Required | Credenciais do proxy ausentes ou incorretas | Adicione --proxy-user user:pass; veja se o provedor exige NTLM/Digest/Negotiate em vez de Basic |
curl: (56) Recv failure: Connection reset by peer | O proxy derrubou a conexão no meio da transferência | Verifique a estabilidade do proxy com o provedor; se for um proxy que encerra TLS, confirme o tratamento de certificados em vez de desativá-lo na marra |
curl: (28) Connection timed out | Firewall bloqueando, proxy obsoleto ou porta errada | Execute env | grep -i proxy para verificar variáveis sobrando; remova as antigas; teste uma requisição direta para isolar a causa |
| Falha na verificação de certificado | Certificado do proxy não confiável ou que intercepta a conexão | Obtenha a cadeia CA correta e use --proxy-cacert; evite desativar a verificação fora de um diagnóstico pontual |
A primeira ação universal para qualquer um desses casos é adicionar -v. Isso mostra exatamente onde a conexão está quebrando — resolução de DNS, conexão TCP, handshake TLS ou troca de autenticação com o proxy — em vez de deixar você adivinhar com base em um código de três dígitos.
Para proxies corporativos especificamente, --proxy-ntlm e --proxy-negotiate cobrem esquemas de autenticação de domínios Windows. Uma coisa que o cURL realmente não lida nativamente: arquivos PAC (scripts de Proxy Auto-Config que algumas empresas usam para atribuir proxies dinamicamente). Se a sua empresa usa um, você vai precisar extrair manualmente o host e a porta reais do proxy — normalmente nas configurações de rede do navegador — já que o cURL não tem um parser PAC embutido.
Quando cURL + proxy não é suficiente
cURL com proxy lida muito bem com HTML estático, chamadas de API REST e buscas simples de dados. Onde ele perde força é nas defesas preferidas da web moderna: aplicações de página única renderizadas por JavaScript, sistemas anti-bot como Cloudflare ou Akamai e barreiras de CAPTCHA. Se você apontar o cURL para um app em React ou Vue atrás de uma dessas proteções, vai receber de volta um <div id="root"></div> vazio — tecnicamente uma requisição bem-sucedida, na prática, dados inúteis. Isso não é um bug do cURL. Ele simplesmente não é um navegador e nunca fingiu ser.
Se você já se sente confortável rodando cURL no terminal e chegou a esse limite, o próximo passo natural não é trocar para uma pilha totalmente diferente — é adicionar uma camada que cuide da renderização e da estrutura para você. É exatamente essa lacuna que as ferramentas de desenvolvedor da Thunderbit foram criadas para preencher.
| Cenário | cURL + Proxy | API da Thunderbit (POST /extract) |
|---|---|---|
| Página HTML estática | Funciona perfeitamente | Funciona e ainda retorna dados estruturados |
| SPA renderizada por JS | Retorna HTML vazio/parcial | renderMode: "full" lida com o JS |
| Anti-bot / CAPTCHA | Bloqueado | Tratamento embutido |
| Saída de dados estruturados | HTML bruto — você precisa analisar | JSON com seu próprio esquema |
| Lote (100+ URLs) | Loop manual + sua própria limitação de taxa | POST /batch/extract |
A Open API da Thunderbit expõe um endpoint /extract que devolve JSON alinhado ao esquema diretamente de páginas pesadas em JavaScript, e um endpoint /distill para conversão limpa em Markdown — ambos podem ser chamados da mesma sessão de terminal em que você já vinha executando comandos cURL. Há também um servidor MCP para assistentes de programação com IA, como Claude ou Cursor, e uma CLI (npx @thunderbit/thunderbit-cli extract <url> --schema fields.json) se você preferir permanecer totalmente em scripts. Nada disso substitui o cURL nas tarefas em que ele é excelente — apenas assume o ponto em que o cURL estruturalmente não consegue avançar. Se você quiser uma visão mais ampla de onde a extração assistida por IA se encaixa em relação a escrever sua própria lógica de scraping, nosso panorama sobre web scraping com IA e a comparação das melhores ferramentas de web scraping com IA cobrem isso com mais profundidade, e nosso artigo sobre web scraping sem código é uma boa introdução se você vem mais do lado de negócios do que de engenharia.
Conclusão
Fazer cURL e proxy conversarem corretamente não é difícil quando você entende onde realmente estão os pontos de falha — e, no fim das contas, quase nenhum deles está no proxy em si. Esquecer export. Confundir -u com -U. Usar socks5:// quando queria socks5h://. Rodar o alias curl do PowerShell em vez de curl.exe. Cada um desses casos gera um erro confuso e genérico que não tem nada a ver com o provedor de proxy.
O hábito que mais economiza tempo: verifique antes de sair depurando. Faça o teste de eco de IP, dê uma olhada na saída de -v, confirme se o proxy realmente está no caminho da requisição antes de assumir que algo quebrou depois. E quando o seu destino começar a devolver JavaScript em vez de HTML limpo, isso não é um problema de cURL a ser resolvido com mais flags — é um sinal para usar uma ferramenta construída para renderização, como a API da Thunderbit, que oferece um plano gratuito se você quiser ver na prática a diferença entre receber JSON e receber HTML bruto.
Perguntas frequentes
O cURL usa proxy por padrão?
Não. A menos que você tenha definido variáveis de ambiente http_proxy / HTTPS_PROXY ou configurado um arquivo .curlrc, o cURL se conecta diretamente ao destino, sem proxy.
Como faço para impedir o cURL de usar proxy em uma única requisição?
Adicione --noproxy "*" a esse comando específico. Para limpar isso em toda a sessão do shell, execute unset http_proxy && unset https_proxy.
Posso usar cURL com proxies rotativos?
Sim — se o seu provedor oferecer um gateway rotativo (um endpoint único que atribui um IP novo a cada requisição), basta apontar -x para esse endereço como qualquer outro proxy. Para lógicas de rotação mais complexas em destinos renderizados por JS, uma camada de API como a da Thunderbit cuida internamente da rotação e da proteção anti-bot, então você não precisa gerenciar a lógica de repetição manualmente.
Por que socks5:// vaza minhas requisições DNS, mas socks5h:// não?
Com socks5://, sua máquina local resolve o hostname de destino antes de enviar a solicitação de conexão ao proxy — o que significa que o resolvedor DNS do seu provedor vê o domínio que você está visitando. O socks5h:// transfere a resolução do hostname para o próprio proxy, então nada sobre o destino fica visível localmente.
É legal usar cURL com proxy?
Usar proxy é legal na maioria das jurisdições, por si só. O que importa é o que você faz com ele — sempre respeite os termos de serviço do site-alvo, o robots.txt quando aplicável e qualquer lei de privacidade de dados relevante. Este guia cobre apenas a mecânica técnica, não um aval jurídico para qualquer caso de uso específico.
Saiba mais
