LobeChat reúne varios proveedores de modelos en una sola interfaz, lo que resulta cómodo, pero la gestión de claves suele quedar de lado: quién la creó, qué modelos puede llamar, si vive en el navegador o en la base de datos, si una copia de seguridad se la lleva y si sigue activa cuando un miembro deja el equipo. Este artículo propone un método aplicable, en el orden de creación, configuración, almacenamiento, rotación, política de equipo y diagnóstico.

Nota: LobeChat y LobeHub son productos y marcas de sus respectivos titulares; OpenAI es una marca de OpenAI, Inc. Este artículo solo ofrece una explicación técnica y no implica subordinación ni relación de colaboración con esas empresas. La interfaz, los nombres de variables y la forma de almacenamiento cambian según la versión; guíate por la documentación actual del proyecto. Los modelos y precios se rigen por la página de precios de modelos del sitio.

1. Distingue primero tres tipos de clave

La expresión «clave API de LobeChat» suele referirse a tres cosas distintas:

  • Credencial de cuenta o plataforma: sirve para entrar en LobeHub Cloud o en una plataforma empresarial; los permisos los define la plataforma.
  • Clave del fabricante del modelo: la emiten OpenAI, Anthropic, Google y otros, y se introduce en el proveedor correspondiente.
  • Clave de gateway: la emite un gateway compatible con OpenAI; una sola clave puede llamar a modelos de varias empresas.

Este artículo trata la tercera, aunque también se aplica a otras claves de fabricante que introduzcas en LobeChat. La clave de gateway no sirve para iniciar sesión ni para llamar a interfaces privadas de un fabricante; al configurar, elige la entrada compatible con OpenAI o un proveedor personalizado, en lugar de pegar la clave en un campo exclusivo de un fabricante.

2. Crear la clave: primero define uso y límite

No crees la clave y después pienses para quién es. Invertir el orden ahorra muchos problemas:

  1. Abre la página de registro de ZSQH AI Gateway, completa el registro y entra en la consola.
  2. Ve a la página de claves API y crea una nueva.
  3. Escribe en el nombre el usuario, el entorno y el uso, por ejemplo lobe-team-prod; no uses test.
  4. Define un límite de cuota y una fecha de vencimiento; si la plataforma permite limitar modelos, restringe los disponibles por proyecto.
  5. Confirma el saldo de la cuenta para no descubrir al final que no puedes llamar.
  6. Copia la clave en un gestor de contraseñas; no la envíes primero a un chat grupal, un documento o un ticket.

Cuando esté creada, confirma por línea de comandos que clave, dirección y modelo se comunican:

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"}]}'

Si la respuesta incluye el campo choices, la cadena de solicitud funciona. Si devuelve 401, revisa primero la clave; si devuelve 404, revisa la ruta /v1; si indica que el modelo no existe, verifica el ID.

3. Variables de entorno del servidor y configuración por usuario

Las claves de LobeChat pueden estar en dos niveles, con efectos muy distintos:

Nivel Dónde se configura Alcance Adecuado para
Variables de entorno del servidor Entorno de despliegue, lobehub.env, gestor de secretos Toda la instancia Entrada unificada del equipo, modelos predeterminados
Configuración de proveedor por usuario Interfaz de ajustes tras iniciar sesión Una sola cuenta Clave propia, pruebas temporales
Clave del lado del gateway Consola del gateway Medición por clave Límites, auditoría, revocación

La variable OPENAI_API_KEY del servidor es una clave compartida: cualquiera que use esa instancia puede llamar con ella. El usuario también puede introducir su propia clave en los ajustes; en el modo de base de datos del servidor, la clave del usuario se cifra y se guarda en la base, y el cifrado depende de KEY_VAULTS_SECRET. Si esa variable se pierde, las claves de usuario ya guardadas pueden quedar ilegibles, así que conviene respaldarla durante el despliegue.

Las variables de servidor habituales son:

  • OPENAI_API_KEY: clave compartida del gateway.
  • OPENAI_PROXY_URL: sobrescribe la dirección predeterminada de OpenAI y apunta a un gateway compatible.
  • OPENAI_MODEL_LIST: controla la lista de modelos; no concede permisos adicionales.
  • KEY_VAULTS_SECRET: cifra las claves de usuario y las direcciones de proxy guardadas en la base de datos.
  • AUTH_SECRET: se relaciona con sesiones y autenticación; debe generarse por separado.
  • DATABASE_URL: cadena de conexión a PostgreSQL, obligatoria en el modo de servidor.

