Clave API de Ollama: por qué no existe y qué usar en su lugar

Una instalación local de Ollama no tiene clave API ni forma integrada de configurarla. El servidor HTTP que ejecuta en http://localhost:11434 responde a cualquier solicitud que llegue a él. Las personas que buscan una «clave API de Ollama» suelen necesitar una de tres cosas: algo que ingresar en el campo obligatorio de clave de una aplicación cliente, una forma de proteger una instancia accesible desde otras máquinas o una clave para el servicio en la nube alojado de Ollama —el único lugar donde existe una clave real. Esta guía abarca las tres opciones.

Por qué Ollama local se distribuye sin autenticación

De forma predeterminada, Ollama se vincula a la dirección de bucle invertido 127.0.0.1 en el puerto 11434. Solo los procesos en la misma máquina pueden conectarse, por lo que una clave API añadiría fricción sin mejorar la seguridad: cualquier programa local capaz de leer un archivo de clave podría llamar a la API directamente con igual facilidad. Este es el mismo modelo de confianza utilizado por la mayoría de los servidores locales de desarrollo.

La consecuencia: no existe OLLAMA_API_KEY variable, sin bandera de clave ni opción de contraseña en ninguna parte de la configuración. En el momento de redactar este artículo, el servidor local de Ollama no incluye ningún mecanismo de autenticación integrado; proteger una instancia accesible desde la red es responsabilidad del usuario, como se explica a continuación. Si aún está configurando su entorno, comience con nuestra Guía de instalación de Ollama o la más amplia Guía completa de Ollama.

Qué ingresar en el campo de clave API de clientes compatibles con OpenAI

Ollama expone puntos finales compatibles con OpenAI bajo /v1, razón por la cual las interfaces gráficas de chat, los asistentes para programación y los SDK oficiales de OpenAI pueden comunicarse con él. Dichos SDK rechazan crear un cliente si no se proporciona una clave API no vacía: esta verificación se realiza en el lado del cliente, antes de enviar cualquier solicitud. Posteriormente, Ollama ignora por completo el encabezado Authorization , por lo que cualquier cadena de caracteres funciona. Por convención, se utiliza ollama.

Python, usando el SDK oficial de OpenAI:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # requerido por el SDK, ignorado por Ollama
)

response = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

JavaScript / TypeScript:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:11434/v1",
  apiKey: "ollama",
});

const response = await client.chat.completions.create({
  model: "llama3.2",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);

El modelo debe haberse descargado previamente (ollama pull llama3.2) o la solicitud fallará con un error «modelo no encontrado». Si no está seguro de qué comando ejecutar, consulte nuestras recomendaciones para los mejores modelos locales para Ollama.

Agregar autenticación real mediante un proxy inverso

Dado que Ollama no puede verificar claves por sí mismo, el patrón habitual consiste en mantenerlo vinculado únicamente a la interfaz de bucle local (loopback) y colocar un proxy inverso delante. Este proxy finaliza la conexión TLS, verifica un token y reenvía las solicitudes válidas a 127.0.0.1:11434. A continuación se muestra una configuración mínima de nginx que exige un token de tipo Bearer:

server {
    listen 443 ssl;
    server_name ollama.example.com;
    # líneas ssl_certificate y ssl_certificate_key omitidas

    location / {
        if ($http_authorization != "Bearer YOUR-LONG-RANDOM-TOKEN") {
            return 401;
        }
        proxy_pass http://127.0.0.1:11434;
        proxy_set_header Host $host;
        proxy_read_timeout 600s;
    }
}

Dos detalles son cruciales. Genere el token mediante un comando como openssl rand -hex 32 en lugar de inventarlo manualmente. Además, el valor elevado de proxy_read_timeout es intencional: las respuestas transmitidas en flujo (streaming) pueden tardar varios minutos, y los tiempos de espera predeterminados de los proxies interrumpirían dichas respuestas a mitad de proceso.

Lo elegante de esta solución es que los SDK de OpenAI ya envían la clave como Authorization: Bearer <clave>. Configure su cliente para apuntar a https://ollama.example.com/v1, establezca la clave API como el token real, y el campo de clave —que antes era ignorado— se convierte ahora en un mecanismo legítimo de autenticación, sin necesidad de modificar el código del cliente. Caddy y Traefik también pueden aplicar esta misma verificación del encabezado o la autenticación HTTP básica con apenas unas líneas de configuración propias; si ya utiliza alguno de ellos, emplee ese en lugar de añadir nginx.

Cambiar la dirección en la que escucha Ollama: Windows, macOS, Linux

Un proxy ubicado en la misma máquina no requiere cambios en la configuración de Ollama. Sin embargo, si otras máquinas deben acceder directamente a Ollama —por ejemplo, un proxy alojado en otro equipo, contenedores Docker o clientes de la red local (LAN)— configure OLLAMA_HOST=0.0.0.0 para que escuche en todas las interfaces. El método para hacerlo varía según la plataforma.

Windows

Cierre Ollama desde la bandeja del sistema. Abra Configuración, busque «variables de entorno» y seleccione «Editar variables de entorno para su cuenta». Añada una variable denominada OLLAMA_HOST con el valor 0.0.0.0, guarde los cambios y reinicie Ollama.

macOS

Las versiones recientes de la aplicación de escritorio incluyen un interruptor de configuración dentro de la app de Ollama para exponerla en la red; compruebe primero esta opción en la configuración de la aplicación. En instalaciones antiguas, ejecute launchctl setenv OLLAMA_HOST "0.0.0.0" y reinicie la aplicación de Ollama.

Linux

Para el servicio systemd instalado mediante el script oficial, ejecute sudo systemctl edit ollama.service y añada:

[Service]
Environment="OLLAMA_HOST=0.0.0.0"

A continuación, ejecute sudo systemctl daemon-reload && sudo systemctl restart ollama.

Una advertencia antes de activar esta opción: 0.0.0.0 activarla en una máquina con una dirección IP pública convierte su GPU en un recurso accesible públicamente. Configure su firewall para permitir el acceso al puerto 11434 únicamente desde los hosts que realmente lo necesiten.

Ollama Cloud: dónde se aplica una clave API real

Ollama Cloud ejecuta modelos demasiado grandes para la mayoría del hardware local en las GPUs de los propios centros de datos de Ollama, y constituye la única parte del ecosistema que dispone de claves API reales. Existen dos formas de acceder a él.

Mediante la CLI local. Ejecutar ollama signin para vincular su cuenta de ollama.com, y luego ejecute modelos alojados en la nube utilizando sus etiquetas específicas para la nube; por ejemplo, en el momento de redactar este artículo, ollama run gpt-oss:120b-cloud. Las solicitudes se asocian automáticamente a su cuenta, sin necesidad de gestionar manualmente claves.

Directamente mediante HTTPS. Genere una clave API en la sección «Claves API» de la configuración de su cuenta en ollama.com y envíela como token Bearer. La API alojada replica fielmente la API local, pero sustituyendo la URL base por https://ollama.com en lugar de localhost:11434:

curl https://ollama.com/api/chat 
  -H "Authorization: Bearer $OLLAMA_API_KEY" 
  -d '{
    "model": "gpt-oss:120b",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": false
  }'

La lista de modelos disponibles en la nube, los puntos finales y los límites de los planes cambian con el tiempo, por lo que debe considerar siempre la documentación oficial de la nube de Ollama como fuente autorizada sobre los nombres actuales de los modelos y las cuotas aplicables. Al decidir si la inferencia alojada o el hardware local resulta más adecuado para su carga de trabajo, nuestra calculadora de punto de equilibrio entre alojamiento local y API proporciona cifras concretas y la Calculadora de VRAM le indica si un modelo determinado cabe en su GPU o no.

El peligro real: una instancia sin autenticación expuesta a Internet

La verdadera historia de seguridad en torno a la clave API de Ollama no es la cadena de marcador de posición en su script de Python, sino los miles de servidores Ollama que escaneos globales de Internet detectan habitualmente escuchando en el puerto 11434 sin autenticación. Cualquiera que encuentre su servidor puede ejecutar inferencia en su GPU de forma gratuita, enumerar sus modelos mediante /api/tags, descargar modelos hasta que se llene su disco o eliminarlos. Además, cualquier vulnerabilidad futura del servidor será explotable sin credenciales: CVE-2024-37032, una vulnerabilidad de ejecución remota de código corregida en 2024, es un precedente al respecto.

• Deje el valor predeterminado 127.0.0.1 bind a menos que algo realmente requiera acceso remoto.
• Para acceso remoto personal, prefiera un túnel SSH (ssh -N -L 11434:127.0.0.1:11434 usuario@servidor) o una VPN como WireGuard o Tailscale, en lugar de abrir el puerto.
• Si debe ser accesible públicamente, coloque delante un proxy inverso autenticado y con terminación TLS, tal como se muestra arriba.
• Mantenga actualizado a Ollama para que las vulnerabilidades conocidas permanezcan parcheadas.

Preguntas frecuentes

¿Requiere Ollama una clave API?

No. Un servidor local de Ollama no tiene autenticación ni opción alguna para habilitarla. Las únicas claves API reales de Ollama son las de Ollama Cloud, generadas desde su cuenta en ollama.com.

¿Qué debo escribir en el campo de clave API requerido por un cliente?

Cualquier cadena no vacía — ollama por convención. Este requisito es puramente del lado del cliente; Ollama descarta dicho encabezado. Si ha configurado un proxy inverso con autenticación delante de Ollama, ingrese el token real del proxy, ya que los clientes compatibles con OpenAI envían la clave como un token de tipo bearer que el proxy puede verificar.

¿Puedo hacer que Ollama exija una clave API por sí mismo?

No, al menos por ahora. No existe ninguna variable de entorno, bandera ni opción de configuración que habilite la autenticación en el servidor local, pese a las numerosas solicitudes de los usuarios al respecto durante mucho tiempo. La solución aceptada es utilizar un proxy inverso delante del servidor.

¿Cómo obtengo una clave API de Ollama Cloud?

Cree una cuenta en ollama.com y genere una clave en la sección «Claves API» de la configuración de su cuenta. Envíela como Authorization: Bearer <clave> en las solicitudes dirigidas a https://ollama.com. Para usarlo desde la línea de comandos, ollama signin vincula su máquina a su cuenta sin necesidad de gestionar manualmente la clave.

¿Por qué el SDK de OpenAI lanza un error de autenticación antes de enviar nada?

El SDK valida la presencia de una clave API al crear el cliente, por lo que una clave vacía o ausente falla localmente, aunque Ollama no le daría importancia. Establezca api_key="ollama" (o cualquier cadena) y asegúrese de que la URL base termine en /v1.

¿Es seguro exponer Ollama en mi red doméstica?

En una LAN doméstica de confianza detrás de NAT, exponer Ollama con OLLAMA_HOST=0.0.0.0 es una configuración común y razonable. Verifique que su router no esté redirigiendo el puerto 11434 a esa máquina y recuerde que cualquier dispositivo de la red —incluidos los teléfonos de los invitados— podrá entonces usar y administrar sus modelos.