Installazione di Open WebUI e configurazione di OmniProxy

Open WebUI è un’interfaccia di chat che puoi distribuire autonomamente sul tuo computer o server e che può funzionare anche completamente offline. Non è vincolata a un singolo fornitore di modelli: può collegarsi sia a strumenti come Ollama, che eseguono i modelli localmente, sia a endpoint compatibili con il formato OpenAI, cioè servizi che forniscono modelli usando lo stesso formato di richiesta. In questo modo puoi passare dai modelli locali a quelli cloud nella stessa finestra.

È adatto all’utilizzo a lungo termine da parte di team e organizzazioni. Le funzionalità aggiornate più rapidamente vengono introdotte prima in Computer, il prodotto usato da Open WebUI per sperimentare nuove funzioni.

Preparazione all’installazione

Open WebUI può essere utilizzato su macOS, Linux e Windows. Puoi installarlo tramite Docker, Python o Kubernetes. Docker installa l’applicazione e il relativo ambiente di esecuzione in un container relativamente isolato ed è il metodo consigliato; se Docker non è disponibile, puoi usare anche il comando Python verificato riportato di seguito. Kubernetes è un sistema per distribuire e gestire container; i passaggi corrispondenti sono disponibili nel Quick Start indicato alla fine della guida.

Consigliato ufficialmente

Docker

Un solo docker run
Apri 3000 nel browser
I dati si trovano nel volume dati

Vuoi solo chattare

Immagine slim

Dimensioni di download inferiori
Cambia il tag in :slim
Le funzioni di chat sono ancora disponibili

Non approfondito qui

Altri due metodi

Installazione manuale con Python
Distribuzione con Kubernetes
Consulta Quick Start ufficiale

Installa prima Docker, quindi avvia il servizio con il comando consigliato. Se usi soltanto la chat tramite API, puoi cambiare il tag dell’immagine in slim.

Prima di iniziare, prepara quanto segue:

Docker già installato e funzionante.
Una stringa segreta riservata esclusivamente al tuo utilizzo. Generala eseguendo openssl rand -hex 32, quindi inseriscila in WEBUI_SECRET_KEY. Conserva questo valore senza modificarlo: se lo cambi quando ricrei il container, gli utenti che hanno già effettuato l’accesso verranno disconnessi.
Un’istanza di OmniProxy in esecuzione e l’ID del modello presente nel suo elenco attuale. L’ID del modello è il nome completo usato per selezionare un modello specifico.

Installazione e primo avvio

Apri il terminale ed esegui il comando del Quick Start. Prima sostituisci your-secret-key con la stringa segreta appena generata:

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data -e WEBUI_SECRET_KEY=your-secret-key --name open-webui --restart always ghcr.io/open-webui/open-webui:main

Le opzioni principali di questo comando svolgono le seguenti funzioni:

-p 3000:8080: consente di aprire l’interfaccia tramite la porta 3000 del computer. Se la porta 3000 è occupata, modifica il numero a sinistra.
-v open-webui:/app/backend/data: salva chat, utenti e impostazioni in un volume dati. Un volume dati conserva le informazioni al di fuori del container, anche dopo il suo aggiornamento; non rimuovere quindi questa opzione.
--add-host=host.docker.internal:host-gateway: consente al container di accedere agli altri servizi in esecuzione sul computer.
--restart always: riavvia il container dopo il riavvio del computer.

Dopo aver eseguito il comando, apri http://localhost:3000 nel browser e segui le indicazioni della pagina per creare il primo account.

Se utilizzi soltanto la chat tramite API, puoi cambiare il tag dell’immagine da :main a :slim. slim è un’immagine più piccola che non include i modelli locali per la voce e gli embedding all’interno del container, ma l’interfaccia di chat rimane disponibile. Se ti servono queste funzionalità locali, continua a usare :main.

Per eseguire un aggiornamento manuale, avvia prima docker rm -f open-webui, quindi docker pull ghcr.io/open-webui/open-webui:main e infine riavvia usando lo stesso comando docker run. Il volume dati e WEBUI_SECRET_KEY devono rimanere invariati.

Se Docker non è disponibile

Il Quick Start offre anche un metodo di installazione tramite Python. Il 2026-10-09, su macOS, il comando seguente ha installato Open WebUI v0.11.4 ed è stato usato per completare una conversazione. Docker Desktop non era installato su quel computer.

DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve

Dopo l’avvio, apri http://localhost:8080 nel browser. Questa è la porta usata dall’installazione Python, non la porta 3000 usata da Docker.

Al primo avvio verrà scaricato un modello di embedding e l’operazione potrebbe richiedere alcuni minuti. Il modello di embedding converte il testo in dati adatti alla ricerca e alla corrispondenza. Attendi che venga visualizzata la pagina di accesso prima di continuare; il primo account registrato diventerà amministratore. La lingua dell’interfaccia segue quella del sistema; durante questa prova è stata visualizzata in cinese semplificato.

DATA_DIR deve puntare a una directory conservata in modo permanente, usata per archiviare i dati di Open WebUI. Se non viene impostata, i dati potrebbero essere salvati in una directory temporanea e andare persi alla chiusura. Se WEBUI_SECRET_KEY non è impostata, il programma scrive .webui_secret_key nella directory corrente. Avvia il programma da una directory che intendi conservare oppure imposta direttamente questa variabile.

Ottenere i parametri di connessione da OmniProxy

Copia i tre valori seguenti dalla tua istanza di OmniProxy:

URL:      https://your-omniproxy-origin.example/v1
API Key:  <YOUR_OMNIPROXY_API_KEY>
Model ID: copia dall’elenco attuale dei modelli di OmniProxy

L’URL è l’indirizzo usato da Open WebUI per collegarsi all’API e deve terminare con /v1. Non aggiungere /chat/completions alla fine: Open WebUI aggiunge autonomamente questo segmento.

Copia per intero l’ID del modello dall’elenco attuale di OmniProxy. Se l’ID include un prefisso dell’origine e una barra, mantienili entrambi. I due nomi brevi seguenti sono soltanto riferimenti tratti dalla documentazione dei fornitori in data 2026-10-09; non usarli se non sono presenti nell’elenco attuale:

ID Claude API di Claude Sonnet 5.5: claude-sonnet-5-5
Nome dell’API di Gemini 3.8 Flash: gemini-3.8-flash

Non inserire in Open WebUI la chiave del fornitore. Se il gateway non convalida la chiave, puoi lasciare vuoto il campo della chiave API; non inventare una chiave aggiuntiva.

Browser

3000 locale

Apri la pagina della chat
Completa prima la registrazione
Poi accedi alle impostazioni

Nel container

Open WebUI

Non scrivere localhost
Usa invece il nome dell'host
L'URL termina con /v1

Stesso computer

OmniProxy

Lascia la chiave nel gateway
Fai riferimento all'elenco dei modelli del gateway
Poi controlla il registro delle chiamate

Quando Open WebUI è in Docker e OmniProxy è in esecuzione sull’host, non usare localhost del container nell’indirizzo.

Se il servizio dei modelli è in esecuzione sull’host e Open WebUI si trova in un container Docker, sostituisci localhost nell’URL con host.docker.internal. L’host è il computer sul quale Docker viene eseguito direttamente. Se OmniProxy è in ascolto soltanto su questo computer, puoi usare l’URL http://host.docker.internal:porta/v1, sostituendo porta con la porta effettivamente usata da OmniProxy.

Se Open WebUI viene eseguito localmente tramite il comando Python della sezione precedente e anche OmniProxy è in esecuzione in locale, usa 127.0.0.1 o localhost nell’indirizzo. In questo caso non usare host.docker.internal.

Inserire la configurazione nello strumento

Nell’interfaccia in cinese semplificato di v0.11.4 verificata il 2026-10-09, i nomi differivano da Settings > Admin > Connections riportato nelle istruzioni in inglese. Segui le opzioni corrispondenti visualizzate nell’interfaccia:

Espandi la barra laterale sinistra.
Seleziona il menu utente in basso.
Seleziona Impostazioni.
Nel gruppo dedicato agli amministratori, seleziona Connessioni esterne.
Apri API OpenAI.
Seleziona + a destra di Gestisci connessioni API OpenAI.
Nella finestra Modifica connessione, inserisci l’URL fino a /v1. Mantieni Chat Completions come tipo di API.
Mantieni Chiave (Bearer) come Metodo di autenticazione. Bearer è il metodo che inserisce la chiave API nella richiesta per autenticare l’accesso. Se OmniProxy ti ha fornito una chiave, inseriscila in Chiave API. Se il gateway non convalida la chiave, lascia vuoto questo campo. Il 2026-10-09, lasciandolo vuoto, sia la verifica sia una conversazione sono riuscite.
Seleziona Verifica connessione accanto all’URL. Se OmniProxy fornisce /models, verrà recuperato l’elenco dei modelli.
Apri Avanzate. Se ID modello viene lasciato vuoto, saranno usati tutti i modelli restituiti da /models a quell’indirizzo. Solo se la verifica non riesce, inserisci in Aggiungi ID modello l’ID completo presente nell’elenco, quindi seleziona Aggiungi. Aggiungi ogni ID una sola volta; gli spazi iniziali e finali vengono rimossi.
Seleziona Salva in questa finestra, quindi seleziona Salva nell’angolo inferiore destro della pagina delle connessioni esterne.

Il semplice salvataggio della configurazione non sostituisce la verifica. Verifica connessione interroga /models del servizio remoto, cioè l’endpoint che elenca i modelli disponibili. Alcuni servizi non forniscono questo endpoint: in tal caso la verifica genera un errore, ma la chat potrebbe comunque funzionare. Aggiungi quindi manualmente l’ID del modello.

Verificare un’attività reale

Torna alla pagina della chat, apri il menu dei modelli accanto alla casella di immissione e seleziona l’ID completo presente nell’elenco di OmniProxy. Invia una frase molto breve, ad esempio chiedendo al modello di rispondere con una sola parola. La risposta deve essere effettivamente visualizzata nella chat.

Il 2026-10-09 questa conversazione è stata completata con l’installazione Python di v0.11.4. Docker rimane il metodo consigliato, ma la prova non è stata ripetuta in Docker.

Apri quindi i registri delle chiamate di OmniProxy e verifica l’origine della richiesta e l’ID del modello. Il solo messaggio di salvataggio riuscito, oppure la sola presenza del modello nel menu, non sono sufficienti per considerare completata la configurazione.

Interfaccia

Il modello è selezionabile

Connections è stato salvato
Il modello compare nell'elenco
Invia una domanda breve

Risposta

La chat contiene una risposta

Non è un messaggio vuoto
Non è un errore di connessione
Prova ancora una volta con un altro modello

Registri

Visibile dal gateway

La fonte è questa connessione
L'ID del modello corrisponde
La chiave non entra nella pagina

La connessione è utilizzabile soltanto quando tutti e tre i controlli corrispondono.

Errori comuni

Nel container è stato usato localhost o 127.0.0.1: entrambi gli indirizzi indicano il container stesso, non l’host. Usa host.docker.internal e verifica che il comando di avvio includa --add-host=host.docker.internal:host-gateway. Se Open WebUI non è in esecuzione in un container, vale il contrario: usa l’indirizzo locale.
Il browser non apre la pagina: con Docker controlla la porta 3000; con Python controlla la porta 8080. Al primo avvio, attendi che termini il download del modello di embedding. docker ps consente di verificare se il container è in esecuzione. Se la porta 3000 è occupata, modifica la porta a sinistra di -p.
L’ID nel menu dei modelli è più lungo del nome breve del fornitore: usa l’ID completo mostrato nel menu, incluse le barre.
Dopo l’aggiornamento tutti gli utenti sono stati disconnessi: WEBUI_SECRET_KEY è cambiata. Riavvia usando la stringa segreta generata la prima volta.
Verifica connessione non riesce: aggiungi prima manualmente l’ID del modello in Avanzate, quindi verifica con un messaggio reale in chat. Alcuni servizi non forniscono /models; anche se la verifica genera un errore, la chat potrebbe comunque funzionare.
Il modello non esiste: copia nuovamente l’ID dall’elenco attuale di OmniProxy e non continuare a usare un nome obsoleto.

Riferimenti ufficiali

Per i comandi di installazione, consulta Open WebUI Quick Start. Per i passaggi di connessione, consulta le istruzioni per la connessione OpenAI-compatible. Gli ID dei modelli usati negli esempi sono disponibili nella panoramica dei modelli Claude e nell’elenco dei modelli Gemini.

Sostituisci ogni segnaposto con valori dalla tua configurazione OmniProxy personale. Non pubblicare mai una chiave reale.

Un risultato salvato o HTTP 200 da soli non provano la piena compatibilità con l'Agente. Controlla l'origine e il modello nel registro delle chiamate di OmniProxy.

Fonti ufficiali · Open WebUI ↗