---
title: "Configurar proxy no Git: como usar o Git atrás de um proxy"
description: "Configure o proxy do Git com git config --global http.proxy http://user:pass@host:port. Regras por host, NO_PROXY, socks5h, remotos SSH e erros comuns."
url: https://proxynet.io/pt-br/blog/git-proxy-settings
date: 2026-11-19
author: "Acar Diveroli"
category: "Tutoriais"
lang: pt-BR
---

# Configurar proxy no Git: como usar o Git atrás de um proxy

Num notebook de trabalho novo, o `git clone` fica parado por vinte segundos e depois desiste com `Failed to connect to … :443`. O navegador da mesma máquina abre a página do repositório sem dificuldade, porque o navegador conhece o proxy da empresa e o Git não. O mesmo acontece num servidor de build que só pode sair por um único gateway, ou quando um servidor Git próprio aceita conexões de um só endereço liberado na sua lista de permissões.

Este guia mostra o `http.proxy` e seus escopos, as regras por host, as variáveis de ambiente que o Git lê e qual delas vence, SOCKS5, credenciais com caracteres especiais, remotos SSH, a remoção das configurações e os textos exatos dos erros. Cada comando foi executado com o Git 2.56 no Windows 11 contra pequenos proxies de teste em 127.0.0.1, com um arquivo de configuração descartável, para que nenhuma configuração real do Git fosse alterada.

> **Nota: Resposta rápida**
>
> Execute `git config --global http.proxy http://user:pass@pr.proxynet.io:8000` para mandar todo `clone`, `fetch` e `push` via HTTPS por um proxy, e confira com `git config --global --get http.proxy`. Para restringir o proxy a um servidor, use `http.https://git.example.com.proxy`; para isentar um host, defina essa chave como uma string vazia. A configuração tem precedência sobre `https_proxy` e `all_proxy`, enquanto o `NO_PROXY` continua isentando os hosts que lista. Use `socks5h://` para um proxy SOCKS5 que também deva resolver nomes de host. Remotos que começam com `git@` usam SSH, que ignora o `http.proxy` e precisa de `ProxyCommand` ou `ProxyJump`.

## Quando o Git precisa de um proxy?

O Git precisa de um proxy sempre que a rede não o deixa alcançar o remoto diretamente, ou quando o remoto só aceita um endereço conhecido: uma rede corporativa com proxy de saída, um runner de CI numa sub-rede fechada, um servidor Git próprio que libera um único IP na lista de permissões. É comum o navegador funcionar enquanto o Git falha, porque o navegador segue o proxy do sistema e o Git lê apenas a própria configuração e algumas variáveis de ambiente.

O Git tem três maneiras de conversar com um remoto, e cada uma busca o proxy num lugar diferente. Antes de mudar qualquer coisa, veja a URL do remoto com `git remote -v`.

## Como o Git envia o tráfego por um proxy?

O Git entrega os remotos HTTP e HTTPS à libcurl, a biblioteca por trás do comando `curl`, então o tráfego HTTPS segue o fluxo normal de um proxy:

1. **O Git lê o endereço do proxy** em `http.<url>.proxy`, depois em `http.proxy`, depois nas variáveis de ambiente, e confere o host contra o `NO_PROXY`.
2. **Ele abre uma conexão TCP com o proxy** e, para um remoto `https://`, envia `CONNECT git.example.com:443`. Nosso proxy de teste registrou exatamente essa linha, com o user agent `git/2.56.0.windows.4`.
3. **Se o proxy responde `407`**, o Git repete o `CONNECT` com um cabeçalho `Proxy-Authorization` montado a partir das credenciais da URL do proxy.
4. **Depois de `200 Connection established`, o TLS acontece dentro do túnel.** O proxy vê o nome do host e a porta, não o conteúdo do repositório.
5. **O servidor Git vê o IP de saída do proxy**, e é isso que uma lista de permissões verifica.

| URL do remoto | Transporte | Configuração de proxy |
|---|---|---|
| `https://git.example.com/team/app.git` | HTTPS pela libcurl | `http.proxy`, variáveis de ambiente |
| `http://git.example.com/team/app.git` | HTTP pela libcurl | `http.proxy`, `http_proxy` |
| `git@git.example.com:team/app.git` | SSH | `ProxyCommand`, `ProxyJump` |
| `ssh://git@git.example.com/team/app.git` | SSH | `ProxyCommand`, `ProxyJump` |
| `git://git.example.com/app.git` | Protocolo Git | `core.gitProxy` |

## Como configurar um proxy no Git?

Defina o `http.proxy` com `git config`. O valor é uma URL no formato `[protocol://][user[:password]@]proxyhost[:port]`, como a [documentação do git-config](https://git-scm.com/docs/git-config) estabelece:

```bash
git config --global http.proxy http://user:pass@pr.proxynet.io:8000
git config --global --get http.proxy
```

Na nossa máquina de teste, o segundo comando devolveu a mesma URL, e o arquivo de configuração ganhou uma seção `[http]` com uma linha `proxy =`.

Não existe uma chave `https.proxy` separada no Git. O `http.proxy` cobre remotos HTTP e HTTPS, e o `http://` no início do valor descreve como o Git fala com o proxy, não com o remoto. Um proxy que espera TLS por conta própria recebe um valor `https://`, e o `http.proxySSLCAInfo` aponta o pacote de certificados usado para verificá-lo.

### Escopo global, de sistema ou de repositório

A opção define qual arquivo recebe a linha:

- **`--global`** grava em `~/.gitconfig` e vale para todos os repositórios da sua conta de usuário.
- **`--system`** grava no arquivo `etc/gitconfig` da instalação e vale para todos os usuários da máquina.
- **`--local`**, o padrão quando nenhuma opção é passada, grava em `.git/config` e vale só para o repositório atual.

Quando a mesma chave aparece em vários arquivos, o valor do repositório vence o global, que vence o do sistema. Um colega que "já configurou o proxy" mas continua sem conseguir clonar muitas vezes rodou o comando dentro de um único repositório, sem `--global`.

### Só para um comando

Para testar um proxy sem salvar nada, passe-o com `-c` antes do subcomando:

```bash
git -c http.proxy=http://user:pass@pr.proxynet.io:8000 ls-remote https://git.example.com/team/app.git
```

O `git ls-remote` só lista os branches de um remoto, então é um teste de conectividade rápido e inofensivo.

## Como usar um proxy só para um host?

Coloque o endereço do remoto dentro da chave: `http.<url>.proxy`. O Git compara cada URL de requisição com essas chaves e usa a correspondência mais específica, de modo que a mesma máquina alcança um host externo pelo proxy e um interno diretamente:

```bash
# proxy só para este host
git config --global http.https://git.example.com.proxy http://user:pass@pr.proxynet.io:8000

# proxy global, mas nunca para o servidor interno
git config --global http.proxy http://user:pass@pr.proxynet.io:8000
git config --global http.https://git.internal.example.proxy ""
```

Um valor vazio desliga o proxy para aquele endereço. No nosso teste, o host isento foi contatado diretamente mesmo com o `http.proxy` e a variável `https_proxy` apontando para um proxy, e o `git config --get-urlmatch http.proxy <url>` devolveu uma linha vazia para ele e o proxy para qualquer outro host.

A correspondência segue uma ordem fixa: esquema, host, porta, caminho e nome de usuário. Um `*` no host vale para um único nível de subdomínio (`https://*.example.com` cobre `git.example.com`, mas não `a.b.example.com`), e um caminho mais longo vence um mais curto. Um remoto também pode ter o próprio `remote.origin.proxy`; uma string vazia ali desativa o proxy para aquele remoto.

## O Git usa HTTP_PROXY, HTTPS_PROXY e NO_PROXY?

Sim. Quando o `http.proxy` não está definido, o Git pega o proxy das mesmas variáveis de ambiente que o curl: `https_proxy` para remotos HTTPS, `http_proxy` para remotos HTTP e `all_proxy` como alternativa para os dois. O `NO_PROXY` guarda uma lista de hosts separados por vírgula que devem ser acessados sem proxy.

Apontamos as variáveis e a configuração para dois proxies de teste diferentes e observamos qual recebia o `CONNECT`:

| Cenário | O que aconteceu |
|---|---|
| `https_proxy` e `http.proxy` definidos | Usou o `http.proxy` |
| Só `HTTPS_PROXY` (maiúsculas) | Usou o proxy |
| Só `HTTP_PROXY`, remoto HTTPS | Conexão direta |
| Só `all_proxy` | Usou o proxy |
| `http.proxy` mais `NO_PROXY=.internal.test` | Conexão direta |

Duas linhas surpreendem muita gente. O `HTTP_PROXY` sozinho não faz nada para um remoto HTTPS, então o clone sai direto. E o `NO_PROXY` também isenta hosts de um proxy definido na configuração do Git: útil para servidores internos, confuso quando um valor esquecido fica no perfil do seu shell. As entradas valem para o próprio host ou para qualquer host sob aquele domínio, então `internal.test` também cobre `git.internal.test`.

No Linux e no macOS, maiúsculas e minúsculas fazem diferença. A [documentação do curl sobre proxies](https://everything.curl.dev/usingcurl/proxies/env.html) explica que o `http_proxy` só é lido em minúsculas, porque um servidor web que roda um script CGI transforma um cabeçalho `Proxy:` recebido numa variável `HTTP_PROXY` em maiúsculas; as demais variáveis de proxy funcionam das duas formas. Na nossa máquina Windows a forma em maiúsculas também funcionou, já que o Windows não diferencia maiúsculas de minúsculas nos nomes de variáveis.

## Como usar um proxy SOCKS5 com o Git?

Escreva um esquema SOCKS na mesma chave `http.proxy`. A libcurl aceita `socks4://`, `socks4a://`, `socks5://` e `socks5h://`, e a diferença entre os dois últimos é onde o nome do host é resolvido:

```bash
git config --global http.proxy socks5h://user:pass@pr.proxynet.io:1080
```

Com `socks5://`, o Git consulta o endereço IP do remoto na sua máquina e pede ao proxy que se conecte a esse número. Com `socks5h://`, ele envia o nome do host e o proxy faz a resolução. Nosso servidor SOCKS de teste deixou a diferença visível: o mesmo `ls-remote` chegou como `CONNECT IPv4 104.20.23.154 port 443` com `socks5://` e como `CONNECT DOMAIN example.com port 443` com `socks5h://`.

Use `socks5h://` quando a sua rede não consegue resolver nomes externos ou quando as consultas DNS não devem sair da sua máquina. A [referência da libcurl sobre proxies](https://curl.se/libcurl/c/CURLOPT_PROXY.html) também observa que uma URL de proxy sem porta usa 1080 por padrão, então escreva sempre a porta do seu endpoint.

Um endpoint de [Proxies SOCKS5](https://proxynet.io/pt-br/socks5-proxy) entra na mesma chave; o funcionamento do protocolo passo a passo está em [Proxy SOCKS5:

o que é e como funciona](/pt-br/blog/socks5-proxy-101).

## Como passar as credenciais do proxy com segurança?

Coloque o nome de usuário e a senha na URL do proxy e aplique codificação percentual a todo caractere que tenha significado numa URL. Os mais comuns são `@` como `%40`, `:` como `%3A`, `#` como `%23`, `/` como `%2F` e o espaço como `%20`:

```bash
# senha p@ss:w#rd
git config --global http.proxy "http://user:p%40ss%3Aw%23rd@pr.proxynet.io:8000"
```

No nosso proxy de teste, a forma codificada chegou como `user:p@ss:w#rd`, exatamente como pretendido. A forma crua, `http://user:p@ss:w#rd@…`, nunca chegou ao proxy: o Git parou com `Invalid proxy URL … only SOCKS proxies support paths`, porque o primeiro `@` e o `#` quebraram a URL.

Uma senha no `~/.gitconfig` fica gravada em texto puro, então há duas saídas mais limpas. Deixe a senha de fora (`http://user@pr.proxynet.io:8000`) e o Git vai pedi-la pelo seu sistema de credenciais, o mesmo que guarda os logins dos repositórios; com os prompts desativados, nossa execução parou com `could not read Password … terminal prompts disabled`. Ou dispense as credenciais de vez: quando o IP da máquina está na whitelist do proxy, a URL é apenas `http://pr.proxynet.io:8000`. A Proxynet aceita até 10 IPs na whitelist, o que combina com um servidor de build de endereço fixo.

### anyauth ou basic?

O `http.proxyAuthMethod` define como o Git faz login. O padrão, `anyauth`, primeiro envia o `CONNECT` sem credenciais e espera um `407` que informe os métodos aceitos; o `basic` envia o usuário e a senha já na primeira requisição. Nossos proxies de teste mostraram quando isso importa:

| Comportamento do proxy | `anyauth` (padrão) | `basic` |
|---|---|---|
| 407 com desafio, conexão mantida | Funciona, duas requisições | Funciona, uma requisição |
| 407 com desafio, depois fecha | `Proxy CONNECT aborted` | Funciona |
| 407 sem `Proxy-Authenticate` | `response 407` | Funciona |

Se aparecer `Proxy CONNECT aborted` com a senha correta, tente primeiro `git config --global http.proxyAuthMethod basic`. O Basic envia a senha codificada em base64, não criptografada, então use-o apenas em redes confiáveis.

## O http.proxy funciona com remotos SSH?

Não. Um remoto como `git@git.example.com:team/app.git` roda sobre SSH, e o Git inicia o programa `ssh` para ele; o `http.proxy` e as variáveis de proxy nunca são consultados. Com o `http.proxy` definido, nosso teste SSH ignorou o proxy por completo e falhou com `ssh: Could not resolve hostname`. Se o SSH em si é novidade para você, [O que é SSH](/pt-br/blog/what-is-ssh) explica as chaves e a verificação do host.

O SSH tem duas opções de proxy próprias, descritas no [manual do ssh_config](https://man.openbsd.org/ssh_config):

- **`ProxyCommand`** roda um programa auxiliar que abre a conexão por um proxy; `%h` e `%p` representam o host e a porta de destino. O `nc` do OpenBSD, presente em muitos sistemas Linux e macOS, faz isso: `ProxyCommand nc -X connect -x pr.proxynet.io:8000 %h %p` para um proxy HTTP, `-X 5` para SOCKS5. O manual dele diz que a autenticação no proxy só funciona com proxies HTTP CONNECT, então a whitelist de IP é o caminho mais simples aqui.
- **`ProxyJump`** encaminha a conexão por outro servidor SSH (um host de salto, ou bastion) em vez de um proxy web: `ProxyJump user@jump.example.com`.

Coloque a linha sob um bloco `Host` no `~/.ssh/config` para que só o servidor Git a use:

```text
Host git.example.com
    ProxyCommand nc -X 5 -x pr.proxynet.io:1080 %h %p
```

Para um único repositório ou um único comando, passe a opção pelo `core.sshCommand` ou pela variável `GIT_SSH_COMMAND`. Na nossa máquina de teste usamos o `connect`, um pequeno programa auxiliar presente no ambiente Git daquela máquina, e os proxies registraram `CONNECT DOMAIN git.internal.test port 22` (SOCKS5) e `CONNECT git.internal.test:22` (HTTP). Alguns proxies HTTP só permitem `CONNECT` para a porta 443, então confirme que a porta 22 está liberada ou mude o remoto para HTTPS. O antigo protocolo `git://` tem a sua própria chave, `core.gitProxy`, raramente necessária hoje.

## Como verificar e remover as configurações de proxy do Git?

Leia o valor primeiro, incluindo de onde ele vem. Estes comandos respondem à maioria das dúvidas do tipo "por que o Git ainda usa o proxy antigo?":

```bash
git config --get http.proxy                     # valor que o Git usa neste repositório
git config --show-origin --get-all http.proxy   # cada valor e o arquivo onde ele está
git config --get-urlmatch http.proxy https://git.example.com/team/app.git
env | grep -i proxy                             # variáveis (PowerShell: Get-ChildItem env:*proxy*)
```

Remova um valor com `--unset` no mesmo escopo em que você o definiu:

```bash
git config --global --unset http.proxy
git config --global --unset http.https://git.example.com.proxy
git config --global --unset-all http.proxy      # se a chave aparecer mais de uma vez
```

Uma chave adicionada duas vezes faz o `--unset` simples recusar com `warning: http.proxy has multiple values`; o `--unset-all` apaga as duas. Remova as variáveis com `unset https_proxy` no bash ou `Remove-Item Env:https_proxy` no PowerShell, e apague a linha do perfil que as definia.

Para acompanhar a conversa com o proxy, rode um comando com `GIT_TRACE_CURL=1`. Por padrão, o Git oculta o cabeçalho `Proxy-Authorization` nesse rastreamento, mas trate a saída como sensível mesmo assim.

## Qual proxy combina com o tráfego do Git?

Um proxy com endereço de saída fixo é o que melhor combina com o Git, porque o motivo habitual para passar o Git por um proxy de terceiros é uma lista de permissões no servidor Git, num espelho de pacotes ou na rede de um parceiro. Os [Proxies de datacenter](https://proxynet.io/pt-br/datacenter-proxy) oferecem um endereço IPv4 dedicado que continua o mesmo entre clones e reinicializações, então a entrada na lista de permissões é escrita uma única vez; endereços rotativos trabalham contra esse objetivo.

Produtos vendidos por IP, como os proxies de datacenter, vêm por padrão com uma restrição de sites de destino, e o acesso a todos os sites é um adicional pago, então confirme que o seu host Git está acessível pelos seus IPs antes de ligá-lo à CI. Numa rede corporativa, o proxy mantido pela sua equipe de TI continua sendo a resposta certa.

## Onde você encontra as configurações de proxy do Git

Notebooks corporativos são o caso clássico: toda conexão de saída passa por um proxy que inspeciona o tráfego, e o Git é informado uma vez na configuração global. Em seguida vêm os runners de CI, normalmente por variáveis de ambiente na definição do job, para que o Git, o gerenciador de pacotes e o curl compartilhem uma única configuração. Servidores Git próprios e espelhos de artefatos que aceitam uma lista curta de endereços de origem precisam de um IP de saída estável, e equipes que trabalham por um bastion encontram o lado SSH, em que o `ProxyJump` substitui qualquer proxy web.

## Erros comuns de proxy no Git e como corrigi-los

Os textos abaixo são o que o Git 2.56 com a libcurl 8.23 exibiu na nossa máquina de teste depois de `fatal: unable to access '<url>':`. Versões mais antigas do curl escrevem alguns deles de forma um pouco diferente.

- **`Failed to connect to git.example.com:443 over proxy 127.0.0.1 after 0 ms: Could not connect to server`.** O próprio proxy está inacessível: porta errada, um firewall, ou o proxy caiu.
- **A mesma mensagem sem `over proxy`.** O Git não usou proxy nenhum. Verifique `--show-origin --get-all http.proxy`, o esquema da URL e o `NO_PROXY`.
- **`Could not resolve proxy: proxy.invalid`.** O nome do host do proxy não resolve.
- **`Could not resolve host: git.example.com`.** O Git saiu direto, ou um proxy `socks5://` precisa de uma consulta DNS que a sua rede não consegue fazer. Defina o proxy ou use `socks5h://`.
- **`CONNECT tunnel failed, response 407`.** O proxy recusou as credenciais ou não recebeu nenhuma. Verifique o nome de usuário, a codificação da senha e a whitelist de IP; [Como corrigir HTTP 407 Proxy Authentication Required](/pt-br/blog/http-407-proxy-authentication-required) percorre todas as causas.
- **`Proxy CONNECT aborted`.** Muitas vezes é o handshake `anyauth` falhando num proxy que fecha a conexão depois do seu 407. Defina `http.proxyAuthMethod` como `basic`.
- **`Invalid proxy URL … only SOCKS proxies support paths`.** Há um `@`, `#` ou `/` sem codificação na senha.
- **`cannot complete SOCKS5 connection to … (2)`.** O proxy SOCKS recusou o destino; o número é o código de resposta do SOCKS (2 significa "não permitido pelo conjunto de regras").
- **`SSL certificate problem: unable to get local issuer certificate`.** Um proxy que inspeciona TLS assina o tráfego de novo com um certificado da empresa em que o Git não confia. Aponte o `http.sslCAInfo` para um pacote com o certificado raiz da empresa ou, no Git for Windows, defina `http.sslBackend` como `schannel` para usar o repositório de certificados do Windows.
- **Uma espera longa que termina em timeout.** Um firewall descarta os pacotes, geralmente porque o Git sai direto numa rede que só permite passar pelo proxy.

O `http.sslVerify false` e o `GIT_SSL_NO_VERIFY` escondem o erro de certificado desligando a verificação que protege você de um ataque man-in-the-middle. Use-os no máximo para um único comando de diagnóstico, nunca como solução.

## Guia de decisão

| Necessidade | Recomendação |
|---|---|
| Todos os remotos HTTPS por um proxy | `git config --global http.proxy` |
| Só um host externo | `http.<url>.proxy` |
| Servidor interno precisa ir direto | `http.<url>.proxy` vazio ou `NO_PROXY` |
| Job de CI com várias ferramentas | Variáveis `https_proxy` e `NO_PROXY` |
| SOCKS5 com DNS no proxy | `socks5h://` no `http.proxy` |
| Nenhuma senha em arquivos de configuração | Whitelist de IP ou só o nome de usuário |
| `Proxy CONNECT aborted` | `http.proxyAuthMethod basic` |
| Remotos `git@` ou `ssh://` | `ProxyCommand` ou `ProxyJump` |
| Inspeção TLS da empresa | `http.sslCAInfo` ou `schannel` |

## Perguntas frequentes

### Como configuro um proxy no Git?

Execute `git config --global http.proxy http://host:port`, com `user:pass@` antes do host se o proxy exigir login. A configuração vale para todos os remotos HTTP e HTTPS da sua conta; confira com `git config --global --get http.proxy`.

### Como removo o proxy do Git?

Execute `git config --global --unset http.proxy`, com a mesma opção de escopo usada para defini-lo. Se o Git continuar usando um proxy, procure um valor de repositório com `git config --show-origin --get-all http.proxy` e verifique se há `https_proxy` ou `all_proxy` no seu ambiente.

### Existe uma configuração https.proxy no git config?

Não. A documentação do Git define apenas `http.proxy`, e essa única chave cobre remotos HTTP e HTTPS. Para um único host HTTPS, use `http.https://host.proxy`.

### Como uso um proxy SOCKS5 com o Git?

Defina o `http.proxy` como `socks5h://user:pass@host:port`; o `h` faz o proxy resolver os nomes de host. Isso cobre os remotos HTTPS, enquanto os remotos SSH precisam de `ProxyCommand` com um programa auxiliar compatível com SOCKS, como o `nc -X 5`.

### O Git usa as configurações de proxy do Windows?

Não conte com isso. A documentação do Git cita como fontes de proxy apenas as próprias chaves `http.proxy` e a família de variáveis `https_proxy`. Defina o `http.proxy` de forma explícita e teste com `git ls-remote`.

### Por que o git clone por SSH ignora o meu proxy?

Porque o `http.proxy` só afeta remotos HTTP e HTTPS. Remotos SSH precisam de uma linha `ProxyCommand` ou `ProxyJump` no `~/.ssh/config` ou no `core.sshCommand`; como alternativa, clone a URL HTTPS do mesmo repositório.

## Em resumo

O Git busca o proxy HTTPS no `http.proxy`, definido uma vez com `git config --global` e restrito a um host com `http.<url>.proxy`; um valor vazio ou o `NO_PROXY` isenta servidores internos, e a configuração tem precedência sobre o `https_proxy`. Aplique codificação percentual à senha, prefira `socks5h://` para SOCKS5, mude o `http.proxyAuthMethod` para `basic` quando o handshake for abortado e resolva erros de certificado com `http.sslCAInfo`, não desligando a verificação. Remotos SSH precisam de `ProxyCommand` ou `ProxyJump`. Teste cada mudança com `git ls-remote` antes de clonar algo grande.
