Se você está tentando baixar um modelo através do ollama pull
de uma rede corporativa, por VPN ou através de um servidor proxy externo, você provavelmente já se deparou com erros como
dial tcp: lookup registry.ollama.ai ou
context deadline exceeded.
O Ollama, por padrão, nem sempre captura corretamente as configurações de proxy do sistema, e o grande tamanho dos modelos (de 2 a 70+ GB) agrava o problema —
a conexão é interrompida no meio do download. Neste artigo, vamos discutir como definir corretamente as variáveis de ambiente, configurar o proxy no Docker e no systemd,
além de decifrar os erros mais comuns de pull e suas soluções.
Como o Ollama funciona com rede e proxy
Ollama é um aplicativo cliente-servidor: o servidor local (ollama serve)
aceita comandos do CLI e executa solicitações de rede ao registro de modelos registry.ollama.ai e ao CDN, onde estão armazenadas as camadas (layers) dos modelos.
O comando ollama pull llama3 na verdade executa uma série de solicitações HTTPS,
semelhantes ao Docker pull: primeiro, é solicitado o manifesto do modelo, em seguida, as camadas binárias (arquivos GGUF de pesos) são baixadas sequencial ou paralelamente.
Um detalhe importante: as solicitações de rede são feitas pelo processo do servidor Ollama, e não pelo comando CLI. Isso significa que as variáveis de ambiente
com as configurações de proxy devem ser definidas onde o processo ollama serve
está em execução, e não no terminal de onde você chama ollama pull.
Se o serviço estiver em execução como uma unidade systemd ou em um contêiner Docker, a exportação da variável em uma sessão bash comum não terá efeito —
essa é a razão mais comum pela qual "o proxy parece configurado, mas o pull ainda não funciona".
Variáveis de ambiente HTTP_PROXY, HTTPS_PROXY, NO_PROXY
Ollama é escrito em Go, e a biblioteca HTTP padrão do Go lê as configurações de proxy das variáveis de ambiente clássicas:
HTTP_PROXY— proxy para solicitações HTTP comunsHTTPS_PROXY— proxy para solicitações HTTPS (é isso que é necessário para baixar modelos, pois o registro opera sobre TLS)NO_PROXY— lista de hosts que devem ser excluídos do proxy (por exemplo, a API local do Ollama em 127.0.0.1:11434)
O formato do valor: http://user:password@host:port para proxy com autenticação
ou socks5://host:port para SOCKS5. O Go suporta ambas as opções,
mas para SOCKS5 é importante que o binário do Ollama tenha sido compilado com suporte a esse proxy — na maioria das compilações atuais isso é verdade, mas em caso de erros, é melhor
testar primeiro em proxies HTTP/HTTPS para excluir essa variável.
Importante: especifique as variáveis tanto em minúsculas quanto em maiúsculas
(http_proxy e HTTP_PROXY).
Algumas distribuições do Linux leem apenas em minúsculas, enquanto aplicativos Go às vezes esperam em maiúsculas — é melhor definir ambas as opções para não ter dúvidas.
Configuração no Linux e macOS
Se você está executando o Ollama diretamente do terminal (não como um serviço do sistema), basta exportar as variáveis antes de iniciar o servidor:
export HTTP_PROXY="http://user:[email protected]:8000"
export HTTPS_PROXY="http://user:[email protected]:8000"
export http_proxy="http://user:[email protected]:8000"
export https_proxy="http://user:[email protected]:8000"
export NO_PROXY="localhost,127.0.0.1"
ollama serve &
ollama pull llama3
Para que as configurações sejam mantidas entre sessões, adicione essas linhas ao ~/.bashrc,
~/.zshrc ou ~/.profile
dependendo do shell que você está usando. Após editar, execute source ~/.bashrc
e reinicie o processo do Ollama — as variáveis de ambiente são lidas apenas na inicialização do processo, não há suporte para recarga a quente.
No macOS, se o Ollama estiver instalado como um aplicativo (e não através do Homebrew), as variáveis de ambiente do terminal podem não chegar ao processo,
iniciado através da GUI. Nesse caso, é mais seguro definir as variáveis através do launchctl setenv:
launchctl setenv HTTPS_PROXY "http://user:[email protected]:8000"
launchctl setenv HTTP_PROXY "http://user:[email protected]:8000"
# Depois disso, reinicie completamente o aplicativo Ollama (saia da bandeja, não apenas feche a janela)
Configuração no Windows
No PowerShell, as variáveis são definidas para a sessão atual com o comando:
$env:HTTP_PROXY="http://user:[email protected]:8000"
$env:HTTPS_PROXY="http://user:[email protected]:8000"
$env:NO_PROXY="localhost,127.0.0.1"
ollama pull mistral
Se o Ollama estiver em execução como um serviço em segundo plano (ícone na bandeja do sistema), as variáveis de sessão não são suficientes — o serviço inicia ao fazer login no sistema
antes de você abrir o PowerShell. É necessário definir as variáveis no nível do usuário ou do sistema através de
"Configurações → Sistema → Sobre → Configurações avançadas do sistema → Variáveis de ambiente", após o que você deve encerrar completamente o processo
ollama.exe através do gerenciador de tarefas e reiniciar o aplicativo.
Proxy para Ollama no Docker
Se o Ollama estiver em execução em um contêiner (um caso comum para implantações de servidor), as variáveis de ambiente do host não são automaticamente passadas para dentro do contêiner —
elas precisam ser explicitamente passadas através de -e ou na seção environment
no docker-compose:
docker run -d \
-e HTTP_PROXY="http://user:[email protected]:8000" \
-e HTTPS_PROXY="http://user:[email protected]:8000" \
-e NO_PROXY="localhost,127.0.0.1" \
-v ollama:/root/.ollama \
-p 11434:11434 \
--name ollama ollama/ollama
Da mesma forma no docker-compose.yml:
version: "3.8"
services:
ollama:
image: ollama/ollama
environment:
- HTTP_PROXY=http://user:[email protected]:8000
- HTTPS_PROXY=http://user:[email protected]:8000
- NO_PROXY=localhost,127.0.0.1
volumes:
- ollama:/root/.ollama
ports:
- "11434:11434"
volumes:
ollama:
Após alterar as variáveis, o contêiner precisa ser recriado (docker compose up -d --force-recreate),
um simples reinício não é suficiente, pois as variáveis de ambiente são fixadas na criação do contêiner.
Proxy para o serviço systemd do Ollama
Em servidores Linux, o Ollama é frequentemente instalado como um serviço systemd através do script de instalação oficial. Nesse caso, as variáveis de ambiente
são definidas através de um arquivo de override, e não através de export no terminal:
sudo systemctl edit ollama.service
No editor que se abre, adicione:
[Service]
Environment="HTTP_PROXY=http://user:[email protected]:8000"
Environment="HTTPS_PROXY=http://user:[email protected]:8000"
Environment="NO_PROXY=localhost,127.0.0.1"
Em seguida, aplique as alterações:
sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama --property Environment
O último comando mostrará quais variáveis o processo realmente vê — uma maneira conveniente de garantir que a configuração foi aplicada, antes de tentar novamente executar o pull.
Análise de erros de pull e suas soluções
Vamos analisar as mensagens de erro mais comuns ao baixar modelos através de um proxy e o que fazer com elas.
dial tcp: lookup registry.ollama.ai: no such host
A resolução DNS não está funcionando através do proxy — geralmente isso significa que a solicitação está tentando sair diretamente, ignorando o servidor proxy, ou que a máquina não tem acesso
ao DNS (rede corporativa fechada). Solução: verifique se HTTPS_PROXY
está realmente sendo capturado pelo processo (veja o comando systemctl show acima),
e se o servidor proxy é capaz de resolver domínios externos (proxies SOCKS5 resolvem DNS do seu lado, proxies HTTP também, mas alguns proxies locais não fazem isso).
proxyconnect tcp: dial tcp: connection refused
O Ollama está tentando se conectar ao proxy, mas recebe uma recusa. Verifique a porta e o host para erros de digitação, certifique-se de que o servidor proxy realmente está ouvindo na porta especificada externamente (e não apenas no localhost), e que o firewall não está bloqueando a conexão de saída para a porta do proxy.
407 Proxy Authentication Required
O proxy requer login e senha, mas eles não foram fornecidos ou foram fornecidos incorretamente. Verifique se a variável de ambiente contém o login e a senha incorporados na URL
no formato http://user:password@host:port, e se caracteres especiais na senha
(como @ ou :)
estão codificados através de URL-encoding (%40, %3A).
x509: certificate signed by unknown authority
Isso é um sinal de um proxy corporativo com inspeção TLS (MITM), que substitui o certificado SSL pelo seu próprio root. O cliente Go do Ollama não confia
nesse certificado. A solução é adicionar o certificado root corporativo ao armazenamento de certificados confiáveis do sistema
(no Linux, geralmente através de update-ca-certificates após copiar o arquivo .crt para
/usr/local/share/ca-certificates/). Desabilitar a verificação de certificados globalmente não é recomendado — isso abre caminho para a interceptação de tráfego.
context deadline exceeded / i/o timeout ao baixar uma camada
A conexão é interrompida no meio do download de uma grande camada do modelo (frequentemente arquivos de 4-40 GB). Esse erro quase sempre indica instabilidade ou baixa largura de banda do servidor proxy, e não do próprio Ollama. Proxies públicos gratuitos ou sobrecarregados interrompem longas sessões TCP, especialmente se o download levar mais de alguns minutos. Nesses casos, mudar para um canal mais estável pode ajudar — por exemplo, proxies de data center, que oferecem alta velocidade e conexão estável para baixar grandes arquivos sem interrupções.
Qual tipo de proxy escolher para o Ollama
A escolha do tipo de proxy depende da razão pela qual você precisa de um proxy para o Ollama. Se a tarefa é apenas contornar as restrições do firewall corporativo dentro da sua própria rede, qualquer proxy HTTP(S) estável servirá. Mas se o objetivo é contornar a geo-restrição do registro de modelos ou ocultar que a solicitação está vindo de um data center (alguns CDNs limitam a velocidade para faixas de IP conhecidas de provedores de nuvem), a escolha do tipo de proxy se torna crítica.
| Tipo de proxy | Velocidade | Quando usar para o Ollama |
|---|---|---|
| Data Center | Alta | Download de grandes camadas de modelos (4-40+ GB) sem interrupções, testes de diferentes localizações de DC |
| Residenciais | Média | Contornar geo-restrições do registro, quando o IP do data center é afetado por limites regionais |
| Móveis | Variável | Último recurso em caso de bloqueio total por faixas de IP de provedores, menos eficaz para grandes downloads devido a flutuações de velocidade |
Para a maioria dos cenários com o Ollama — quando você precisa apenas baixar um modelo de dezenas de gigabytes de forma estável — a escolha ideal continua sendo proxies de data center: eles oferecem a máxima largura de banda e latências mínimas, o que é crítico ao baixar grandes camadas binárias. IPs residenciais devem ser conectados apenas se os endereços de data center realmente estiverem sujeitos a restrições do lado do registro de modelos.
Diagnóstico de conexão
Antes de gastar tempo depurando o próprio Ollama, verifique o proxy diretamente através do curl — isso excluirá confusões entre problemas no aplicativo e problemas no próprio servidor proxy:
# Verificando a disponibilidade do registro através do proxy
curl -v -x http://user:[email protected]:8000 https://registry.ollama.ai/v2/
# Medindo a velocidade de download através do proxy
curl -x http://user:[email protected]:8000 -o /dev/null -w "%{speed_download}\n" https://registry.ollama.ai/v2/
# Executando ollama serve com log detalhado
OLLAMA_DEBUG=1 ollama serve
Se o curl recebe uma resposta com sucesso, mas ollama pull ainda falha —
o problema quase certamente está no fato de que as variáveis de ambiente não chegaram ao processo do servidor (o serviço está em execução com outro usuário, de outro shell
ou como uma unidade systemd sem override). Volte à seção sobre systemd e verifique a saída de systemctl show ollama --property Environment.
Se o curl também falhar ao baixar um arquivo grande ou mostrar uma velocidade instável — a causa está do lado do servidor proxy, e você deve considerar mudar para um provedor de proxy mais estável, voltado para a transferência de grandes volumes de dados.
Conclusão
A configuração do Ollama por proxy se resume a três pontos-chave: as variáveis de ambiente devem ser definidas especificamente para o processo
ollama serve, e não para o terminal onde você chama o pull;
o formato da URL do proxy deve incluir login e senha corretamente codificados; e em caso de erros de certificados, você deve adicionar o
certificado root corporativo ao armazenamento de confiança, e não desativar a verificação TLS. A maioria dos erros de pull não são bugs do próprio Ollama,
mas sim consequências de que as configurações de rede não foram aplicadas ao processo correto ou que o servidor proxy não suporta a transferência prolongada de grandes arquivos.
Se sua principal tarefa é baixar modelos de dezenas de gigabytes de forma estável e rápida, recomendamos experimentar proxies de data center — eles oferecem alta largura de banda, necessária para o download de grandes camadas de modelos. E se a razão para usar um proxy é contornar as geo-restrições do registro de modelos, preste atenção aos proxies residenciais, que raramente são afetados por limites regionais aplicados a faixas de IP de provedores de nuvem.