Cherry Studio es un cliente de IA de escritorio muy usado, compatible con Windows, macOS y Linux. No ofrece modelos propios: los modelos vienen del proveedor de API que configures. Además de los proveedores integrados, permite añadir un endpoint personalizado compatible con OpenAI, algo muy práctico para equipos que usan un gateway unificado: una Base URL y una clave permiten cambiar entre varios modelos.

Este artículo sigue las versiones habituales de 2026 y recorre la instalación, el proveedor, los modelos, los asistentes, la base de conocimiento y el uso en equipo. Los nombres de la interfaz cambian según la versión; toma como referencia la versión actual.

Nota: Cherry Studio es un producto y una marca de su titular; OpenAI es una marca de OpenAI, Inc. Este artículo solo describe la integración técnica y no implica afiliación ni relación con esas empresas. Los modelos, el alcance de la API y los precios se indican en la página de precios de modelos.

1. Instalación: usa los canales del proyecto

Cherry Studio ofrece instaladores de escritorio; las vías habituales de descarga son el sitio del proyecto y GitHub Releases. Elige el paquete según tu sistema:

  • Windows: descarga el instalador y sigue las indicaciones.
  • macOS: descarga el dmg y arrástralo a la carpeta de Aplicaciones; si el sistema lo bloquea la primera vez, sigue el aviso para permitirlo.
  • Linux: instala el AppImage o el paquete de tu distribución que publica el proyecto.

No conviene usar "versiones portables" ni paquetes modificados de origen desconocido: el cliente de escritorio guarda claves API y el historial de chat, y un instalador no verificado supone un riesgo alto. Tras instalar, abre "Acerca de" en Ajustes para confirmar la versión y luego decide si actualizas; en versiones antiguas los botones y los campos pueden estar en otro lugar.

2. Prepara tres parámetros

Un proveedor personalizado solo necesita tres datos, pero cada uno se puede llenar mal:

Elemento Valor recomendado Nota
Tipo de proveedor OpenAI Usa el protocolo compatible con OpenAI
Dirección de API https://ai.zhongshangqihang.com/v1 Llena hasta /v1, no la ruta completa del endpoint
Clave de API sk-... Créala en la consola del gateway y nómbrala por proyecto
ID del modelo El identificador de API de la página de precios No es el nombre visible de la web

La clave se crea en la consola después de registrarte en ZSQH AI Gateway. Se recomienda una clave por proyecto para ver consumo, límites y revocación. Copia el ID del modelo desde la página de precios de modelos y revisa mayúsculas, guiones y sufijos de versión.

3. Añadir un proveedor personalizado

Con las versiones habituales actuales, el orden es el siguiente:

  1. Abre Cherry Studio y haz clic en el engranaje de la esquina inferior izquierda para entrar en Ajustes.
  2. Selecciona "Proveedores de modelos".
  3. Haz clic en "+ Añadir proveedor", debajo de la lista.
  4. En "Añadir proveedor personalizado", escribe el nombre, por ejemplo "Gateway ZSQH".
  5. Rellena la "Clave de API".
  6. En "Configuración del endpoint", elige OpenAI; si el gateway ofrece el protocolo Responses, también puedes seleccionar OpenAI Responses en "Más ajustes".
  7. Escribe la dirección de API, por ejemplo https://ai.zhongshangqihang.com/v1.
  8. Haz clic en "Añadir" para guardar.

Si tu versión no muestra "+ Añadir proveedor", actualiza el cliente primero. Los nombres del tipo de endpoint varían, pero los campos esenciales no cambian: nombre, clave y dirección. La generación y la edición de imágenes tienen una Base URL aparte; no la mezcles con la de los modelos de chat.

4. Añadir modelos y comprobar la conexión

Después de guardar el proveedor, vuelve a su lista de modelos. Hay dos formas de añadirlos:

  • Obtener la lista de modelos: el cliente pide al gateway los modelos disponibles y tú marcas los que necesites.
  • Añadir manualmente: haz clic en "+" y escribe el ID del modelo. Úsalo cuando el gateway no exponga la lista o la consulta falle.

El ID debe coincidir exactamente con el de la página de precios. Tras añadirlo a mano, confirma que el tipo sea "Chat" o "Conversación"; si eliges otro tipo, el modelo no aparecerá en el selector del chat. Los modelos de embeddings y de imagen se añaden por separado según su uso.

El botón "Comprobar" de la interfaz sirve sobre todo para validar la clave, no para confirmar que cada modelo esté habilitado para ti. La prueba completa es crear una conversación, elegir el modelo recién añadido y enviar "Responde solo OK".

5. Valida con curl antes de volver al cliente

Cuando la configuración se atasca, una petición mínima te dice si el problema está en el gateway o en el cliente:

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 trae choices, la dirección, la clave y el modelo funcionan al menos; el problema estará seguramente en un campo del cliente o en el proxy de red. Un 401 apunta primero a la clave y a espacios sobrantes; un 404, a /v1 y al ID del modelo; un 429, al consumo y la concurrencia. Cambia una sola variable a la vez para no mezclar causas.

6. Asistentes: asigna cada modelo a una tarea

Los "asistentes" de Cherry Studio guardan un mensaje de sistema, un modelo y parámetros, y sirven para fijar trabajos repetitivos. Una división práctica:

  • Preguntas diarias: un modelo general rápido y de costo controlado.
  • Resúmenes largos: un asistente aparte con modelo de contexto largo y una estructura de salida definida en el mensaje.
  • Tareas de código: un modelo con buena capacidad de programación y la instrucción de leer los archivos antes de modificar.
  • Traducción y corrección de estilo: un asistente para cada una, con glosario y criterios en el mensaje de sistema.
  • Cada asistente debe resolver un solo tipo de problema; así el mensaje no crece sin control.

También puedes fijar un modelo predeterminado en Ajustes para reducir la elección en cada conversación nueva. Cuantos más modelos uses, más importa controlar el contexto: lo que pueda ir a la base de conocimiento, que vaya allí; lo que se pueda resumir antes, no se pega entero una y otra vez.

7. Base de conocimiento: el modelo de embeddings no es obligatorio

La entrada está en "Base de conocimiento", a la izquierda. Haz clic en "Nuevo", pon un nombre que describa el alcance de los documentos y elige el modelo de embeddings. La versión actual ofrece tres opciones:

  • No usar: solo recuperación por palabras clave BM25, sin configuración adicional; sirve para validar el flujo.
  • Modelo de embeddings en la nube: requiere que el servicio de embeddings correspondiente funcione; la recuperación combina palabras clave y vectores.
  • Modelo de embeddings local: descárgalo primero en "Ajustes → Modelos locales" y luego selecciónalo en la base de conocimiento.

Los embeddings pasan por el gateway: confirma antes que ofrece la interfaz de embeddings y el modelo adecuado; si no, elige "No usar" o un modelo local. Después de crear la base, pulsa "Añadir material" e importa uno o dos archivos con respuestas claras; prueba a preguntar cuando terminen de procesarse.

Cambiar el modelo de embeddings puede activar una "reconstrucción de la base de conocimiento". Antes de reconstruir, confirma que el nuevo modelo funciona y no cambies a la vez el modelo y la configuración de fragmentación: de lo contrario no sabrás qué provocó el cambio de resultados.

8. Orden de diagnóstico de fallos habituales

Síntoma Causa habitual Qué hacer
401 (fallo de autenticación) Clave incorrecta, con espacios o sin guardar Vuelve a pegarla y confirma que pertenece a este gateway
404 Not Found Sobra o falta /v1 en la dirección Deja solo hasta /v1, no la ruta completa
model not found ID erróneo o modelo no habilitado Copia el identificador exacto de la página de precios
Falla la lista de modelos El gateway no expone esa interfaz Añade el ID del modelo manualmente
Mala calidad en la base de conocimiento Fragmentación, método de recuperación o documentos Prueba con un conjunto pequeño antes de ajustar
El chat se corta a mitad Proxy, firewall o inestabilidad de red Desactiva el streaming y revisa proxy y tiempos de espera

Una red corporativa o un proxy pueden bloquear las respuestas SSE: el síntoma es que la petición sale pero la respuesta no llega. Desactiva el streaming de forma temporal; si la respuesta sin streaming funciona, revisa el proxy y el firewall en lugar de cambiar de modelo una y otra vez.

9. Uso en equipo: se comparte la norma, no la clave

Cherry Studio es un cliente de escritorio y la documentación pública no presenta la gestión de permisos multiusuario como capacidad central. En equipo se parece más a "una norma de configuración común + el cliente local de cada persona". Recomendaciones:

  • Cada persona usa su propia clave del gateway, con su nombre; si alguien sale o hay una fuga, se revoca por separado.
  • Revisa consumo y límites en el gateway y reparte costos por proyecto.
  • Reúne los mensajes de sistema de los asistentes habituales en plantillas de texto y distribúyelos.
  • Guarda los materiales de la base de conocimiento en una ubicación compartida y controlada, para no mantener versiones distintas.
  • Usa WebDAV o almacenamiento compatible con S3 para las copias, sabiendo que incluyen la configuración del proveedor y la clave API.
  • No envíes archivos de copia al chat de grupo ni los dejes en discos compartidos no confiables.
  • No guardes claves de larga duración en computadoras públicas ni pegues datos privados de clientes o contratos sin anonimizar en una conversación.

Si el equipo necesita auditoría, cuotas y permisos unificados, el control debe estar en el gateway.

Preguntas frecuentes

¿Cherry Studio es gratis?

El cliente se puede usar gratis, pero el costo de las llamadas a los modelos lo cobra el proveedor de API que configures. Confirma siempre la versión actual del cliente y la página de precios del gateway.

¿La Base URL debe incluir /v1?

La mayoría de las configuraciones compatibles con OpenAI lo necesitan: usa https://ai.zhongshangqihang.com/v1. No escribas /v1/chat/completions, porque el cliente añade la ruta del endpoint por su cuenta.

¿Qué hago si falla la lista de modelos?

Primero confirma si el gateway expone la interfaz de lista. Si no la ofrece o la petición falla, pulsa "+" y escribe el ID a mano; el resultado es equivalente. El ID válido es el identificador de API de la página de precios.

¿Es obligatorio configurar embeddings para la base de conocimiento?

No. La versión actual permite "No usar" y responder con recuperación BM25 por palabras clave. Si necesitas búsqueda vectorial, configura después un modelo de embeddings en la nube o local y confirma que el servicio responde.

¿Puede el equipo compartir una sola clave?

No es recomendable. Una clave compartida impide separar el consumo y una fuga afecta a todo el grupo. Emite claves por persona, proyecto o entorno, y apóyate en los límites y los informes de uso del gateway.

Próximos pasos

La integración con Cherry Studio no es complicada; lo difícil es alinear la Base URL, la clave y el ID del modelo. Primero haz que curl funcione y después pasa al cliente; si algo falla, revisa en el orden 401, 404 y model not found. Si necesitas un punto de acceso unificado y gestión de consumo, puedes registrarte en ZSQH AI Gateway; los modelos y precios se indican en la página de precios de modelos.

Lecturas relacionadas: