Cherry Studio
Configurez et utilisez AGTCloud dans Cherry Studio.
Cherry Studio est un client de bureau multimodèle pour Windows, macOS et Linux. Ajoutez un fournisseur OpenAI personnalisé pour utiliser l’endpoint Chat Completions compatible d’AGTCloud.
Ce tutoriel couvre uniquement la conversation ordinaire. Les fichiers, images, outils, raisonnement, bases de connaissances, Agent, MCP et autres fonctions avancées dépendent de la version et des capacités réelles du modèle.
Prérequis
Avant de commencer, vérifiez que vous avez :
- Préparé un appareil Windows, macOS ou Linux pris en charge ;
- Créé un compte AGTCloud et ouvert une session ;
- Créé une API Key AGTCloud dans API Keys ;
- Copié dans le catalogue de modèles un ID accessible à l’API Key et compatible Chat Completions.
Télécharger et installer Cherry Studio
Téléchargez depuis la page officielle. La page et les noms des packages peuvent changer : choisissez la version actuelle correspondant au système et au processeur.
- Sur un PC Intel ou AMD courant, choisissez l’installation standard Windows x64 ;
- Sur Windows ARM, choisissez ARM64 ;
- Exécutez l’installateur téléchargé et suivez les indications.
Si vous ne connaissez pas l’architecture, consultez « Type du système » dans Paramètres → Système → Informations système.
Démarrez Cherry Studio après installation. Si des paramètres d’initialisation, de répertoire de données ou de mise à jour apparaissent, suivez l’interface actuelle.
Ajouter le fournisseur AGTCloud
Ouvrir les paramètres des fournisseurs
Dans Cherry Studio, ouvrez Settings → Model Provider. Dans l’interface chinoise, l’entrée correspond à « Paramètres → Service de modèles ».
Ajouter un fournisseur personnalisé
Cliquez sur Add ou le bouton d’ajout dans la liste et créez un fournisseur personnalisé. Définissez Provider Name sur AGTCloud et Provider Type sur OpenAI.
Renseigner la connexion
| Champ Cherry Studio | Valeur |
|---|---|
Provider Name | AGTCloud |
Provider Type | OpenAI |
Chat Endpoint / Protocol (si présent) | OpenAI Chat Completions |
API Key | your-api-key |
API Host | https://api.agtcloud.cn/v1/ |
Custom Headers | Laisser vide par défaut |
Remplacez your-api-key par l’API Key AGTCloud créée dans API Keys. Si un choix de protocole de conversation est proposé, utilisez OpenAI Chat Completions.
Activer le fournisseur
Après enregistrement, activez l’interrupteur en haut à droite du fournisseur. S’il est désactivé, ses modèles ajoutés ne figurent pas dans la liste de conversation.
API Host doit se terminer par /
Saisissez https://api.agtcloud.cn/v1/. Ne renseignez pas l’adresse complète /v1/chat/completions : Cherry Studio pourrait ajouter le chemin une seconde fois.
Récupérer et ajouter des modèles
Ouvrir la gestion des modèles
Cliquez sur Manage dans la configuration AGTCloud. Cherry Studio tente de récupérer les modèles accessibles avec l’API Host et l’API Key actuels.
Ajouter un modèle à la liste
Trouvez un modèle compatible Chat Completions et cliquez sur + à droite. Seuls les modèles ajoutés à la liste du fournisseur apparaissent dans le sélecteur de conversation.
Ajouter manuellement si la liste ne se charge pas
Vérifiez d’abord API Host, API Key et l’activation du fournisseur. Vous pouvez aussi copier l’ID dans le catalogue de modèles et saisir MODEL_ID via l’ajout manuel de votre version.
Vérifier la connexion
Cliquez sur le bouton de connectivité près de l’API Key. Cherry Studio utilise généralement le dernier modèle de conversation ajouté. En cas d’échec, vérifiez la présence d’au moins un modèle que votre clé peut appeler.
Configurez les modèles selon leurs capacités réelles
Il n’est pas nécessaire d’ajouter tous les modèles. Le contexte, les fichiers, la compréhension d’images, les outils et le raisonnement dépendent du modèle et du protocole effectivement utilisés.
Commencer une première conversation
Créer un sujet
Revenez à la conversation et créez un sujet.
Sélectionner un modèle AGTCloud
Dans le sélecteur, choisissez AGTCloud → MODEL_ID. MODEL_ID est fictif : l’interface affiche l’ID que vous avez ajouté.
Vérifier le résultat
Une réponse reçue normalement confirme la connexion de base de l’API Host, de l’API Key et du modèle. Cette étape entraîne une consommation API normale.
Questions fréquentes
| Symptôme | Vérifier en priorité | Solution |
|---|---|---|
| Modèle AGTCloud absent | Activation et ajout du modèle | Activez le fournisseur et vérifiez que le modèle figure dans sa liste |
Liste Manage vide | API Host, API Key et modèles accessibles | Renseignez de nouveau les paramètres ou copiez MODEL_ID dans le catalogue pour un ajout manuel |
| Échec du test de connectivité | Modèles ajoutés, protocole et autorisations | Vérifiez que le dernier modèle de conversation est accessible à la clé via Chat Completions |
Réponse 401 | API Key et état du Token | Copiez une clé valide, sans espaces superflus |
Réponse 403 | Autorisations et état du compte | Vérifiez la clé et les modèles accessibles dans la console |
Réponse 404 | API Host, chemins dupliqués et ID du modèle | Utilisez https://api.agtcloud.cn/v1/, pas un Endpoint complet, et revérifiez l’ID |
| Chemin de requête dupliqué | Endpoint complet saisi dans API Host | Rétablissez https://api.agtcloud.cn/v1/ avec le / final et vérifiez de nouveau la connexion |
| Échec des fonctions avancées | Capacités, protocole et version | Désactivez d’abord les fichiers, outils, base de connaissances ou raisonnement, puis validez en texte ordinaire |
| Réponse lente ou interrompue | Proxy, longueur du contexte et état du modèle | Réessayez avec un nouveau sujet plus court et vérifiez le réseau ainsi que l’état du modèle |
En cas de problème non identifié, consignez l’heure, l’ID du modèle, le code HTTP et l’erreur expurgée, puis consultez Erreurs et dépannage. Ne fournissez pas d’API Key complète.
Conseils de sécurité
- N’inscrivez pas l’API Key dans les captures d’écran, exports de conversation, journaux ou configurations partagées ;
- Ne transmettez pas de mots de passe, données clients, fichiers privés ou autres contenus sensibles lors du premier test ;
- Sur un appareil partagé, supprimez les identifiants conservés dans Cherry Studio après utilisation ;
- Avant d’exporter ou partager une configuration, vérifiez l’absence d’API Key.