No escribas la misma clave a la vez en las variables de entorno y en la configuración de usuario, salvo que tengas claro qué nivel prevalece. Al diagnosticar, confirma primero qué clave usa la solicitud y después revisa los registros del gateway.

4. Cómo configurar varios modelos y proveedores

La sintaxis de OPENAI_MODEL_LIST es: + añade, - oculta, ID-de-modelo=nombre visible<capacidades> personaliza la presentación y las capacidades, y los elementos se separan con comas inglesas. Por ejemplo:

-all,+modelo-a=Preguntas diarias<128000:fc:vision>,+modelo-b=Análisis largo<200000:reasoning>

El primer elemento entre corchetes angulares es el contexto máximo; después van las etiquetas de capacidad, entre las habituales fc (llamada a funciones), vision (visión), file (archivos), reasoning (razonamiento) y search (búsqueda web). Las etiquetas deben reflejar la capacidad real del modelo: un error no da aviso inmediato, pero hace fallar tareas de plugins o imágenes.

El principio para varios proveedores es «una configuración por punto de acceso upstream»:

  • Un solo gateway merece una sola entrada de proveedor; usa la lista de modelos para separar usos.
  • Gateways o entornos distintos llevan entradas separadas, con el entorno en el nombre.
  • Cada entrada usa una clave independiente, para poder limitar y revocar por separado.
  • No dupliques la misma clave para aparentar más modelos; las cuentas se vuelven confusas.

La lista de modelos solo decide qué se muestra; los permisos reales están en el gateway. Para limitar qué modelos puede llamar una clave, configúralo en la consola, no confíes en ocultarlos en el frontend.

5. Dónde se guardan las claves y por dónde se filtran

Según la forma de despliegue:

  • Modo local o de navegador: la configuración se guarda en el almacenamiento local del navegador y puede desaparecer al cambiar de equipo o borrar la caché. No guardes claves de larga duración en una computadora compartida.
  • Modo de base de datos del servidor: las claves de usuario se cifran y se escriben en PostgreSQL; el cifrado depende de KEY_VAULTS_SECRET. La copia de seguridad contiene texto cifrado, pero el archivo de la clave debe guardarse aparte.
  • Archivo de variables de entorno: lobehub.env está en texto plano; dale permisos de lectura solo para la cuenta del servicio, no lo subas a Git ni lo distribuyas con la imagen.
  • S3 y copias de seguridad: S3 guarda archivos y material de la base de conocimiento y normalmente no contiene claves; las copias de la base y la configuración de despliegue sí pueden incluir datos sensibles de forma indirecta.

También hay que cuidar las capturas de pantalla, los tickets y los historiales de chat. Muchas filtraciones no vienen de una base de datos comprometida, sino de una clave pegada en el lugar equivocado.

6. Rotación y revocación

Se recomienda rotar cada 90 días, o de inmediato si un miembro deja el equipo, se pierde un dispositivo o hay sospecha de filtración. El orden es «crear primero, cambiar después, desactivar al final»:

  1. Crea una clave nueva con los mismos permisos y añade la fecha al nombre.
  2. Actualiza lobehub.env o la configuración de proveedor del usuario, revisando cada entrada.
  3. Reinicia o reconstruye el servicio y envía una solicitud de prueba.
  4. Confirma en los registros del gateway que la clave nueva registra llamadas y la antigua no recibe tráfico nuevo.
  5. Observa durante un tiempo la tasa de errores y el consumo para detectar scripts o dispositivos olvidados.
  6. Desactiva la clave antigua y conserva el registro un tiempo antes de eliminarla.

No borres la clave antigua antes de configurar la nueva: quedaría una ventana sin servicio. Si sospechas una filtración, desactiva primero para contener el daño y después revisa consumo anómalo y origen de las llamadas.

7. Política de equipo: una clave por persona, entornos separados

  • Una clave por persona y una por uso; las tareas automatizadas llevan su propia clave.
  • Desarrollo, pruebas y producción usan claves independientes para que el tráfico de pruebas no contamine las cuentas de producción.
  • Si se pueden definir cuota, vencimiento y rango de modelos, define todo; como mínimo, los dos primeros.
  • La clave compartida del servidor se reserva para la entrada predeterminada, con una cuota conservadora para detectar anomalías con facilidad.
  • Mantén un inventario: solo nombre de la clave, titular, uso, fecha de creación y vencimiento; nunca la clave completa.
  • Revisa cada mes las claves sin uso prolongado, las que superan la cuota y las anomalías de autenticación.
  • Incluye la creación, entrega y desactivación de claves en los procesos de alta y salida del personal.
  • Define qué datos pueden enviarse a modelos en la nube; evalúa los proyectos sensibles antes de usarlos.
  • Revisa periódicamente los precios de modelos, porque los precios y el catálogo cambian.

Aunque el equipo sea pequeño, conviene conservar el registro de «quién solicita, quién usa y cuándo caduca». Ante un incidente, se localiza rápido.

8. Diagnóstico de fallos

Síntoma Causa habitual Solución
401 Unauthorized Clave incorrecta, desactivada o con espacios Vuelve a copiarla y confirma que pertenece al gateway actual
403 Forbidden Cuota agotada, permisos insuficientes o modelos restringidos Revisa cuota y permisos de modelos en la consola
404 Not Found Ruta de la dirección de API incorrecta Conserva solo hasta /v1
429 Too Many Requests Límite de velocidad o de cuota alcanzado Revisa consumo y configuración de concurrencia
model not found ID de modelo incorrecto o no habilitado Copia el identificador exacto de la página de precios
La clave de usuario deja de funcionar KEY_VAULTS_SECRET cambió o falta Restaura el secreto original y vuelve a introducir la clave
curl funciona, la interfaz falla Configuración no guardada, caché del navegador o proxy de red Guarda de nuevo y revisa el proxy

Al diagnosticar, distingue primero si «la aplicación no leyó la configuración» o si «el gateway rechazó la solicitud»: en el primer caso, revisa variables de entorno, base de datos y registros; en el segundo, el código de estado HTTP.

Preguntas frecuentes

¿La clave API de LobeChat se guarda en el navegador o en el servidor?

Depende del despliegue. En el modo de navegador o local se guarda en el almacenamiento local; en el modo de base de datos del servidor, la clave del usuario se cifra y se escribe en PostgreSQL, mientras que la clave compartida de las variables de entorno existe en texto plano dentro del entorno de despliegue.

Si el servidor ya tiene OPENAI_API_KEY, ¿el usuario debe rellenar algo?

No. La clave del servidor es compartida y los usuarios de la instancia pueden llamar directamente. El usuario también puede introducir su propia clave para tener una cuota independiente o usar otro proveedor; la prioridad depende de la versión actual.

¿Una clave puede llamar a varios modelos?

Normalmente sí, siempre que el gateway permita a esa clave llamar a esos modelos. La lista de modelos solo controla la visualización; los permisos y la cuota reales se configuran en la consola del gateway.

¿Qué efecto tiene cambiar KEY_VAULTS_SECRET?

Las claves de usuario y direcciones de proxy ya cifradas pueden quedar ilegibles, y la clave del usuario aparece de repente como inválida. Antes de cambiarla, haz una copia de seguridad y consulta las instrucciones de migración de la versión actual; no la sustituyas sin más.

¿Qué hacer primero si se filtra una clave?

Desactiva o elimina la clave para contener el daño y después revisa consumo anómalo, origen y franja horaria de las llamadas. A continuación revisa el archivo de variables de entorno, las copias de la base de datos, los repositorios, los historiales de chat y las capturas; si hace falta, rota las demás credenciales del mismo entorno.

Resumen

La configuración de claves en LobeChat no es complicada; lo difícil es gestionarlas a largo plazo: nombres trazables, cuotas con límite, almacenamiento protegido, copias con límites claros y capacidad de contener una filtración. Puedes empezar por registrarte en ZSQH AI Gateway y crear una clave exclusiva para el cliente; cuando funcione, ajusta la política del equipo y revisa el costo con los precios de modelos.

Lecturas relacionadas: