← Volver al blog

Ollama con proxy: cómo configurar HTTP_PROXY y solucionar errores al descargar modelos

Análisis detallado de la configuración de Ollama detrás de un servidor proxy: desde variables de entorno hasta diagnóstico de errores al obtener modelos y elección del tipo de proxy adecuado.

📅16 de noviembre de 2026

Si estás intentando descargar un modelo a través de ollama pull desde una red corporativa, a través de una VPN o mediante un proxy externo, seguramente ya te has encontrado con errores como dial tcp: lookup registry.ollama.ai o context deadline exceeded. Ollama por defecto no siempre captura correctamente la configuración del proxy del sistema, y los grandes tamaños de los modelos (de 2 a 70+ GB) agravan el problema — la conexión se interrumpe a mitad de la descarga. En este artículo, analizaremos cómo establecer correctamente las variables de entorno, configurar el proxy en Docker y systemd, así como desglosar los errores más comunes de pull y sus soluciones.

Cómo Ollama trabaja con la red y el proxy

Ollama es una aplicación cliente-servidor: el servidor local (ollama serve) recibe comandos de la CLI y realiza solicitudes de red al registro de modelos registry.ollama.ai y al CDN, donde se almacenan las capas (layers) de los modelos. El comando ollama pull llama3 en realidad ejecuta una serie de solicitudes HTTPS, similares a Docker pull: primero se solicita el manifiesto del modelo, luego se descargan secuencial o paralelamente las capas binarias (archivos GGUF de pesos).

Un detalle importante: las solicitudes de red son realizadas por el proceso del servidor de Ollama, no por el comando de la CLI. Esto significa que las variables de entorno con la configuración del proxy deben establecerse donde se ejecuta el proceso ollama serve, y no en la terminal desde donde llamas a ollama pull. Si el servicio se ejecuta como una unidad systemd o en un contenedor Docker, exportar la variable en una sesión bash normal no tendrá efecto — esta es la razón más común por la que "el proxy parece estar configurado, pero el pull aún no funciona".

Variables de entorno HTTP_PROXY, HTTPS_PROXY, NO_PROXY

Ollama está escrito en Go, y la biblioteca HTTP estándar de Go lee la configuración del proxy de las clásicas variables de entorno:

  • HTTP_PROXY — proxy para solicitudes HTTP normales
  • HTTPS_PROXY — proxy para solicitudes HTTPS (es el que se necesita para descargar modelos, ya que el registro funciona por TLS)
  • NO_PROXY — lista de hosts que deben excluirse de la proxy (por ejemplo, la API local de Ollama en 127.0.0.1:11434)

Formato del valor: http://user:password@host:port para proxy con autenticación o socks5://host:port para SOCKS5. Go soporta ambas opciones, pero para SOCKS5 es importante que el binario de Ollama esté compilado con soporte para este proxy — en la mayoría de las compilaciones actuales esto es así, pero si hay errores, primero prueba con HTTP/HTTPS-proxy para descartar esta variable.

Importante: especifica las variables tanto en minúsculas como en mayúsculas (http_proxy y HTTP_PROXY). Algunas distribuciones de Linux solo leen en minúsculas, mientras que las aplicaciones de Go a veces esperan en mayúsculas — es mejor establecer ambas variantes para no adivinar.

Configuración en Linux y macOS

Si ejecutas Ollama directamente desde la terminal (no como un servicio del sistema), basta con exportar las variables antes de iniciar el 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 la configuración se mantenga entre sesiones, añade estas líneas a ~/.bashrc, ~/.zshrc o ~/.profile dependiendo del shell que estés utilizando. Después de editar, ejecuta source ~/.bashrc y reinicia el proceso de Ollama — las variables de entorno solo se leen al iniciar el proceso, no hay soporte para recarga en caliente.

En macOS, si Ollama está instalada como una aplicación (y no a través de Homebrew), las variables de entorno de la terminal pueden no llegar al proceso, iniciado a través de la GUI. En este caso, es más seguro establecer las variables a través de launchctl setenv:

launchctl setenv HTTPS_PROXY "http://user:[email protected]:8000"
launchctl setenv HTTP_PROXY "http://user:[email protected]:8000"
# Después de esto, reinicia completamente la aplicación Ollama (salir de la bandeja, no solo cerrar la ventana)

Configuración en Windows

En PowerShell, las variables se establecen para la sesión actual con el 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

Si Ollama se está ejecutando como un servicio en segundo plano (icono en la bandeja del sistema), las variables de sesión no son suficientes — el servicio se inicia al iniciar sesión antes de que abras PowerShell. Debes establecer las variables a nivel de usuario o sistema a través de "Configuración → Sistema → Acerca de → Configuración avanzada del sistema → Variables de entorno", después de lo cual debes finalizar completamente el proceso ollama.exe a través del administrador de tareas y reiniciar la aplicación.

Proxy para Ollama en Docker

Si Ollama se está ejecutando en un contenedor (un caso común para implementaciones en servidor), las variables de entorno del host no se transfieren automáticamente al contenedor — deben ser pasadas explícitamente a través de -e o la sección environment en 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

De manera similar en 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:

Después de cambiar las variables, el contenedor debe ser recreado (docker compose up -d --force-recreate), un simple reinicio no es suficiente, ya que las variables de entorno se fijan al crear el contenedor.

Proxy para el servicio systemd de Ollama

En servidores Linux, Ollama a menudo se instala como un servicio systemd a través del script de instalación oficial. En este caso, las variables de entorno se establecen a través de un archivo de sobreescritura, y no a través de export en la terminal:

sudo systemctl edit ollama.service

En el editor que se abre, añade:

[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"

Luego aplica los cambios:

sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama --property Environment

El último comando mostrará qué variables realmente ve el proceso — una forma conveniente de asegurarte de que la configuración se ha aplicado, antes de intentar nuevamente realizar el pull.

Análisis de errores de pull y su solución

Analizaremos los mensajes de error más comunes al descargar modelos a través de un proxy y qué hacer con ellos.

dial tcp: lookup registry.ollama.ai: no such host

La resolución DNS no funciona a través del proxy — generalmente significa que la solicitud intenta salir directamente, omitiendo el servidor proxy, o que la máquina no tiene acceso a DNS (red corporativa cerrada). Solución: asegúrate de que HTTPS_PROXY realmente está siendo capturada por el proceso (ver el comando systemctl show arriba), y que el servidor proxy puede resolver dominios externos (los proxies SOCKS5 resuelven DNS de su lado, los proxies HTTP también, pero algunos proxies locales no lo hacen).

proxyconnect tcp: dial tcp: connection refused

Ollama intenta conectarse al proxy, pero recibe un rechazo. Verifica el puerto y el host en busca de errores tipográficos, asegúrate de que el servidor proxy realmente está escuchando en el puerto especificado desde el exterior (y no solo en localhost), y que el firewall no está bloqueando la conexión saliente al puerto del proxy.

407 Proxy Authentication Required

El proxy requiere un nombre de usuario y una contraseña, pero no se han proporcionado o se han proporcionado incorrectamente. Asegúrate de que en la variable de entorno el nombre de usuario y la contraseña estén integrados en la URL en el formato http://user:password@host:port, y que los caracteres especiales en la contraseña (por ejemplo, @ o :) estén codificados a través de URL-encoding (%40, %3A).

x509: certificate signed by unknown authority

Esto es un signo de un proxy corporativo con inspección TLS (MITM), que reemplaza el certificado SSL por su raíz. El cliente Go de Ollama no confía en este certificado. La solución es agregar el certificado raíz corporativo al almacén de certificados de confianza del sistema (en Linux, generalmente a través de update-ca-certificates después de copiar el archivo .crt en /usr/local/share/ca-certificates/). Deshabilitar la verificación de certificados a nivel global no se recomienda — esto abre la puerta a la interceptación del tráfico.

context deadline exceeded / i/o timeout al descargar una capa

La conexión se interrumpe a mitad de la carga de una gran capa del modelo (a menudo son archivos de 4-40 GB). Este error casi siempre indica inestabilidad o baja capacidad del servidor proxy, y no de Ollama en sí. Los proxies públicos gratuitos o sobrecargados interrumpen sesiones TCP largas, especialmente si la descarga toma más de unos minutos. En tales casos, ayuda cambiar a un canal más estable — por ejemplo, proxies de centros de datos, que ofrecen alta velocidad y conexión estable para descargar archivos grandes sin interrupciones.

Qué tipo de proxy elegir para Ollama

La elección del tipo de proxy depende de la razón por la que necesitas un proxy para Ollama. Si el objetivo es simplemente eludir las restricciones del firewall corporativo dentro de tu propia red, cualquier proxy HTTP(S) estable funcionará. Pero si el objetivo es eludir la geo-bloqueo del registro de modelos o ocultar que la solicitud proviene de un centro de datos (algunos CDN limitan la velocidad para rangos de IP conocidos de proveedores de nube), la elección del tipo de proxy se vuelve crítica.

Tipo de proxy Velocidad Cuándo usar para Ollama
Centro de datos Alta Descarga de grandes capas de modelos (4-40+ GB) sin interrupciones, pruebas desde diferentes ubicaciones de DC
Residenciales Media Eludir geo-restricciones del registro, cuando la IP del centro de datos cae bajo el límite regional
Móviles Variable Último recurso en caso de bloqueo total por rangos de IP de proveedores, menos efectivo para grandes descargas debido a fluctuaciones de velocidad

Para la mayoría de los escenarios con Ollama — cuando solo necesitas descargar un modelo de decenas de gigabytes de manera estable — la opción óptima sigue siendo proxies de centros de datos: ofrecen la máxima capacidad de ancho de banda y latencias mínimas, lo cual es crítico al descargar grandes capas binarias. Las IP residenciales deben conectarse solo si las direcciones de centros de datos realmente caen bajo las restricciones del lado del registro de modelos.

Diagnóstico de conexión

Antes de perder tiempo depurando Ollama, verifica el proxy directamente a través de curl — esto eliminará la confusión entre un problema en la aplicación y un problema en el propio servidor proxy:

# Verificar la disponibilidad del registro a través del proxy
curl -v -x http://user:[email protected]:8000 https://registry.ollama.ai/v2/

# Medir la velocidad de descarga a través del proxy
curl -x http://user:[email protected]:8000 -o /dev/null -w "%{speed_download}\n" https://registry.ollama.ai/v2/

# Ejecutar ollama serve con registro detallado
OLLAMA_DEBUG=1 ollama serve

Si curl recibe una respuesta con éxito, pero ollama pull sigue fallando — el problema casi seguramente radica en que las variables de entorno no llegaron al proceso del servidor (el servicio se ejecuta con otro usuario, desde otro shell o como una unidad systemd sin sobreescritura). Regresa a la sección sobre systemd y revisa la salida de systemctl show ollama --property Environment.

Si curl también se interrumpe al descargar un archivo grande o muestra una velocidad inestable — la causa está del lado del servidor proxy, y deberías considerar cambiar a un proveedor de proxy más estable, orientado a la transferencia de grandes volúmenes de datos.

Conclusión

Configurar Ollama detrás de un proxy se reduce a tres puntos clave: las variables de entorno deben establecerse específicamente para el proceso ollama serve, y no para la terminal desde donde llamas a pull; el formato de la URL del proxy debe incluir correctamente codificados el nombre de usuario y la contraseña; y en caso de errores de certificados, se debe agregar el certificado raíz corporativo al almacén de confianza, en lugar de deshabilitar la verificación TLS. La mayoría de los errores de pull no son errores de Ollama en sí, sino consecuencia de que la configuración de red no se aplicó al proceso correcto o el servidor proxy no soporta la transferencia prolongada de archivos grandes.

Si tu objetivo principal es descargar modelos de decenas de gigabytes de manera estable y rápida sin interrupciones en la conexión, te recomendamos probar proxies de centros de datos — ofrecen una alta capacidad de ancho de banda, necesaria para cargar grandes capas de modelos. Y si la razón para usar un proxy es eludir las geo-restricciones del registro de modelos, presta atención a los proxies residenciales, que son menos propensos a caer bajo los límites regionales aplicados a los rangos de IP de proveedores de nube.