LobeChat reúne varios modelos, plugins y bases de conocimiento en una sola interfaz; hay muchas opciones de configuración y es fácil diagnosticar mal un error. La mayoría de los problemas no está en el modelo, sino en una de cuatro capas: la clave no surte efecto, la dirección o el nombre del modelo no son correctos, se alcanzó el límite de cuota o concurrencia, o la red y el intercambio de origen fallan. Clasificar primero y verificar capa por capa es más eficaz que reinstalar el cliente una y otra vez.

Este artículo recorre los errores 401, 404 y 429 y los fallos de conexión, y añade los problemas de streaming, plugins y base de conocimiento. La interfaz y los nombres de variables cambian según la versión; guíate por la documentación de la versión actual. Los modelos y precios se rigen por la página de precios de modelos del sitio, y los precios pueden cambiar.

Nota: LobeChat y LobeHub son productos y marcas de sus respectivos titulares. Este artículo solo ofrece una explicación técnica de diagnóstico y no implica relación de subordinación con esas empresas.

1. Registra primero la evidencia y después clasifica

Síntoma Código o mensaje habitual Primera impresión Qué revisar primero
401 Unauthorized invalid_api_key, respuesta vacía La clave no se reconoce Integridad de la clave, dirección a la que pertenece, forma de inyección
404 / model not found not_found_error, model_not_found Ruta o nombre de modelo incorrectos Base URL, /v1, ID del modelo
429 Too Many Requests rate_limit_error, insufficient_quota Límite de velocidad o cuota insuficiente Concurrencia, consumo, facturación
Failed to fetch Sin código, error del navegador La solicitud no obtuvo respuesta DNS, proxy, firewall, CORS
5xx server_error, página de error del gateway Falla del upstream o del gateway Reintentar y registrar el ID de solicitud
Falla de plugin o base de conocimiento Error de llamada a herramientas, carga fallida Falta una capacidad o dependencia Llamada a funciones, almacenamiento, embeddings

Antes de diagnosticar, anota al menos: hora, versión, forma de despliegue (escritorio, web o Docker), código de estado, cuerpo de la respuesta e ID de solicitud. Sin esos datos solo queda adivinar.

2. 401: la clave no se reconoce

Un 401 significa que el servidor rechaza esa clave. Las causas más frecuentes son:

  • Al copiar se colaron espacios, saltos de línea o caracteres de ancho completo que parecen iguales pero no lo son.
  • Se mezclan la configuración de la interfaz y las variables de entorno del despliegue, y la solicitud real no usa la clave que crees.
  • La clave fue eliminada, rotada o el proyecto al que pertenece está desactivado.
  • Se usa la clave del proveedor A contra la dirección del proveedor B.
  • Un proxy de la empresa intercepta la solicitud y devuelve una página HTML de inicio de sesión en lugar de JSON.

Verifica primero fuera del cliente. Envía una solicitud mínima con la misma clave y la misma dirección:

export ZSQH_API_KEY="sk-tu-clave"

curl -sS "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"}]}' \
  -w "\nHTTP %{http_code}\n"

Si devuelve 200 y choices, la clave y la dirección son válidas; si sigue dando 401, el problema está en la copia, los permisos o el proxy. En despliegues Docker, confirma que las variables llegaron al contenedor con docker exec lobe-chat env | grep -i openai, usando el nombre real que muestre docker ps. La configuración de la interfaz pertenece al usuario actual y puede desaparecer al cambiar de dispositivo o borrar la caché; en equipos compartidos, prioriza las variables de entorno.

3. 404 y model not found: revisa dirección y modelo por separado

Hay dos clases de 404: la ruta no existe o el modelo no existe. La primera se revisa en la URL; la segunda, en el ID del modelo.

En el campo de dirección de proxy de LobeChat, algunas versiones aceptan solo el dominio y otras exigen /v1, según si el gateway reenvía /v1 por su cuenta. El criterio es que /v1 aparezca una sola vez en la dirección final. Un error habitual es que el host ya termina en /v1 y la ruta se añade otra vez, formando /v1/v1/chat/completions. La dirección de proxy debe apuntar a la raíz de la API, no a la ruta completa /chat/completions.

model not found no tiene relación con la ruta. El ID del modelo distingue mayúsculas, sufijos de versión y prefijos de proveedor; cópialo de la página de precios de modelos o de la consola. Si gestionas la lista con CUSTOM_MODELS, haz primero una prueba mínima con -all,+un-modelo-que-sepas-que-funciona y añade los demás cuando todo vaya bien; usa comas inglesas y sin espacios. Que un modelo aparezca en la lista no basta: confirma que el tipo y las capacidades coincidan con la realidad, o fallará en la primera llamada.

