Cherry Studio réunit plusieurs fournisseurs de modèles dans un même client de bureau. L'usage est simple, mais la gestion des clés est souvent négligée : qui les a créées, quels modèles elles peuvent appeler, où elles sont stockées, si une sauvegarde les emporte, et si elles restent actives après le départ d'un collaborateur. Cet article suit l'ordre création, configuration, stockage, synchronisation, rotation, permissions et dépannage, avec des pratiques directement applicables.

Remarque : Cherry Studio est une marque de CherryHQ. Cet article est purement technique et n'implique aucune affiliation ni coopération avec CherryHQ. Les noms d'interface, modes de stockage et entrées de menu peuvent changer selon la version : référez-vous au client installé et à la documentation officielle. Modèles et prix figurent sur la page tarifs des modèles.

1. Distinguer d'abord trois types de « clé Cherry Studio »

L'expression est souvent employée pour des objets différents :

  • Identifiants du client ou de la plateforme entreprise : utilisés pour la connexion, l'administration de la version entreprise ou les services propres à l'éditeur ; droits et facturation dépendent de l'éditeur.
  • Clés de fournisseurs de modèles : émises par OpenAI, Anthropic, Google, etc., à saisir dans le champ du fournisseur correspondant.
  • Clés de passerelle : émises par un service compatible OpenAI comme ZSQH AI Gateway ; une seule clé donne accès à plusieurs modèles.

Cet article traite le troisième cas. Cette clé ne sert pas à se connecter à Cherry Studio et n'appelle pas les interfaces de l'éditeur du client. Dans la configuration, choisissez « fournisseur personnalisé » ou une entrée compatible OpenAI, et non le champ dédié d'un fournisseur précis.

2. Créer une clé : définir d'abord l'usage et le plafond

Ne créez pas une clé avant de savoir à qui elle servira ; l'ordre inverse fait gagner du temps :

  1. Ouvrez la page d'inscription ZSQH AI Gateway, créez un compte et connectez-vous à la console.
  2. Rendez-vous dans la page des clés API et créez une nouvelle clé.
  3. Nommez-la avec l'utilisateur, l'appareil et l'usage, par exemple cherry-laptop-quotidien, jamais test.
  4. Définissez un plafond et une date d'expiration ; si la console permet de restreindre les modèles, limitez-les par projet.
  5. Vérifiez le solde du compte pour ne pas découvrir le problème après la configuration.
  6. Copiez la clé dans un gestionnaire de mots de passe, sans la coller d'abord dans un groupe de discussion, un document ou un ticket.

Une fois la clé créée, confirmez en ligne de commande que la clé, l'adresse et le modèle fonctionnent ensemble, avant de passer au client :

export ZSQH_API_KEY="sk-votre-clé"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"votre-ID-de-modèle","messages":[{"role":"user","content":"Réponds seulement OK"}]}'

Si la réponse contient le champ choices, la chaîne de requête fonctionne. En cas de 401, vérifiez d'abord la clé ; de 404, le chemin /v1 ; de modèle inexistant, l'identifiant du modèle.

3. Configurer le fournisseur et les modèles dans le client

L'entrée habituelle de Cherry Studio est « Paramètres → Services de modèles ». Les libellés varient selon les versions, mais les champs restent proches :

Champ Valeur conseillée Explication
Type de fournisseur Personnalisé / compatible OpenAI Ne pas choisir un protocole propriétaire
Clé API sk-... Clé de passerelle créée dans la console
Adresse API https://ai.zhongshangqihang.com/v1 Sans barre oblique finale
Modèle Récupéré dans la liste ou ajouté à la main Identifiant identique à la page tarifs

Après l'enregistrement, cliquez sur « Récupérer la liste des modèles » ou ajoutez l'identifiant manuellement. Respectez la casse et le suffixe de version ; indiquez le type selon l'usage (dialogue, embedding, vision, etc.) ; les options exactes dépendent de la version. Terminez par « Vérifier » ou par un message « Réponds seulement OK ».

4. Répartir les rôles entre plusieurs modèles

Multiplier les modèles ne consiste pas à remplir une liste, mais à affecter chaque assistant à un type de tâche :

  • Questions courantes : un modèle généraliste rapide et au coût maîtrisé.
  • Documents longs et contrats : un modèle à long contexte, dans un assistant séparé pour ne pas polluer les échanges quotidiens.
  • Code et sorties structurées : un modèle stable en programmation, avec les paramètres requis disponibles.
  • Base de connaissances : configurer un modèle d'embedding dédié, puis un modèle de reranking si nécessaire.
  • Contenus sensibles : privilégier un modèle local ou définir d'abord les limites de traitement des données.

Rédigez un prompt système clair pour chaque assistant afin de réduire les rappels. Plus vous avez de modèles, plus il faut éviter de recoller un document entier dans la conversation : ce qui peut être indexé doit l'être.

5. Où sont stockées les clés, et comment sauvegarder ou synchroniser

Cherry Studio conserve la configuration des fournisseurs et les clés dans les données applicatives locales. La documentation officielle n'indique pas que le stockage local soit chiffré : traitez-le comme un fichier sensible. Activez le chiffrement du disque et un mot de passe de verrouillage, et ne placez pas le dossier de données dans un cloud public ou un dépôt de code.

Pour la sauvegarde, la documentation officielle mentionne WebDAV, un stockage compatible S3 et un répertoire local. Une sauvegarde complète inclut conversations, assistants, base de connaissances, pièces jointes et configuration des fournisseurs, y compris les clés API ; une sauvegarde allégée est plus petite, mais ne permet pas de restaurer entièrement la base de connaissances. La documentation ne décrit pas de synchronisation temps réel multi-appareils : la pratique courante consiste à sauvegarder sur un ordinateur A et à restaurer sur un ordinateur B.

Par conséquent :

  • Gérez les fichiers de sauvegarde comme des fichiers de clés : ne les partagez pas, ne les déposez pas sur un cloud non fiable.
  • Créez une clé par appareil au lieu de copier la même partout.
  • Faites une sauvegarde complète avant toute migration, puis vérifiez fournisseurs, modèles et base de connaissances après restauration.
  • Sur un ordinateur partagé, utilisez des comptes système distincts pour éviter l'écrasement des configurations.

6. Rotation et révocation

Prévoyez une rotation tous les 90 jours, ou immédiatement en cas de départ, de perte d'appareil ou de suspicion de fuite. La règle est « créer la nouvelle, basculer, puis désactiver l'ancienne » ; ne supprimez pas directement l'ancienne clé.

  1. Créez une nouvelle clé aux mêmes droits, avec la date en suffixe du nom.
  2. Remplacez la clé API dans Cherry Studio et vérifiez chaque entrée de fournisseur.
  3. Envoyez une requête de test et confirmez que les journaux de la passerelle enregistrent la nouvelle clé.
  4. Surveillez le taux d'erreur et l'usage pour repérer un script ou un appareil oublié.
  5. Désactivez l'ancienne clé, puis supprimez-la après un délai de sécurité.

Cherry Studio permet de configurer plusieurs clés pour un même fournisseur et de les alterner, ce qui répartit la pression des limites de débit ; cela ne dispense pas de tracer les comptes et les responsables.

7. Moindre privilège et politique d'équipe

  • Une clé par personne, une clé par usage ; les tâches automatisées ont la leur.
  • Réglez le quota, l'expiration et, si possible, le périmètre de modèles ; au minimum les deux premiers.
  • Passez par une passerelle unifiée pour conserver les journaux de membres, de modèles et d'usage, utiles à la réconciliation.
  • Tenez un registre : nom de clé, détenteur, usage, date de création et d'expiration, jamais la clé complète.
  • Vérifiez chaque mois les clés inutilisées, les dépassements et les anomalies d'authentification.
  • Intégrez création, transmission et désactivation des clés aux procédures d'arrivée et de départ.
  • Définissez quelles données peuvent aller vers un modèle cloud ; évaluez les projets sensibles avant usage.
  • Revoyez régulièrement la page tarifs des modèles : prix et modèles disponibles évoluent.

8. Dépannage

  • 401 / Invalid API Key : clé erronée, désactivée, ou espace et retour à la ligne collés avec.
  • 403 : quota épuisé, droits insuffisants ou modèle hors périmètre.
  • 404 : chemin d'API incorrect ; vérifiez que /v1 n'est ni répété ni absent.
  • 429 : limitation de débit ou plafond atteint ; consultez l'usage dans la console.
  • Timeout ou flux interrompu : vérifiez proxy, pare-feu et réglages de sortie en streaming.
  • Erreur de base de connaissances : modèle d'embedding non configuré ou interface d'embedding absente de la passerelle.
  • Inutilisable après restauration : confirmez que la configuration fournisseur est restaurée, puis ressaisissez ou validez la clé.
  • Échec persistant après changement de clé : vérifiez l'enregistrement et l'arrivée de la requête dans les journaux de la passerelle.

Questions fréquentes

Où est stockée la clé API de Cherry Studio, et est-elle sécurisée ?

Dans les données applicatives locales ; le chemin dépend du système et de la version. La documentation officielle ne promet pas de chiffrement, et une sauvegarde complète contient les clés. Protégez-la comme un fichier sensible, activez le chiffrement du disque et évitez toute synchronisation vers un emplacement public.

Une clé peut-elle servir à plusieurs modèles ?

En général oui, si la passerelle autorise cette clé à appeler ces modèles. La restriction dépend des capacités de la console ; à défaut, limitez l'impact par le quota, l'expiration et les journaux.

La sauvegarde WebDAV envoie-t-elle les clés ?

La documentation officielle indique qu'une sauvegarde complète contient la configuration des fournisseurs et les clés API. Choisissez un stockage de confiance, activez le chiffrement en transit et ne partagez pas les fichiers. Si les clés sont sensibles, évaluez une sauvegarde allégée ou retirez-les avant l'envoi.

Comment migrer configuration et clés vers un nouvel ordinateur ?

Faites une sauvegarde complète, envoyez-la vers WebDAV ou S3, puis restaurez sur le nouvel appareil ; vous pouvez aussi copier le répertoire de sauvegarde local. Vérifiez ensuite fournisseurs, modèles, base de connaissances et modèle par défaut, et créez une clé dédiée au nouvel appareil.

Que faire en premier après une fuite de clé ?

Désactivez ou supprimez la clé pour limiter les dégâts, puis examinez l'usage anormal, les sources d'appel et les plages horaires. Contrôlez ensuite sauvegardes, dépôts, historiques de discussion et captures, et faites tourner les autres identifiants du même environnement si nécessaire.

En résumé

Configurer une clé dans Cherry Studio n'est pas complexe ; la difficulté est la gestion dans la durée : nom traçable, quota plafonné, stockage protégé, sauvegardes délimitées, fuite contenue. Vous pouvez créer un compte ZSQH AI Gateway pour générer une clé dédiée au client, puis resserrer la politique d'équipe une fois le fonctionnement validé, en revoyant les coûts sur la page tarifs des modèles.

Lectures associées :