Chiave API Ollama: perché non ne esiste una e cosa usare al suo posto

Un’installazione locale di Ollama non prevede alcuna chiave API né alcun metodo integrato per impostarne una. Il server HTTP che avvia http://localhost:11434 risponde a ogni richiesta che riceve. Chi cerca una «chiave API Ollama» ha generalmente bisogno di una delle seguenti tre cose: un valore da inserire nel campo obbligatorio della chiave API di un’app client, un modo per proteggere un’istanza accessibile da altre macchine oppure una chiave per il servizio cloud ospitato di Ollama — l’unico contesto in cui esiste effettivamente una chiave. Questa guida tratta tutti e tre i casi.

Perché Ollama locale viene distribuito senza autenticazione

Per impostazione predefinita, Ollama si associa all’indirizzo di loopback 127.0.0.1 sulla porta 11434. Solo i processi sulla stessa macchina possono connettersi, quindi una chiave API aggiungerebbe complessità senza migliorare la sicurezza: qualsiasi programma locale in grado di leggere un file contenente la chiave potrebbe altrettanto facilmente chiamare direttamente l’API. Si tratta dello stesso modello di fiducia adottato dalla maggior parte dei server di sviluppo locale.

La conseguenza: non esiste OLLAMA_API_KEY variabile, nessun flag per la chiave e nessuna opzione per la password in alcuna parte della configurazione. Al momento della stesura di questo articolo, il server Ollama locale non dispone affatto di un meccanismo di autenticazione integrato: proteggere un'istanza accessibile in rete è compito vostro, come illustrato più avanti. Se state ancora configurando il sistema, iniziate con la nostra Guida all’installazione di Ollama o con la più ampia Guida completa a Ollama.

Cosa inserire nel campo della chiave API dei client compatibili con OpenAI

Ollama espone endpoint compatibili con OpenAI all’indirizzo /v1, motivo per cui le interfacce utente per chat, gli assistenti per la programmazione e gli SDK ufficiali di OpenAI possono comunicare con esso. Tali SDK rifiutano di creare un client senza una chiave API non vuota — tale controllo avviene lato client, prima che qualsiasi richiesta venga inviata. Ollama, a sua volta, ignora completamente l’intestazione Authorization ricevuta, quindi qualsiasi stringa è accettabile. Per convenzione si utilizza ollama.

Python, usando l’SDK ufficiale di OpenAI:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # obbligatoria per l’SDK, ignorata da 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);

Il modello deve essere già stato scaricato (ollama pull llama3.2) altrimenti la richiesta fallirà con un errore «modello non trovato». Se non siete sicuri di cosa eseguire, consultate le nostre selezioni per i I migliori modelli locali per Ollama.

Aggiungere un’autenticazione reale tramite un reverse proxy

Poiché Ollama non può verificare autonomamente le chiavi, il metodo standard consiste nel lasciare Ollama in ascolto sull’interfaccia di loopback predefinita e inserire davanti ad esso un reverse proxy. Il proxy termina la connessione TLS, verifica un token e inoltra le richieste valide a 127.0.0.1:11434. Una configurazione minima di nginx che richiede un bearer token:

server {
    listen 443 ssl;
    server_name ollama.example.com;
    # righe ssl_certificate e ssl_certificate_key omesse

    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;
    }
}

Due dettagli sono fondamentali. Generare il token con uno strumento come openssl rand -hex 32 anziché inventarlo manualmente. Inoltre, il valore elevato di proxy_read_timeout è intenzionale: le generazioni in streaming possono durare diversi minuti e i timeout predefiniti dei proxy interromperebbero la risposta a metà.

L’aspetto elegante è che gli SDK di OpenAI inviano già la chiave sotto forma di intestazione Authorization: Bearer <key>. Basta puntare il client su https://ollama.example.com/v1, impostare la chiave API sul token reale e il campo precedentemente ignorato diventa un’autentica forma di autenticazione, senza modifiche lato client. Anche Caddy e Traefik possono applicare lo stesso controllo sull’intestazione o l’autenticazione HTTP basic con poche righe di configurazione propria; se ne state già utilizzando uno, preferitelo all’aggiunta di nginx.

Modificare l’indirizzo su cui Ollama ascolta: Windows, macOS, Linux

Un proxy sulla stessa macchina non richiede modifiche ad Ollama. Tuttavia, se altre macchine devono raggiungere Ollama direttamente — ad esempio un proxy su un altro host, contenitori Docker o client della LAN — impostare OLLAMA_HOST=0.0.0.0 affinché Ollama ascolti su tutte le interfacce. Il metodo per farlo varia a seconda della piattaforma.

Windows

Uscire da Ollama tramite l’icona nella barra delle applicazioni. Aprire le Impostazioni, cercare «variabili d’ambiente» e scegliere «Modifica variabili d’ambiente per il tuo account». Aggiungere una variabile denominata OLLAMA_HOST con valore 0.0.0.0, salvare le modifiche e riavviare Ollama.

macOS

Le versioni recenti dell’applicazione desktop includono un’opzione nelle impostazioni di Ollama per esporre il servizio sulla rete — controllare innanzitutto le impostazioni dell’app. Nei vecchi installati, eseguire launchctl setenv OLLAMA_HOST "0.0.0.0" e riavviare l’app Ollama.

Linux

Per il servizio systemd installato dallo script ufficiale, eseguire sudo systemctl edit ollama.service e aggiungere:

[Service]
Environment="OLLAMA_HOST=0.0.0.0"

Quindi eseguire sudo systemctl daemon-reload && sudo systemctl restart ollama.

Un avvertimento prima di attivare questa opzione: 0.0.0.0 su una macchina con indirizzo IP pubblico trasforma la vostra GPU in una risorsa pubblica. Proteggere la porta 11434 con un firewall, consentendo la connessione soltanto agli host autorizzati.

Ollama Cloud: dove si applica una vera chiave API

Ollama Cloud esegue modelli troppo grandi per la maggior parte dell’hardware locale sui GPU del proprio datacenter, ed è l’unica componente dell’ecosistema dotata di vere chiavi API. Esistono due modi per accedervi.

Tramite l’interfaccia a riga di comando locale. Esegui ollama signin per collegare il vostro account ollama.com, quindi eseguire modelli ospitati nel cloud utilizzando i relativi tag cloud — al momento della stesura di questo articolo, ad esempio ollama run gpt-oss:120b-cloud. Le richieste sono associate al vostro account; non è necessario gestire manualmente alcuna chiave.

Direttamente tramite HTTPS. Creare una chiave API nella sezione «Chiavi API» delle impostazioni del vostro account ollama.com e inviarla come bearer token. L’API ospitata replica quella locale, con https://ollama.com come URL base anziché 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
  }'

L’elenco dei modelli disponibili nel cloud, gli endpoint e i limiti dei piani cambiano nel tempo, pertanto la documentazione ufficiale di Ollama Cloud rappresenta la fonte autorevole per i nomi correnti dei modelli e i relativi limiti di utilizzo. Quando dovrete decidere se l’inferenza ospitata o l’hardware locale sia più adatto al vostro carico di lavoro, il nostro Calcolatore del punto di pareggio tra auto-hosting e API fornisce dati quantitativi, e il Calcolatore VRAM ti indica se un determinato modello è compatibile con la tua GPU.

Il vero rischio: un’istanza non autenticata esposta su Internet

La vera questione di sicurezza relativa alla chiave API di Ollama non riguarda la stringa segnaposto nel tuo script Python, bensì le migliaia di server Ollama che gli scanner su Internet individuano regolarmente in ascolto sulla porta 11434 senza alcuna autenticazione. Chiunque trovi il tuo server può eseguire inferenze gratuitamente sulla tua GPU, elencare i tuoi modelli tramite /api/tags, scaricare modelli fino a riempire il disco o eliminarli. Inoltre, qualsiasi futura vulnerabilità del server diventa sfruttabile senza credenziali: CVE-2024-37032, una vulnerabilità di esecuzione remota di codice corretta nel 2024, ne è un precedente.

• Lascia il valore predefinito 127.0.0.1 bind, a meno che non sia effettivamente necessario accedere in remoto.
• Per l’accesso remoto personale, preferisci un tunnel SSH (ssh -N -L 11434:127.0.0.1:11434 utente@server) oppure una VPN come WireGuard o Tailscale, anziché aprire la porta.
• Se deve necessariamente essere raggiungibile pubblicamente, posiziona davanti ad esso un reverse proxy autenticato e con terminazione TLS, come illustrato sopra.
• Mantieni Ollama aggiornato per assicurarti che le vulnerabilità note vengano corrette.

Domande frequenti

Ollama richiede una chiave API?

No. Un server Ollama locale non prevede alcuna autenticazione né alcuna opzione per abilitarla. Le uniche vere chiavi API di Ollama sono quelle di Ollama Cloud, generate nel tuo account su ollama.com.

Cosa devo inserire nel campo «chiave API» obbligatorio di un client?

Qualsiasi stringa non vuota — ollama per convenzione. Tale requisito è puramente lato client; Ollama ignora completamente l’intestazione. Se hai configurato davanti a Ollama un reverse proxy con autenticazione, inserisci invece il token reale del proxy, poiché i client di tipo OpenAI inviano la chiave come bearer token verificabile dal proxy.

Posso far sì che Ollama stesso richieda una chiave API?

Al momento no. Non esiste alcuna variabile d’ambiente, flag o opzione di configurazione che consenta di abilitare l’autenticazione sul server locale, nonostante le richieste degli utenti risalgano a molto tempo fa. La soluzione comunemente accettata consiste nell’utilizzare un reverse proxy davanti al server.

Come ottengo una chiave API di Ollama Cloud?

Crea un account su ollama.com e genera una chiave nella sezione «Chiavi API» delle impostazioni del tuo account. Inviala come Authorization: Bearer <key> nei tuoi request verso https://ollama.com. Per l’uso da CLI, ollama signin collega automaticamente il tuo dispositivo al tuo account, evitando la gestione manuale della chiave.

Perché l’SDK OpenAI genera un errore di autenticazione prima ancora di inviare qualsiasi richiesta?

L’SDK verifica la presenza di una chiave API al momento della creazione del client, quindi una chiave vuota o mancante causa un errore locale, anche se Ollama non ne farebbe alcun uso. Imposta api_key="ollama" (o qualsiasi altra stringa) e assicurati che l’URL base termini con /v1.

È sicuro esporre Ollama sulla mia rete domestica?

Su una LAN domestica attendibile e protetta da NAT, esporre Ollama con OLLAMA_HOST=0.0.0.0 è una configurazione comune e ragionevole. Verifica che il tuo router non stia inoltrando la porta 11434 verso quel dispositivo e ricorda che ogni dispositivo connesso alla rete — inclusi i telefoni degli ospiti — potrà quindi utilizzare e gestire i tuoi modelli.