Un 403 suele significar que la clave se reconoce pero no se permite usar ese modelo o función; no lo mezcles con un 401 cambiando la clave.

4. CORS, proxy y TLS: los tropiezos de la conexión directa desde el navegador

Cuando la versión web de LobeChat envía solicitudes desde el navegador, el gateway debe permitir el intercambio de recursos desde su dominio. Un fallo de CORS se manifiesta con Access to fetch ... has been blocked by CORS policy en la consola, mientras que curl funciona sin problema. Hay dos soluciones: permitir el Origin correspondiente en el gateway o usar un reenvío del lado del servidor para evitar la comprobación de origen del navegador.

Si LobeChat está detrás de Nginx, Caddy o Cloudflare, la capa de proxy debe poder acceder al gateway; no mezcles el host de la API con el proxy HTTP. Los proxies del sistema, las VPN, y las variables HTTP_PROXY y HTTPS_PROXY dentro del contenedor pueden acumularse; conserva una sola capa y excluye las direcciones internas con NO_PROXY.

Los problemas de TLS suelen aparecer como UNABLE_TO_VERIFY_LEAF_SIGNATURE, frecuentes con proxies de inspección corporativa. La solución correcta es instalar el certificado raíz de la empresa; poner NODE_TLS_REJECT_UNAUTHORIZED en 0 solo sirve para localizar el problema de forma temporal y reduce la seguridad.

Los servicios de plugins también deben permitir el Origin de LobeHub. En autoalojamiento hay que confirmar además que la función de plugins está activada y que el modelo admite llamadas a funciones; de lo contrario, el plugin fallará durante la ejecución.

5. 429: límites de velocidad, concurrencia y cuota

Un 429 tiene dos significados habituales: las solicitudes van demasiado rápido o la cuota es insuficiente. El primero suele acompañarse de rate_limit_error; el segundo, de insufficient_quota, y la dirección de la solución es la opuesta.

  • Demasiado rápido: reduce la concurrencia y el número de conversaciones y clientes abiertos a la vez; un contexto largo multiplica el consumo de tokens.
  • Cuota insuficiente: revisa el consumo y la facturación del gateway, recarga o cambia de clave; reintentar sin más no lo resuelve.
  • Si la respuesta incluye Retry-After, espera ese tiempo; si no, usa retroceso exponencial con jitter aleatorio y fija un número máximo de reintentos.
  • Cuando todo un equipo comparte una clave, varios dispositivos y ventanas comparten la misma cuota de concurrencia.

Si el 429 solo aparece en conversaciones largas, comprime primero el contexto o abre una conversación nueva y después confirma la ventana de contexto del modelo. Bajar el «número máximo de mensajes de contexto» alivia la presión del contexto, pero no sustituye la gestión del consumo.

6. Streaming interrumpido: la respuesta se detiene a mitad

LobeChat devuelve por defecto en streaming. Que se detenga a mitad no suele ser un fallo del modelo, sino un SSE almacenado en búfer por el proxy, un tiempo de espera por inactividad o una desconexión del upstream durante la generación. Se nota porque la primera mitad llega bien y la segunda termina de golpe, o porque la interfaz se queda en «escribiendo».

Primero desactiva el streaming si la versión lo permite y compara con la misma pregunta. Si la respuesta sin streaming llega completa, el problema está en la cadena SSE. El proxy inverso debe desactivar el buffering de respuesta y ampliar el tiempo de espera de lectura, por ejemplo con proxy_buffering off y proxy_read_timeout en Nginx; los CDN como Cloudflare también pueden almacenar en búfer los flujos de eventos. Los modelos de razonamiento pasan mucho tiempo «pensando» antes del texto y parecen bloqueados; confirma con una solicitud sin streaming si de verdad no hay respuesta.

7. Errores específicos de plugins y base de conocimiento

Si falla un plugin, separa tres capas: si el modelo admite llamadas a funciones, si el gateway del plugin es accesible y si el servicio del plugin permite el intercambio de origen. En autoalojamiento, confirma también que la función de plugins está habilitada. Si el modelo no admite herramientas, la interfaz puede seguir abriendo el plugin, pero la ejecución dará error.

La base de conocimiento tiene otro conjunto de dependencias: PostgreSQL con PGVector para los vectores, almacenamiento compatible con S3 para los archivos originales y un modelo de embeddings disponible. El modelo de embeddings predeterminado suele ser algún modelo de OpenAI, pero tu gateway no necesariamente ofrece el mismo; hay que configurarlo aparte. Los nombres de variables y el formato de valores se rigen por la documentación de la versión actual.

Si falla la carga, revisa la dirección del bucket, las claves, los permisos y el intercambio de origen; si falla la recuperación, revisa si el índice está construido y si la dimensión de embeddings coincide. Al cambiar de modelo de embeddings, normalmente hay que reconstruir el índice antiguo. El análisis de PDF y Word puede depender de servicios adicionales: si el texto plano se carga pero los formatos complejos fallan, investiga por ese lado.

8. Registros y evidencia

  1. Abre el panel Network de las herramientas de desarrollo, localiza la solicitud fallida y anota URL, código de estado, cuerpo de respuesta y encabezados; elimina la clave antes de compartirlo.
  2. Usa docker logs -f lobe-chat para revisar errores de arranque, fallos de migración y tiempos de conexión agotados.
  3. Usa docker exec lobe-chat env para confirmar que las variables existen, cuidando la ortografía y las comillas.
  4. Ejecuta curl o nslookup dentro del contenedor para distinguir la red del contenedor, el DNS y el gateway externo.
  5. Si necesitas registros detallados, arranca con DEBUG=lobe:* y LOG_LEVEL=debug y sigue la salida.
  6. Al abrir un ticket, incluye versión, forma de despliegue, hora, código de estado e ID de solicitud; «no conecta» no permite localizar nada.

9. Un orden de diagnóstico fijo

  1. Conecta directamente al gateway con curl y confirma si la clave, el host y el modelo son válidos.
  2. Si curl falla, revisa DNS, proxy, TLS, firewall y estado del gateway.
  3. Si curl funciona pero LobeChat falla, revisa el tipo de API, si /v1 está duplicado, el ID del modelo, CORS y el proxy del cliente.
  4. Clasifica por código de estado: 401, clave; 404, ruta y modelo; 429, consumo y concurrencia; fallo de conexión, red y certificados.
  5. Cambia una sola variable cada vez y vuelve a probar de inmediato, registrando el resultado.

Este orden separa los problemas del cliente de los del servidor. La mayoría de los llamados errores de LobeChat termina en una línea de configuración o en una capa de red. Si necesitas gestionar claves, consumo y entrada de modelos de forma unificada, puedes registrarte en ZSQH AI Gateway; los modelos disponibles y las formas de facturación se rigen por la página de precios de modelos.

Preguntas frecuentes

¿Un «Failed to fetch» en LobeChat significa que la clave está mal?

No necesariamente. El mensaje solo indica que el navegador no obtuvo una respuesta válida. Prueba la misma dirección con curl; si curl también falla, revisa DNS, proxy, firewall y certificados; si curl funciona, revisa CORS, la composición de la ruta y el proxy del cliente.

¿Por qué curl funciona pero LobeChat devuelve 401 o una respuesta vacía?

Las causas habituales son una clave de la interfaz distinta de la variable de entorno, espacios introducidos al copiar, una dirección de proxy a la que le sobra o falta /v1, y el bloqueo de origen del navegador. Compara uno por uno la dirección final y los encabezados de la solicitud.

He añadido un modelo a CUSTOM_MODELS y no aparece en la lista, ¿por qué?

Confirma que el nombre de la variable coincide con la versión actual, que las comas son inglesas y sin espacios, y que el contenedor se reconstruyó en lugar de solo reiniciarse. Haz primero una prueba mínima con -all,+un-modelo-que-sepas-que-funciona y añade los demás después.

¿Un 429 se recupera si sigo reintentando?

Los 429 por límite de velocidad pueden recuperarse tras aplicar retroceso y reducir la concurrencia; los de cuota insuficiente no se recuperan reintentando y exigen revisar la facturación, el consumo o cambiar de clave. Mira primero el tipo de error en el cuerpo de la respuesta y decide después si reintentar.

¿La falla de carga de la base de conocimiento es el mismo problema que el de la API de chat?

Normalmente no. El chat usa la interfaz de conversación; la base de conocimiento depende además de la base de datos, la extensión vectorial, el almacenamiento de objetos y el modelo de embeddings. Confirma esas configuraciones y después revisa el formato del archivo y el servicio de análisis.

Lecturas relacionadas: