LobeChat: API personalizada, OpenAI compatible y despliegue (2026)

LobeChat es una aplicación de chat con IA de código abierto que admite varios modelos, varios asistentes, plugins y bases de conocimiento. Se puede desplegar en la nube con un clic o ejecutar en tu propio servidor. Hay dos formas de integrar una API personalizada: rellenar los datos del proveedor en la interfaz o fijarlos al desplegar mediante variables de entorno. La primera encaja en un ordenador personal; la segunda, en equipos y ejecuciones de larga duración.

Este artículo toma como referencia las versiones habituales de octubre de 2026 y explica la preparación de parámetros, el despliegue con Docker, las variables de entorno, la configuración en la interfaz y la resolución de problemas.

Nota: LobeChat y LobeHub son productos de sus respectivos titulares, y OpenAI es una marca de su titular; este artículo solo ofrece una explicación técnica de integración. Los nombres de las variables de entorno y los accesos de la interfaz pueden cambiar según la versión; consulta la documentación oficial de tu versión actual. Los modelos y precios se indican en los precios de modelos del sitio.

1. Cómo elegir entre las tres formas de integración

Forma	Escenario adecuado	Dónde se configura	Ventajas
Configuración en la interfaz	Uso personal, pruebas rápidas	AI Providers en los ajustes	Surte efecto al guardar, sin reiniciar
Variables de entorno de Docker	Servidor propio, uso en equipo	`docker run` o compose	Versionable y replicable
Variables de entorno en la nube	Despliegue gestionado como Vercel	Ajustes de variables del proyecto	Sin operación de servidores, ideal para equipos pequeños

En un ordenador personal, se recomienda probar primero con la configuración en la interfaz y después migrar a Docker; en un despliegue de equipo, es mejor usar directamente variables de entorno y guardar la clave y la dirección en un gestor de secretos, no en el repositorio de código.

2. Prepara tres parámetros

API Key: créala en ZSQH AI Gateway y ponle un nombre por proyecto o entorno.
Base URL: https://ai.zhongshangqihang.com/v1, la entrada compatible con OpenAI.
ID del modelo: cópialo de la página de precios de modelos; recuerda que es el identificador de API, no el nombre visible.

Verifica primero con curl para no confundir un problema del gateway con un problema de configuración de LobeChat:

export ZSQH_API_KEY="sk-tu-clave"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tu-modelo-id",
    "messages": [{"role": "user", "content": "Responde solo OK"}]
  }'

Si la respuesta incluye choices, los tres elementos son válidos y puedes pasar a la fase de despliegue.

3. Despliegue con Docker

La forma más sencilla es arrancar un contenedor con la imagen oficial y pasar la clave, la dirección del proxy y la lista de modelos mediante variables de entorno:

docker run -d --name lobechat \
  -p 3210:3210 \
  -e OPENAI_API_KEY="sk-tu-clave" \
  -e OPENAI_PROXY_URL="https://ai.zhongshangqihang.com/v1" \
  -e CUSTOM_MODELS="-all,+tu-modelo-id" \
  lobehub/lobe-chat

Después de arrancar, accede a http://dirección-del-servidor:3210. Significado de algunos parámetros:

OPENAI_API_KEY: clave del gateway; se recomienda inyectarla mediante variables de entorno o un gestor de secretos, no escribirla en un archivo compose público.
OPENAI_PROXY_URL: sobrescribe la dirección predeterminada de OpenAI y apunta a tu gateway compatible.
CUSTOM_MODELS: controla la lista de modelos; -all vacía primero la lista predeterminada y +ID-del-modelo añade un modelo.

Si usas Docker Compose, escribe las mismas variables en la sección environment. Después de cambiar las variables hay que reconstruir el contenedor; un simple reinicio no siempre carga el entorno nuevo.

4. Variables de entorno y lista de modelos

Variable	¿Obligatoria?	Ejemplo	Descripción
`OPENAI_API_KEY`	Sí	`sk-...`	Clave creada en el gateway
`OPENAI_PROXY_URL`	Sí	`https://ai.zhongshangqihang.com/v1`	Sobrescribe la Base URL predeterminada
`CUSTOM_MODELS`	Recomendada	`-all,+model-a,+model-b`	Controla los modelos visibles
`OPENAI_MODEL_LIST`	Según la versión	`+model-a`	Las versiones antiguas pueden usar este nombre

Puntos clave de la sintaxis de CUSTOM_MODELS:

+ID-del-modelo añade un modelo; -ID-del-modelo lo oculta.
-all vacía primero la lista predeterminada para evitar que aparezcan modelos que no se pueden llamar.
Separa los elementos con comas inglesas y sin espacios.
Puedes renombrar con ID-del-modelo=nombre visible, pero no cambies el ID del modelo en sí.

Las distintas versiones no admiten exactamente los mismos nombres de variables ni la misma sintaxis; las versiones antiguas pueden usar OPENAI_MODEL_LIST. Si la lista de modelos desaparece después de actualizar, consulta primero la documentación de la versión actual y no apliques sin más un tutorial antiguo.

5. Configurar desde la interfaz

Si no quieres tocar las variables de entorno, puedes configurarlo en la interfaz. Con las versiones habituales actuales:

Abre LobeChat y entra en los ajustes.
Busca «AI Providers» o «Language Model».
Selecciona OpenAI e introduce la API Key y la dirección del proxy.
Añade el ID del modelo personalizado en la lista de modelos.
Guarda, crea una conversación nueva y prueba con ese modelo.

La configuración en la interfaz es adecuada para uso local. Si despliegas en un servidor, la configuración guardada en el navegador pertenece al usuario actual y puede que tengas que volver a configurarla al cambiar de dispositivo o borrar la caché; en equipos compartidos, prioriza las variables de entorno.

6. Verificación y proxy inverso

Cuando el contenedor esté en marcha, revisa primero los registros para confirmar que no hay errores en las variables de entorno:

docker logs -f lobechat

Después, envía un mensaje desde la interfaz para probar. Si lo despliegas expuesto a Internet, se recomienda poner delante Nginx o Caddy y cubrir al menos tres puntos:

Configurar HTTPS; no transmitas claves por HTTP en texto plano.
Establecer control de acceso para no exponer la aplicación a cualquiera.
Configurar tiempos de espera y buffering; las respuestas en streaming necesitan que el buffering del proxy esté desactivado.

Al procesar respuestas en streaming con Nginx, una configuración habitual es desactivar proxy_buffering y ampliar el tiempo de espera de lectura. De lo contrario, la respuesta aparece «de golpe» o se queda atascada a mitad.

7. Lista de comprobación para producción

Inyecta la clave mediante un gestor de secretos o variables de entorno; no la escribas en la imagen.
Emite una clave independiente para LobeChat, así podrás limitar el uso y revocarla con facilidad.
Configura una base de datos; de lo contrario, las conversaciones y la configuración pueden quedarse solo en local.
Activa HTTPS y control de acceso; no dejes un despliegue público sin protección.
Configura presupuestos y límites de concurrencia en el gateway para evitar que un bucle anómalo consuma la cuota.
Haz copias de seguridad periódicas de la base de datos y de los archivos subidos.
Antes de actualizar, revisa el changelog; fija una etiqueta de versión en la imagen y no uses latest durante largos periodos.

8. Errores habituales y cómo resolverlos

Síntoma	Causa habitual	Solución
No hay modelos tras arrancar	`CUSTOM_MODELS` no surtió efecto	Revisa el nombre de la variable, las comas y si el contenedor se reconstruyó
`401 Unauthorized`	Clave no inyectada o no válida	Entra en el contenedor, confirma la variable de entorno y crea una clave nueva
`404 Not Found`	Ruta de la dirección del proxy incorrecta	Revisa `/v1` y añádelo o quítalo si es necesario
`model not found`	El ID del modelo no coincide con la página de precios	Copia el identificador exacto
La respuesta se atasca a mitad	Buffering o tiempo de espera del proxy inverso	Desactiva el buffering y amplía el tiempo de espera de lectura
Error al subir archivos	Almacenamiento o capacidades del modelo sin configurar	Revisa la configuración de almacenamiento y las capacidades del modelo
La base de conocimiento no está disponible	Modelo de embeddings sin configurar	Configura un modelo de embeddings disponible

Al resolver problemas, distingue primero si «la aplicación no leyó la configuración» o si «el gateway rechazó la solicitud». En el primer caso, revisa las variables de entorno y los registros del contenedor; en el segundo, el código de estado HTTP. La solución es completamente distinta.

Preguntas frecuentes

¿LobeChat es gratuito?

LobeChat es un proyecto de código abierto que puedes desplegar por tu cuenta; el coste de las llamadas a los modelos lo cobra el proveedor de API que conectes. Los precios del servicio gestionado y de las funciones de pago se rigen por lo que indique el proveedor del servicio.

¿Es obligatorio usar Docker?

No. También puedes ejecutarlo con Node.js o desplegarlo en una plataforma en la nube compatible con Next.js. La ventaja de Docker es la consistencia del entorno y la facilidad de migración; es más habitual en despliegues de equipo.

¿Qué diferencia hay entre `OPENAI_PROXY_URL` y la dirección de proxy de la interfaz?

La variable de entorno surte efecto en la capa de despliegue y es adecuada para una configuración unificada del equipo; la configuración de la interfaz pertenece al usuario actual y puede que haya que rehacerla al cambiar de dispositivo. Si ambas existen, prevalece la prioridad de la versión actual.

¿Por qué aparecen modelos que no funcionan en la lista?

Lo más probable es que no hayas vaciado la lista predeterminada con -all o que la sintaxis de CUSTOM_MODELS sea incorrecta. Deja primero solo un modelo que sepas que funciona y añade más cuando todo vaya bien.

¿Se pueden conectar Claude o Gemini?

Sí, siempre que el gateway ofrezca el modelo correspondiente en formato compatible con OpenAI y el ID del modelo sea correcto. Las capacidades con protocolos nativos distintos, como ciertas llamadas a herramientas o parámetros de imagen, deben probarse en la práctica; consulta la documentación del sitio.

Próximos pasos

La integración de LobeChat se puede dividir en dos pasos: confirmar primero con curl que el gateway funciona y después alinear la Base URL, la clave y el modelo mediante variables de entorno o la interfaz. En despliegues de equipo, prioriza las variables de entorno; en pruebas personales, prioriza la interfaz. Si necesitas un punto de acceso unificado a modelos y gestión de uso, puedes registrarte en ZSQH AI Gateway; los modelos y precios se indican en la página de precios de modelos.

Lecturas relacionadas: