Cherry Studio reúne varios proveedores de modelos en un mismo cliente de escritorio. Es cómodo, pero la gestión de claves suele quedar en segundo plano: quién la creó, qué modelos puede usar, dónde se guarda, si la copia de seguridad se la lleva y si sigue activa después de que alguien deja el equipo. Este artículo propone un método aplicable, en el orden de creación, configuración, almacenamiento, sincronización, rotación, permisos y diagnóstico.

Nota: Cherry Studio es una marca de CherryHQ; este artículo solo ofrece una discusión técnica y no implica afiliación ni relación con CherryHQ. Los nombres de la interfaz, las rutas de almacenamiento y las funciones pueden cambiar según la versión; usa como referencia la versión actual del cliente y su documentación. Los modelos y precios se indican en la página de precios de modelos.

1. Distingue primero tres tipos de "clave de Cherry Studio"

El término se usa para cosas distintas:

  • Credencial del cliente o de la plataforma empresarial: sirve para iniciar sesión, gestionar la versión de empresa o usar servicios propios del fabricante; sus permisos y su facturación dependen del fabricante.
  • Clave de un proveedor de modelos: la emiten OpenAI, Anthropic, Google y otros, y se escribe en el campo del proveedor correspondiente.
  • Clave de gateway: la emite un servicio compatible con OpenAI como ZSQH AI Gateway; una sola clave puede llamar a modelos de varios fabricantes.

Este artículo trata el tercer tipo. No sirve para iniciar sesión en Cherry Studio ni para llamar a la interfaz del fabricante del cliente. Al configurar, elige "Proveedor personalizado" o la entrada compatible con OpenAI, en lugar de poner la clave del gateway en un campo exclusivo de un fabricante.

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

No crees la clave antes de saber quién la usará; 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 dispositivo y el uso, por ejemplo cherry-laptop-diario; no uses test.
  4. Define un límite de gasto y una fecha de caducidad; si la consola 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 de grupo, un documento o un ticket.

Cuando la crees, confirma con la línea de comandos que clave, dirección y modelo funcionan, y después pasa al cliente:

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 aparece el campo choices, la ruta de la petición es correcta. Un 401 apunta a la clave; un 404, a la ruta /v1; un modelo inexistente, al ID.

3. Configurar proveedor y modelo en el cliente

La entrada habitual es "Ajustes → Proveedores de modelos". Los botones cambian algo entre versiones, pero los campos son similares:

Elemento Valor recomendado Nota
Tipo de proveedor Personalizado / compatible con OpenAI No elijas un protocolo exclusivo de un fabricante
Clave de API sk-... Clave del gateway creada en la consola
Dirección de API https://ai.zhongshangqihang.com/v1 Sin barra al final
Modelo Obtener de la lista o añadir a mano El ID debe coincidir con la página de precios

Después de guardar, puedes pulsar "Obtener lista de modelos" o añadir el ID manualmente. El ID distingue mayúsculas y sufijos de versión; marca el tipo según el uso (chat, embeddings, visión, etc.), con las opciones de tu versión. Al terminar, usa "Comprobar" o envía "Responde solo OK" para validar.

4. Cómo repartir varios modelos

Tener varios modelos no significa llenar la lista, sino dar a cada asistente una sola clase de tarea:

  • Preguntas diarias: un modelo general rápido y de costo controlado.
  • Textos largos y contratos: un modelo de contexto largo, en un asistente separado para no mezclarlo con el chat diario.
  • Código y salida estructurada: un modelo estable en programación y con los parámetros necesarios.
  • Base de conocimiento: configura aparte el modelo de embeddings; si necesitas reranking, añade también el modelo correspondiente.
  • Contenido sensible: prioriza un modelo local o define antes los límites del tratamiento de datos.

Escribe un mensaje de sistema claro en cada asistente para repetir menos instrucciones. Cuantos más modelos uses, más conviene evitar pegar documentos enteros en el chat: lo que pueda entrar en la base de conocimiento, que entre allí.

5. Dónde se guarda la clave y qué cuidar en copias y sincronización

Cherry Studio guarda la configuración de proveedores y las claves en los datos locales de la aplicación. La documentación del proyecto no indica que el almacenamiento local esté cifrado, así que trátalo como un archivo sensible: activa el cifrado del disco, usa contraseña de bloqueo y no pongas el directorio de datos en un disco público ni en un repositorio de código.

En copias de seguridad, la documentación menciona WebDAV, almacenamiento compatible con S3 y un directorio local. La copia completa incluye chats, asistentes, base de conocimiento, adjuntos y configuración de proveedores, y también las claves API; la copia reducida ocupa menos, pero no restaura por completo la base de conocimiento. La documentación no describe sincronización multidispositivo en tiempo real; lo habitual es hacer copia en el equipo A y restaurar en el equipo B.

Por eso:

  • Trata el archivo de copia como un archivo de claves: no lo compartas ni lo dejes en discos en la nube no confiables.
  • Crea una clave por dispositivo; no copies la misma en todas las máquinas.
  • Haz una copia completa antes de migrar y, tras restaurar, revisa proveedores, modelos y bases de conocimiento.
  • En computadoras compartidas, usa cuentas de sistema separadas para que las configuraciones no se sobrescriban.

6. Rotación y revocación

Se recomienda rotar cada 90 días, o de inmediato si alguien deja el equipo, se pierde un dispositivo o hay sospecha de fuga. El orden correcto es "crear la nueva, cambiar, desactivar la antigua"; no borres la anterior de golpe.

  1. Crea una clave nueva con los mismos permisos y añade la fecha al nombre.
  2. Sustituye la clave API en Cherry Studio y revisa cada entrada de proveedor.
  3. Envía una petición de prueba y confirma en los registros del gateway que aparece la clave nueva.
  4. Observa la tasa de errores y el consumo para detectar scripts o dispositivos olvidados.
  5. Desactiva la clave antigua y elimínala después de un tiempo prudencial.

Cherry Studio permite configurar varias claves por proveedor y alternarlas, útil para repartir la presión de los límites; pero eso no equivale a compartir una clave: las cuentas y los responsables deben seguir separados.

7. Permisos mínimos y política de equipo

  • Una clave por persona y una por uso; las tareas automatizadas llevan su propia clave.
  • Configura límite de gasto, caducidad y, si es posible, rango de modelos; como mínimo los dos primeros.
  • Usa un gateway unificado para conservar registros de miembros, modelos y consumo que faciliten la conciliación.
  • Lleva un registro con nombre de clave, titular, uso, fecha de creación y caducidad; nunca guardes la clave completa.
  • Revisa cada mes las claves sin uso prolongado, las que superan el límite y las fallas de autenticación anómalas.
  • Incluye la creación, el traspaso y la desactivación de claves en los procesos de alta y salida.
  • Define qué datos pueden ir a modelos en la nube; evalúa los proyectos sensibles antes de usarlos.
  • Revisa periódicamente los precios de modelos; los precios y la disponibilidad cambian.

8. Diagnóstico de fallos

  • 401 / Invalid API Key: clave incorrecta, desactivada o pegada con espacios o saltos de línea.
  • 403: gasto agotado, permisos insuficientes o modelo fuera del rango permitido.
  • 404: ruta de la dirección incorrecta; revisa si /v1 se repite o falta.
  • 429: límite de frecuencia o de gasto alcanzado; consulta el consumo en la consola.
  • Tiempo de espera o corte: revisa proxy, firewall y configuración de streaming.
  • Error en la base de conocimiento: falta el modelo de embeddings o el gateway no ofrece esa interfaz.
  • No funciona tras restaurar una copia: confirma que la configuración del proveedor se restauró y vuelve a introducir o validar la clave.
  • Sigue fallando tras cambiar la clave: verifica que se guardó y comprueba en los registros del gateway si la petición llega.

Preguntas frecuentes

¿Dónde se guarda la clave API de Cherry Studio y es segura?

En los datos locales de la aplicación; la ruta exacta varía según el sistema y la versión. La documentación del proyecto no indica que esté cifrada y la copia completa incluye la clave. Protégela como un archivo sensible, activa el cifrado del disco y evita sincronizarla a ubicaciones públicas.

¿Puede una clave servir para varios modelos?

Normalmente sí, siempre que el gateway permita a esa clave llamar a esos modelos. Limitar el rango depende de la consola; si no es posible, controla el impacto con límite de gasto, caducidad y registros.

¿La copia en WebDAV sube la clave?

La documentación indica que la copia completa incluye la configuración de proveedores y las claves API. Elige un almacenamiento confiable, activa el cifrado en tránsito y no compartas el archivo; si te preocupa la clave, valora una copia reducida o retírala antes de copiar.

¿Cómo migro la configuración y la clave a otra computadora?

Haz primero una copia completa, súbela a WebDAV o S3 y restaura en el equipo nuevo; también puedes migrar el directorio local. Después revisa proveedores, modelos, bases de conocimiento y modelo predeterminado, y crea una clave propia para el dispositivo nuevo.

¿Qué hago primero si una clave se filtra?

Desactívala o elimínala para cortar el daño y luego revisa consumo anómalo, origen de las llamadas y franja horaria. Después revisa copias, repositorios, historiales de chat y capturas; si hace falta, rota las demás credenciales del mismo entorno.

Resumen

Configurar claves en Cherry Studio no es complejo; lo difícil es gestionarlas a largo plazo: nombres trazables, límites definidos, almacenamiento protegido, copias acotadas y capacidad de reaccionar ante una fuga. Puedes 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: