Conectar Chatbox a una API personalizada puede tomar cinco minutos o convertirse en una sucesión de errores 401. La diferencia no suele estar en el cliente, sino en cómo se crea, se guarda y se delimita la clave API. Este artículo aborda cuatro aspectos: cómo crearla, cómo configurar varios modelos, dónde se almacena y cómo rotarla y diagnosticar fallos.

Nota: Chatbox es una marca de su titular; este artículo solo ofrece una explicación técnica de integración y no implica relación con el equipo de Chatbox. Los modelos y precios se consultan en la página de precios de modelos; la interfaz depende de la versión actual.

1. Distingue primero los dos orígenes de «clave»

En Chatbox pueden coexistir dos tipos de credenciales: la cuenta con la que inicias sesión en el servicio Chatbox AI y la clave API que introduces para un proveedor personalizado. Las dos tienen facturación distinta y también se diagnostican de forma diferente.

Origen Quién cobra Escenario adecuado Atención
Cuenta Chatbox AI Según el plan del cliente No quieres gestionar claves No tiene relación con la clave personalizada
Clave API propia La cobra el proveedor de API Ya tienes un gateway o una cuenta de modelos Debes guardarla y rotarla por tu cuenta
Modelo local Depende del hardware del equipo Los datos no deben salir de la máquina No requiere una clave remota

Si aparece un 401 «a pesar de haber iniciado sesión», confirma primero qué proveedor está seleccionado en la conversación actual. Haber iniciado sesión correctamente no significa que la clave del proveedor personalizado esté bien escrita.

2. Crear la clave: nombre, titularidad y permisos

Después de registrarte en ZSQH AI Gateway, crea la clave desde el panel de control. Conviene acertar en tres cosas desde el principio:

  1. Nombre trazable: usa el formato «dispositivo-uso-responsable», por ejemplo chatbox-mac-alice.
  2. Una clave por uso: separa escritorio, celular y scripts de automatización para localizar mejor los problemas.
  3. Titularidad registrada: anota en el inventario interno la fecha de creación, el responsable y el uso.

La clave completa suele mostrarse una sola vez, al crearla; al cerrar la página ya no se puede volver a consultar. Guárdala de inmediato en un gestor de contraseñas y no la envíes por captura de pantalla a un grupo. Si el panel permite límites de cuota, alcance de modelos o restricciones por IP, aplica el principio de mínimo privilegio; si no sabes qué restricciones existen, la base mínima es una clave independiente.

3. Configurar varios proveedores y modelos en Chatbox

Tener varios modelos no significa tener varias claves. Lo habitual es una clave por proveedor y varios ID de modelo bajo ese proveedor:

  1. Abre los ajustes y entra en «Proveedores de modelos».
  2. Agrega un proveedor compatible con OpenAI; se recomienda un nombre con prefijo de entorno.
  3. Introduce la Base URL, normalmente https://ai.zhongshangqihang.com/v1.
  4. Introduce la clave API y confirma que no tiene espacios delante ni detrás.
  5. Agrega manualmente los ID de modelo o intenta cargar la lista.
  6. Asigna a cada modelo su tipo: chat, visión, razonamiento o llamada a herramientas.
  7. Pulsa «Comprobar» para validar y luego vuelve a la conversación para cambiar de modelo.

El ID del modelo debe coincidir con el de la página de precios de modelos. El nombre visible puedes cambiarlo, pero el identificador API debe coincidir carácter por carácter. Nombra por separado los modelos de chat y los de visión, por ejemplo «chat-principal» y «visión-capturas», para no equivocarte al cambiar.

Si el equipo también usa clientes como Cherry Studio o LobeChat, conviene unificar los nombres de proveedor y los alias de modelo para evitar que «la misma persona use modelos distintos según el cliente».

4. Dónde se guarda la clave: local, sincronización y copias

La versión de escritorio suele guardar la configuración en el directorio de datos de la aplicación en la máquina, y la móvil, dentro del espacio aislado de la app. Las rutas concretas cambian según el sistema y la versión; no se recomienda editar los archivos de configuración a mano.

Sobre la sincronización, distingue tres cosas:

  • Historial de conversaciones: si se sincroniza y con qué alcance depende de la versión del cliente y del plan de la cuenta.
  • Ajustes: la configuración del proveedor puede sincronizarse con la cuenta o quedarse solo en la máquina.
  • Clave: no interpretes «los ajustes se sincronizan» como «la clave se sincroniza de forma segura». Muchos clientes incluyen la clave en la configuración o en los archivos de respaldo.

Por eso, las copias exportadas, los directorios de configuración migrados y las capturas compartidas deben tratarse como archivos sensibles. Al cambiar de dispositivo, es preferible volver a escribir la clave en lugar de copiar todo el directorio de datos; cuando confirmes que el equipo antiguo ya no se usa, revoca la clave anterior.

5. Mínimo privilegio: que cada clave haga solo lo que debe

No se trata de tener pocas claves, sino de que los límites estén claros. Prácticas aplicables:

  • Una clave por miembro, sin compartir.
  • Separar producción de pruebas y dar a la clave de prueba una cuota menor.
  • Guardar la clave solo en los dispositivos necesarios; en equipos públicos, eliminarla al terminar.
  • Activar presupuestos, listas blancas de modelos o alertas de uso si el panel del gateway lo permite.
  • En registros y tickets, escribir solo los últimos caracteres de la clave, nunca la clave completa.

Si el cliente admite varios proveedores, también puedes separar «trabajo» y «personal». Así, si un extremo se filtra, solo hay que revocar una clave y los demás dispositivos no se ven afectados.

6. Rotación y revocación: con un ritmo fijo

Se recomienda rotar como mínimo cada 90 días y hacerlo de inmediato ante cambios de personal, pérdida de un dispositivo o filtraciones de configuración. El orden no debe invertirse:

  1. Crea una clave nueva en el panel y añade la fecha como sufijo del nombre.
  2. Sustituye la clave del proveedor en Chatbox por el valor nuevo.
  3. Envía un mensaje de prueba y confirma que el modelo responde.
  4. Cuando la clave nueva funcione, revoca la anterior.
  5. Revisa el consumo del gateway para descartar llamadas desconocidas.
  6. Actualiza el inventario interno con la fecha de rotación.

Para validar, puedes consultar primero el código de estado con un comando:

export ZSQH_API_KEY="sk-clave-nueva"

curl -sS -o /dev/null -w "%{http_code}\n" \
  "https://ai.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY"

Un 200 indica que la autenticación pasó; un 401 obliga a revisar si la clave se copió completa. Si el gateway no expone la interfaz de lista de modelos, valida con una solicitud de conversación normal. Durante la rotación no cambies al mismo tiempo la Base URL y el ID del modelo, porque no podrás saber en qué paso está el problema.

7. Fallos comunes: clasificar por código de estado

Síntoma Causa habitual Solución
401 (credenciales rechazadas) Clave incorrecta, caducada, revocada o con espacios Crear una clave nueva y pegarla completa
403 Forbidden Sin permiso sobre el modelo, restricción regional o de política Revisar permisos y alcance de modelos en el panel
404 Not Found Ruta de la Base URL incorrecta Comprobar si debe incluir /v1
429 Too Many Requests Límite de concurrencia o de cuota Reducir concurrencia y revisar consumo y límites
5xx Fallo del servicio upstream Reintentar más tarde y conservar la hora de la solicitud

Al diagnosticar, cambia una sola variable cada vez. Primero determina si el problema es «de esta clave» o «de este modelo»: probar con otra clave o con otro modelo permite separar ambos casos con rapidez.

8. Lista de traspaso para equipos

Incluir los siguientes puntos en el documento de traspaso evita la mayoría de los problemas de «no funciona después del cambio de persona»:

  • Responsable, uso, fecha de creación y próxima rotación de cada clave.
  • Nombre del proveedor, Base URL y lista de ID de modelo.
  • Qué dispositivos guardan la clave y cuáles son compartidos.
  • Procedimiento de revocación por salida, cambio de puesto o pérdida de dispositivo.
  • Dónde consultar anomalías de consumo y a quién contactar.

Preguntas frecuentes

¿La clave se sincroniza con otros dispositivos junto con el historial?

No necesariamente. La sincronización del historial y la de la configuración son cosas distintas, y que la clave viaje con la configuración depende de la versión del cliente y de la forma de inicio de sesión. No trates la sincronización como una caja fuerte de claves; al cambiar de dispositivo es más seguro volver a escribirla.

¿Puedo usar la misma clave en escritorio y celular?

Técnicamente suele ser posible, pero no conviene mantenerlo a largo plazo. Separar las claves por dispositivo permite revocar solo una si un extremo se pierde o se filtra, sin afectar al otro.

La opción «Comprobar» del cliente pasa, pero el chat devuelve 401. ¿Por qué?

Confirma qué proveedor y qué modelo están seleccionados en la conversación: ¿son los que acabas de configurar? Cuando coexisten varios proveedores, el problema más habitual es que la solicitud se envía a otro proveedor sin clave.

Después de rotar la clave, ¿hay que volver a agregar los modelos?

Normalmente no. El ID del modelo forma parte de la configuración del proveedor y el cambio de clave solo modifica la autenticación. Si el cliente borra la lista de modelos al cambiar la clave, vuelve a agregarlos; el ID sigue siendo el de la página de precios.

¿Se puede introducir la clave en un software proxy o en una extensión del navegador?

No es recomendable. La clave solo debería estar en clientes de confianza y en el panel del gateway. Los programas proxy, las herramientas de captura y las extensiones del navegador pueden leer o reenviar la configuración; si no es necesario, no les des acceso.

Próximos pasos

La gestión de claves en Chatbox se resume así: una clave por uso, tratar la configuración y las copias como archivos sensibles y, al rotar, crear primero la nueva y revocar después la antigua. Si necesitas un punto de acceso unificado, control de consumo y permisos, puedes registrarte en ZSQH AI Gateway; los modelos y precios se consultan en la página de precios de modelos.

Lecturas relacionadas: