Instal·lació d'Open WebUI i configuració d'OmniProxy

Open WebUI és una interfície de xat allotjada per un mateix que es pot instal·lar al teu propi ordinador o servidor i també pot funcionar completament fora de línia. No està lligada a cap proveïdor de models: es pot connectar a eines com Ollama que executen models localment, així com a punts finals compatibles amb OpenAI—adreces que proporcionen serveis de models utilitzant el mateix format de sol·licitud. Això et permet canviar entre models locals i al núvol a la mateixa finestra.

És adequat per a un ús a llarg termini per part d’equips i organitzacions. Les capacitats que reben actualitzacions més ràpides apareixen primer a Computer, el producte que Open WebUI utilitza per provar noves funcions.

Abans de començar

Open WebUI està disponible en macOS, Linux i Windows. Pots instal·lar-lo utilitzant Docker, Python o Kubernetes. Docker empaqueta l’aplicació i el seu entorn d’execució en un contenidor relativament aïllat i és el mètode recomanat. Si Docker no està disponible, també pots utilitzar l’ordre de Python provada a continuació. Kubernetes és un sistema per desplegar i gestionar contenidors; consulta l’inici ràpid enllaçat al final d’aquesta guia per als passos corresponents.

Recomanat oficialment

Docker

Una ordre docker run
Obre el 3000 al navegador
Les dades s'emmagatzemen al volum

Només vull xatejar

imatge slim

Mida de descàrrega més petita
Canvia l'etiqueta a :slim
La funcionalitat de xat roman disponible

No es tracta aquí

Dues opcions més

Instal·lació manual de Python
Desplegament de Kubernetes
Consulta l'inici ràpid oficial

Instal·la Docker primer, després inicia l'aplicació amb l'ordre recomanada. Si només xateges a través d'una API, pots canviar l'etiqueta de la imatge a slim.

Abans de començar, prepara el següent:

Docker instal·lat i en execució.
Una cadena secreta utilitzada només per tu. Executa openssl rand -hex 32 per generar-ne una, després introdueix-la com WEBUI_SECRET_KEY. Desa aquest valor permanentment. Si el canvies en reconstruir el contenidor, els usuaris que ja hagin iniciat sessió hauran de tancar-la.
Una instància d’OmniProxy en execució i un ID de model de la seva llista de models actual. L’ID del model és el nom complet utilitzat per seleccionar un model específic.

Instal·lació i primer llançament

Obre un terminal i executa l’ordre de l’inici ràpid. Primer substitueix your-secret-key pel secret que acabes de generar:

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

Les parts següents d’aquesta ordre tenen finalitats diferents:

-p 3000:8080: Et permet obrir la interfície a través del port 3000 en aquest ordinador. Si el port 3000 ja està en ús, canvia el número de l’esquerra.
-v open-webui:/app/backend/data: Emmagatzema xats, usuaris i paràmetres en un volum de dades. Un volum de dades és una ubicació fora del contenidor on les dades es conserven a llarg termini, de manera que el seu contingut roman després que el contenidor s’actualitzi. No eliminis aquesta opció.
--add-host=host.docker.internal:host-gateway: Permet que el contenidor accedeixi a altres serveis que s’executen en aquest ordinador.
--restart always: Inicia el contenidor de nou després que l’ordinador es reiniciï.

Després que l’ordre finalitzi, obre http://localhost:3000 en un navegador i segueix les instruccions a la pantalla per crear el primer compte.

Si només necessites xatejar a través d’una API, pots canviar l’etiqueta de la imatge de :main a :slim. slim és una imatge més petita que no inclou models locals de veu i incrustació dins del contenidor, però la interfície de xat roman disponible. Continua utilitzant :main si necessites aquestes capacitats locals.

Per a actualitzacions manuals, primer executa docker rm -f open-webui, després executa docker pull ghcr.io/open-webui/open-webui:main, i reinicia’l amb la mateixa docker run ordre. Mantingues tant el volum de dades com WEBUI_SECRET_KEY sense canvis.

Si Docker no està disponible

L’inici ràpid també proporciona un mètode d’instal·lació de Python. El 09-10-2026, es va utilitzar l’ordre següent en macOS per instal·lar Open WebUI v0.11.4 i completar una conversa. Docker Desktop no estava instal·lat en aquest ordinador en aquell moment.

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

Després de l’inici, obre http://localhost:8080 en un navegador. Aquest és el port utilitzat per la instal·lació de Python, no el port 3000 de Docker.

Es descarrega un model d’incrustació durant el primer inici, cosa que pot trigar diversos minuts. Un model d’incrustació converteix el text en dades que són més fàcils de cercar i fer coincidir. Espera que aparegui la pàgina d’inici de sessió abans de continuar. El primer compte registrat es converteix en l’administrador. L’idioma de la interfície segueix l’idioma del sistema; el xinès simplificat es va mostrar durant aquesta prova.

DATA_DIR ha d’apuntar a un directori que es conservarà a llarg termini i s’utilitzarà per emmagatzemar les dades d’Open WebUI. Si no s’estableix, les dades es poden emmagatzemar en un directori temporal i perdre’s després de l’apagada. Si WEBUI_SECRET_KEY no s’estableix, el programa escriu .webui_secret_key al directori actual. Inicia’l des d’un directori que tinguis la intenció de conservar, o estableix aquesta variable tu mateix.

Obtenir detalls de connexió d’OmniProxy

Copia els tres elements següents de la teva pròpia instància d’OmniProxy:

URL:      https://your-omniproxy-origin.example/v1
API Key:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Copy from the current OmniProxy model list

L’URL és l’adreça que Open WebUI utilitza per connectar-se al punt final i ha d’acabar amb /v1. No afegeixis /chat/completions després d’ella; Open WebUI afegeix aquesta part automàticament.

Copia l’ID complet del model de la llista actual d’OmniProxy. Si l’ID inclou un prefix de font i una barra inclinada, conserva’ls també. Els dos noms curts següents són només referències de la documentació del proveïdor a data de 09-10-2026. No els utilitzis si no estan a la llista actual:

ID de l’API de Claude per a Claude Sonnet 5.5: claude-sonnet-5-5
Nom de l’API per a Gemini 3.8 Flash: gemini-3.8-flash

No introdueixis una clau de proveïdor a Open WebUI. Si la passarel·la no valida les claus, deixa la clau API en blanc en lloc d’inventar-ne una altra.

Navegador

Port local 3000

Obre la pàgina de xat
Completa el registre primer
Després obre els paràmetres

Dins del contenidor

Open WebUI

No utilitzis localhost
Utilitza el nom de la màquina amfitriona en lloc d'això
L'URL acaba amb /v1

Mateix ordinador

OmniProxy

Mantingues la clau a la gateway
Utilitza la llista de models de la gateway
Després revisa els registres de sol·licituds

Quan Open WebUI s'executa a Docker i OmniProxy s'executa a l'amfitrió, no utilitzis el localhost del contenidor a l'adreça.

Si el servei de models s’executa a l’amfitrió mentre Open WebUI s’executa en un contenidor Docker, substitueix localhost a l’URL per host.docker.internal. L’amfitrió és l’ordinador que executa Docker directament. Si OmniProxy només escolta en aquest ordinador, l’URL es pot escriure com http://host.docker.internal:port/v1, substituint port pel port que OmniProxy utilitza realment.

Si Open WebUI s’executa localment a través de l’ordre de Python a la secció anterior i OmniProxy també s’executa localment, utilitza 127.0.0.1 o localhost a l’adreça. No utilitzis host.docker.internal en aquest cas.

Introduir la configuració

A la interfície de xinès simplificat de la v0.11.4 provada el 09-10-2026, els noms diferien de Settings > Admin > Connections a les instruccions en anglès. Segueix les opcions que es mostren a la interfície provada, traduïdes a continuació:

Expandeix la barra lateral esquerra.
Fes clic al menú d’usuari a la part inferior.
Fes clic a Settings.
A la secció d’administrador de sota, fes clic a External Connections.
Obre OpenAI API.
Fes clic a + a la dreta de Manage OpenAI API Connections.
Al diàleg Edit Connection, introdueix l’URL que acaba en /v1. Mantingues el tipus d’API establert a Chat Completions.
Mantingues Authentication Method establert a Key (Bearer). L’autenticació Bearer col·loca la clau API a la sol·licitud per a la verificació d’identitat. Si OmniProxy t’ha donat una clau, introdueix-la sota API Key. Si la gateway no valida les claus, deixa aquest camp en blanc. El 09-10-2026, tant la validació com una conversa van tenir èxit amb el camp deixat en blanc.
Fes clic a Verify Connection al costat de l’URL. Si OmniProxy proporciona /models, la llista de models es recuperarà aquí.
Obre Advanced. Si Model ID es deixa en blanc, s’utilitzaran tots els models retornats per /models en aquesta adreça. Només si la validació falla, introdueix un ID complet de la llista sota Add Model ID, després fes clic a Add. Afegeix cada ID només una vegada; els espais inicials i finals s’eliminen.
Fes clic a Save en aquesta finestra, després fes clic a Save a l’extrem inferior dret de la pàgina External Connections.

Desar la configuració per si sola no substitueix la validació. Verify Connection sol·licita el punt final /models de l’altre servei, que llista els models disponibles. Alguns serveis no proporcionen aquest punt final, per la qual cosa la validació pot informar d’un error tot i que el xat encara pot funcionar. En aquest cas, afegeix l’ID del model manualment.

Verificar una tasca real

Torna a la pàgina de xat, obre el menú de models al costat de la caixa d’entrada i selecciona l’ID complet de la llista d’OmniProxy. Envia un missatge molt curt, com ara demanar-li que respongui amb només una paraula. Una resposta ha d’aparèixer realment a la caixa de xat.

El 09-10-2026, aquesta conversa es va completar utilitzant la instal·lació de Python de la v0.11.4. Docker continua sent el mètode recomanat, però la prova no es va repetir a Docker.

Després, obre els registres de sol·licituds d’OmniProxy i confirma la font i l’ID del model per a aquesta sol·licitud. Veure només un desat correcte, o veure només el model al menú, no compta com a finalització.

Interfície

Es pot seleccionar el model

S'han desat les connexions
El model apareix a la llista
Envia una pregunta curta

Resposta

La caixa de xat mostra una resposta

No és un missatge en blanc
No és un error de connexió
Prova-ho de nou amb un altre model

Registres

Visible a la gateway

La font és aquesta connexió
L'ID del model coincideix
No s'ha introduït cap clau a la pàgina

La connexió només és utilitzable quan les tres comprovacions coincideixen.

Errors comuns

localhost o 127.0.0.1 es va utilitzar dins del contenidor: Aquestes adreces apunten al contenidor mateix, no a l’amfitrió. Canvia l’adreça a host.docker.internal i confirma que l’ordre d’inici inclou --add-host=host.docker.internal:host-gateway. El contrari s’aplica quan Open WebUI no s’executa en un contenidor: utilitza una adreça local en lloc d’això.
El navegador no pot obrir la pàgina: Per a Docker, comprova el port 3000; per a Python, comprova el port 8080. Durant el primer inici, espera que finalitzi la descàrrega del model d’incrustació. Pots utilitzar docker ps per confirmar si el contenidor s’està executant. Si el port 3000 ja està en ús, canvia el port al costat esquerre de -p.
L’ID al menú de models és més llarg que el nom curt del proveïdor: Utilitza l’ID complet del menú, incloent-hi qualsevol barra inclinada.
Tothom ha tancat la sessió després d’una actualització: WEBUI_SECRET_KEY canviat. Reinicia utilitzant el secret generat la primera vegada.
Verify Connection falla: Primer afegeix manualment l’ID del model sota Advanced, després confirma-ho amb un xat real d’una frase. Alguns serveis no proporcionen /models, per la qual cosa el xat encara pot funcionar quan la validació informa d’un error.
El model no existeix: Copia l’ID de nou de la llista actual d’OmniProxy en lloc de continuar utilitzant un nom obsolet.

Referències oficials

Per a les ordres d’instal·lació, consulta Open WebUI Quick Start. Per als passos de connexió, consulta les OpenAI-compatible connection instructions. Per als IDs de model utilitzats als exemples, consulta el Claude model overview i Gemini model list.

Substitueix cada marcador de posició amb valors de la teva pròpia configuració d'OmniProxy. No publiquis mai una clau real.

Un resultat guardat o HTTP 200 sols no demostra compatibilitat completa de l'Agent. Comprova la font i el model al registre de crides d'OmniProxy.

Fonts oficials · Open WebUI ↗