Documentazione

Open WebUI

Open WebUI tratta qualsiasi endpoint compatibile con OpenAI come una connessione. Aggiungine una in Impostazioni amministratore oppure imposta due variabili d’ambiente all’avvio del container: entrambi i percorsi portano allo stesso risultato.

Una connessione OpenAI in Admin Settings, oppure OPENAI_API_BASE_URL e OPENAI_API_KEY all'avvio del container — entrambe terminano sullo stesso /v1.

Connessione o docker run

# Settings → Admin Settings → Connections → Manage OpenAI API Connections → +
URL                https://api.kunavo.com/v1
API Key            sk-kn-...
Model IDs (Filter) claude-sonnet-5, claude-opus-5, claude-haiku-4-5, gpt-5-6-terra

# …or at container start, same thing:
docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=https://api.kunavo.com/v1 \
  -e OPENAI_API_KEY=sk-kn-... \
  -v open-webui:/app/backend/data \
  --name open-webui ghcr.io/open-webui/open-webui:main

Compila Model IDs (Filter). Senza questo campo, il selettore elenca l’intero catalogo, inclusi modelli di immagini, video e musica che una finestra di chat non può chiamare, e il primo clic dell’utente finisce su uno di questi. Il filtro serve anche quando un endpoint non dispone di una route /models; Kunavo ne ha una, quindi la verifica riesce in entrambi i casi.

L’URL mantiene /v1. Se Open WebUI è eseguito in Docker e lo stai indirizzando a qualcosa sullo stesso host, sostituisci localhost con host.docker.internal: questo non si applica a un endpoint ospitato, ma è il problema che si incontra subito dopo quello precedente.

Non hai ancora una chiave? Crea un account Kunavo, genera una chiave (inizia con sk-kn-) e aggiungi credito da $10: le chiamate vengono pagate con quel saldo e le chiamate non riuscite non vengono addebitate. La dashboard si apre quindi sulla configurazione Open WebUI.

Passo dopo passo

Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
In Open WebUI vai a Impostazioni → Amministrazione → Connessioni e individua Gestisci connessioni API OpenAI.
Fai clic su ➕ Aggiungi connessione e inserisci l’URL e la chiave API.
Aggiungi gli ID che vuoi a Model IDs (Filter), quindi salva e avvia la verifica della connessione.
Avvia una nuova chat: i modelli appariranno nel selettore con il nome della connessione come prefisso.

Verificato rispetto a Guida di Open WebUI ai provider compatibili con OpenAI il 6 settembre 2026. Le impostazioni di terze parti cambiano; se il nome di un campo qui non corrisponde più a quello visualizzato, fa fede quella pagina, non questa.

Verifica prima di eseguire il debug del client

Una sola richiesta stabilisce se il problema riguarda l'endpoint, la chiave o il file di configurazione. Se restituisce JSON, lo stesso base URL e la stessa chiave funzionano in Open WebUI.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Quale model id inserire nel campo

Ogni modello di testo è raggiungibile come model id: l'elenco aggiornato è GET /v1/models e il catalogo con i prezzi è nella pagina dei modelli. Le tariffe sono in USD per 1M di token, input / output.

ID del modello	Kunavo ingresso / uscita	Dove si inserisce in Open WebUI
`claude-sonnet-5`	$1.40 / $7.00	il modello predefinito per la chat generale
`claude-opus-5`	$3.50 / $17.50	conversazioni analitiche lunghe
`claude-haiku-4-5`	$0.70 / $3.50	veloce, economico e adatto alla maggior parte dei turni
`gpt-5-6-terra`	$0.70 / $4.20	documenti lunghi incollati nella finestra di chat

La fatturazione è per token, usando un saldo prepagato senza canone mensile: vedi billing. In presenza di contesto ripetuto, che costituisce la maggior parte di ciò che invia un editor o un client di chat, prompt caching incide sulla spesa più della scelta del modello.

Domande frequenti

Come si collega Open WebUI a un’API compatibile con OpenAI?

Vai a Impostazioni → Amministrazione → Connessioni, apri «Gestisci connessioni API OpenAI» e fai clic su Aggiungi connessione; quindi inserisci l’URL dell’endpoint, la radice /v1, e la chiave API. Puoi fare lo stesso all’avvio del container con le variabili d’ambiente OPENAI_API_BASE_URL e OPENAI_API_KEY. Entrambe le procedure creano la stessa connessione.

A cosa serve Model IDs (Filter) in Open WebUI?

Limita gli ID dei modelli di quella connessione che appaiono nel selettore ed è anche l’opzione di riserva per gli endpoint che non implementano una route /models: in quel caso aggiungi gli ID manualmente e la verifica non riesce, anche se la chat continua a funzionare. Su un gateway con un ampio catalogo multimodale, conviene impostarlo in ogni caso, così il selettore della chat elenca solo i modelli che una finestra di chat può effettivamente chiamare.

L’URL base di Open WebUI include /v1?

Sì. Open WebUI aggiunge all’URL fornito solo la route, quindi l’URL della connessione deve essere la radice /v1: https://api.example.com/v1. Gli endpoint degli esempi nella documentazione includono il suffisso. Senza di esso, la connessione viene salvata, ma ogni richiesta restituisce un 404.

Open WebUI può usare modelli Claude e GPT?

Sì, se vengono serviti tramite un endpoint compatibile con OpenAI. Open WebUI invia l’ID del modello direttamente all’URL della connessione, quindi gli ID di qualsiasi fornitore vengono risolti dall’endpoint, non da Open WebUI. Questo significa anche che una sola connessione e una sola chiave possono inserire gli ID Claude e GPT nello stesso selettore dei modelli.