Conectar proveedores de terceros y autoalojados

Libre WebUI 0.16.0 añade un espacio específico de Conexiones de proveedores en Configuración > Plugins. Úsalo para activar un proveedor integrado, apuntar un plugin compatible a otra API, inspeccionar el catálogo efectivo o conectar una puerta autoalojada en una red de confianza.

Libre WebUI admite actualmente estos formatos de comunicación:

• OpenAI Chat Completions;
• OpenAI Responses;
• Anthropic Messages; y
• contenidos y llamadas a funciones de Google Gemini.

Las definiciones integradas de Anthropic y Gemini usan adaptadores específicos seleccionados por sus identidades. Un proveedor recién importado usa semántica de OpenAI Chat Completions o Responses; apuntarlo a una API compatible con Anthropic o Gemini no selecciona esos adaptadores. Un proveedor con otra forma de solicitud, streaming, herramientas o respuesta necesita un adaptador del backend. El JSON describe enrutamiento y configuración; no traduce un protocolo ajeno.

Abrir Conexiones de proveedores

1. Inicia sesión y abre Configuración > Plugins.
2. Busca en la lista del panel izquierdo.
3. Selecciona un proveedor para revisar su estado y catálogo efectivo.
4. Actívalo para tu cuenta.
5. Selecciona Configurar solo si necesitas guardar una credencial o sustituir un ajuste de conexión.

La configuración está cerrada por defecto. Los ajustes de conexión aparecen primero para administradores, mientras que los controles de muestreo, como temperatura y límites de tokens, permanecen en Parámetros avanzados, plegado por separado. Los valores heredados aparecen como sugerencias, no como sustituciones rellenadas.

Las definiciones son configuración compartida de la instancia, por lo que solo los administradores pueden importarlas, instalarlas, actualizarlas o eliminarlas. Cada usuario controla su activación, credencial y ajustes de generación permitidos.

Añadir una conexión rápidamente

Configuración > Conexiones es una ruta más corta para el caso habitual: un endpoint compatible con OpenAI y una clave de API. Los administradores ven una tarjeta del entorno Ollama local con salud y versión, las conexiones existentes y un pequeño formulario para añadir otra.

Se proporciona un nombre, la URL completa de completado de chat y una clave opcional. Libre WebUI deriva el ID del nombre, instala la definición, almacena la clave en el servidor, activa la conexión y pregunta al endpoint qué modelos ofrece. Los modelos descubiertos sustituyen al catálogo provisional y aparecen en Chat.

Cada fila muestra endpoint, número de modelos, si hay clave, activación, actualización y eliminación. Todo lo demás —modos Responses, URL base, catálogos por capacidad, política de parámetros— permanece en Configuración > Plugins.

Codex (inicio de sesión de ChatGPT)

El proveedor integrado Codex (ChatGPT) no requiere clave de API. Cuando el servidor tiene una sesión de Codex CLI (codex login como usuario del sistema), el proveedor aparece a los administradores y ofrece la familia Codex documentada mediante la sesión de ChatGPT. Los tokens se leen del auth.json de la CLI, se actualizan con su mismo cliente OAuth y se vuelven a escribir para que la CLI siga funcionando; los valores nunca aparecen en registros.

Como las solicitudes proceden del backend, no de una tarea, estos modelos también impulsan Work con el bucle aislado normal. Está restringido a administradores porque cada llamada consume la suscripción de ChatGPT del propietario. Ocúltalo con CODEX_OAUTH_MODELS_ENABLED=false o usa otra sesión mediante CODEX_HOME.

Elegir un proveedor integrado o importado

Libre WebUI incluye definiciones para OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Kimi Code de Moonshot AI, Hugging Face, GitHub Models, MLX LM local y otros servicios. Empieza por una entrada integrada si su protocolo y autenticación coinciden con el servicio.

Para otro servicio compatible, un administrador puede importar una definición JSON. Este ejemplo mínimo describe una puerta compatible con OpenAI:

{
  "id": "private-ai-gateway",
  "name": "Private AI Gateway",
  "type": "completion",
  "endpoint": "http://ai-gateway:8080/v1/chat/completions",
  "api_mode": "chat_completions",
  "auth": {
    "header": "Authorization",
    "prefix": "Bearer ",
    "key_env": "PRIVATE_AI_GATEWAY_API_KEY"
  },
  "model_map": ["gateway-chat"]
}

Importa el archivo en Configuración > Plugins, actívalo y guarda la clave para la cuenta que lo usará. Añade variables de conexión cuando los administradores necesiten campos editables de URL base, ruta, exploración o endpoints por capacidad. El archivo integrado plugins/openai.json es un ejemplo completo.

Para una puerta intencionadamente sin autenticación en una red de confianza, define auth.header y auth.key_env como cadenas vacías y omite auth.prefix. Libre WebUI no exigirá ni enviará una clave.

Elegir Chat Completions o Responses

Los plugins compatibles con OpenAI pueden usar ambos modos:

Modo de API	Ruta predeterminada	Campo habitual
chat_completions	/chat/completions	messages
responses	/responses	input

El proveedor integrado de OpenAI expone Modo de API. Libre WebUI adapta la salida de Responses, completa o en streaming, a Chat y Work, incluido estado de reproducción acotado para razonamiento y herramientas.

Cambiar el modo altera la ruta predeterminada, no el protocolo del servidor superior. Selecciona Responses solo si implementa formas compatibles de solicitudes y eventos.

Configurar una URL base o un endpoint completo

Libre WebUI resuelve la ruta de completado en este orden:

1. Una sustitución completa de endpoint que no sea la predeterminada.
2. base_url más un api_path opcional.
3. El endpoint declarado por la definición.

Usa URL base para la raíz:

https://gateway.example/v1

Sin ruta personalizada, Chat Completions envía a:

https://gateway.example/v1/chat/completions

Responses envía a:

https://gateway.example/v1/responses

Usa Ruta de API cuando el proveedor exponga una operación compatible en otra ruta relativa. Usa Endpoint completo heredado solo si necesitas aportar la URL completa; un endpoint genuino prevalece sobre URL base y Ruta de API.

Los sufijos conocidos /chat/completions, /completions y /responses también identifican la semántica. Una ruta personalizada desconocida conserva el modo elegido.

Después de cambiar ruta o clave, vuelve a guardar antes de probar Chat. Si el plugin declara autenticación, una ruta personalizada exige una credencial guardada por la misma cuenta. Un plugin sin autenticación puede dejar ambos campos vacíos. Libre WebUI no envía una clave de entorno del operador a un destino del usuario; el respaldo de entorno se reserva a la ruta integrada de confianza.

Explorar o mantener ID de modelos

Selecciona un proveedor activo y pulsa Actualizar modelos. Libre WebUI recarga su catálogo y la lista de Chat.

La exploración también se ejecuta automáticamente: el catálogo se vuelve a descubrir si falta o supera PLUGIN_MODEL_DISCOVERY_TTL_MS, de modo que los modelos siguen al proveedor y no al momento de activación. Actualizar modelos fuerza la comprobación:

Resultado	Significado
Catálogo actualizado	El proveedor respondió y la lista cambió
Catálogo ya actualizado	Respondió con la misma lista
Se necesita clave de API	No hay clave válida; no se hizo solicitud y se conserva el catálogo anterior
No se pudo cargar el catálogo	El proveedor no respondió o no devolvió nada utilizable

Una clave solo de entorno no se usa para una definición instalada en vez de la integrada; el mensaje lo indica. Los modelos de voz, imagen y embeddings aparecen con etiquetas de capacidad, pero se excluyen del selector de chat.

Para una ruta compatible con OpenAI, la URL de modelos se elige así:

• una ruta terminada en /models se usa tal cual;
• un sufijo conocido como /chat/completions, /completions, /responses, /embeddings o /messages se sustituye por /models; y
• en los demás casos se añade /models.

Estas rutas derivan la misma URL:

https://gateway.example/v1/chat/completions
https://gateway.example/v1/responses

-> https://gateway.example/v1/models

Cuando la derivación no sea correcta, expón models_endpoint en el array variables:

{
  "name": "models_endpoint",
  "type": "string",
  "label": "Models Endpoint",
  "default": "https://gateway.example/v1/models"
}

El valor heredado o guardado por el administrador prevalece. No se lee una propiedad models_endpoint de nivel superior. Se espera una respuesta compatible con OpenAI con objetos en un array data:

{
  "data": [{ "id": "gateway-chat" }, { "id": "gateway-code" }]
}

Los ID se almacenan por usuario y no reescriben el archivo compartido. Si el proveedor no implementa exploración compatible, mantén ID de respaldo en model_map. El catálogo es de solo lectura; las etiquetas indican qué ruta enumera un modelo, no son comprobaciones de salud.

Los ID no son globalmente únicos. Chat guarda el ID bruto con la identidad exacta de Ollama o plugin, por lo que varios proveedores pueden exponer el mismo nombre. Si el proveedor deja de estar disponible, Libre WebUI muestra la selección como no disponible en vez de redirigir silenciosamente.

Configurar la generación de imágenes por separado

El proveedor integrado de OpenAI expone imágenes mediante https://api.openai.com/v1/images/generations y usa actualmente gpt-image-2 de forma predeterminada en configuraciones nuevas. Los ID antiguos de GPT Image siguen en el catálogo de respaldo.

Las rutas de Chat e imágenes están aisladas. Una URL base personalizada de Chat no recibe solicitudes de imágenes automáticamente. Deja image_endpoint vacío para usar el declarado por el plugin o define la URL completa de la operación compatible.

Las opciones de imagen se identifican por proveedor. Si dos plugins exponen el mismo ID, Libre WebUI solo envía al seleccionado en el panel de imágenes.

Conectar una puerta HTTP con seguridad

Los endpoints pueden ser URL absolutas HTTP o HTTPS. HTTP resulta útil en una LAN, red Tailscale o red de contenedores privada, pero envía claves, prompts, resultados y contenido sin cifrado de transporte. Prefiere HTTPS al cruzar un límite de red o si la puerta admite TLS.

Las solicitudes proceden del backend, no del navegador. Elige una dirección accesible:

Ubicación del backend	Ejemplo de raíz
Proceso nativo, misma máquina	http://127.0.0.1:8081/v1
Servicio Docker Compose	http://ai-gateway:8080/v1
Contenedor al host compatible	http://host.docker.internal:8081/v1
Host de LAN o Tailscale de confianza	http://192.168.1.20:8081/v1

Dentro de un contenedor, localhost identifica el propio contenedor de Libre WebUI, no otro servicio Compose ni el host.

Libre WebUI solo acepta HTTP y HTTPS, valida el destino final antes de elegir una credencial y no sigue redirecciones para solicitudes de proveedor o exploración. Configura directamente la URL final.

Verificar la puerta antes de activarla

Prueba la exploración desde la máquina o contenedor que ejecuta el backend:

curl http://ai-gateway:8080/v1/models \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY'

Después prueba la operación del modo seleccionado.

Chat Completions:

curl http://ai-gateway:8080/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "messages": [{"role": "user", "content": "Reply with: ready"}],
    "stream": false
  }'

Responses:

curl http://ai-gateway:8080/v1/responses \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "input": "Reply with: ready",
    "store": false
  }'

Cuando ambas funcionen, configura la misma ruta, modo, credencial e ID en Conexiones de proveedores. Activa, selecciona Actualizar modelos y elige el modelo identificado por proveedor en Chat. Work también puede usarlo si admite herramientas de forma fiable.

Solución de problemas

Síntoma	Comprobación
Las solicitudes aún llegan al endpoint integrado	Elimina una sustitución completa obsoleta y guarda la URL base y Ruta de API deseadas.
El proveedor recibe una carga incorrecta	Haz coincidir Modo de API con Chat Completions o Responses y verifica el sufijo final.
Actualizar modelos no devuelve ID	Prueba /models, verifica data[].id, expón/configura models_endpoint o mantén model_map.
Permanece un modelo tras editar la ruta	Guarda el cambio; Libre WebUI borra el catálogo descubierto obsoleto antes de actualizar.
Se informa de que falta la clave	Guarda una credencial por usuario; el respaldo de entorno integrado no sigue sustituciones.
Docker no puede alcanzar localhost	Usa el nombre del servicio Compose, un alias de host compatible o una dirección privada accesible.
Chat funciona, pero no las imágenes	Configura image_endpoint completo por separado y selecciona un modelo de esa capacidad.
Chat funciona, pero Work rechaza el modelo	Confirma llamadas a herramientas compatibles; un completado de texto normal no basta.
El proveedor devuelve una redirección	Configura directamente la URL final validada; Libre WebUI no sigue redirecciones.

Para detalles de enrutamiento, credenciales, estado de reproducción y autorización, lee Plugins. Para fallos de despliegue, consulta Solución de problemas.

Agradecimiento a la comunidad

Esta guía y la experiencia de Conexiones de proveedores de Libre WebUI 0.16.0 se beneficiaron de ZhengJin (@fangzhengjin), cuyos comentarios detallados y concepto de UX asistido por IA en #163 ayudaron a definir el flujo.

Documentación relacionada

• Plugins
• Trabajar con modelos
• MLX LM en Apple Silicon
• Work: espacios de trabajo aislados
• Solución de problemas