LobeChat réunit plusieurs fournisseurs de modèles dans une même interface, ce qui est pratique, mais la gestion des clés est souvent négligée : qui les a créées, quels modèles elles peuvent appeler, si elles sont stockées dans le navigateur ou en base, si une sauvegarde les emporte, et si elles restent valides après le départ d'un membre. Cet article suit l'ordre création, configuration, stockage, rotation, politique d'équipe et diagnostic, avec des pratiques directement applicables.

Remarque : LobeChat et LobeHub sont des produits et marques de leurs détenteurs respectifs ; OpenAI est une marque d'OpenAI, Inc. Cet article est purement technique et n'implique aucune affiliation ni partenariat avec ces sociétés. L'interface, les noms de variables et les modes de stockage évoluent selon les versions : la documentation officielle actuelle fait foi ; les modèles et les prix sont indiqués sur la page Tarifs des modèles.

1. Distinguer d'abord trois types de clés

L'expression « clé API LobeChat » désigne souvent trois choses différentes :

  • Identifiant de compte ou de plateforme : utilisé pour se connecter à LobeHub Cloud ou à une plateforme entreprise, avec des droits définis par la plateforme.
  • Clé de fournisseur de modèles : émise par OpenAI, Anthropic, Google, etc., et saisie dans le fournisseur correspondant.
  • Clé de passerelle : émise par une passerelle compatible OpenAI, une seule clé donnant accès à plusieurs modèles.

Cet article traite du troisième cas, également valable pour d'autres clés de fournisseurs saisies dans LobeChat. Une clé de passerelle ne sert pas à se connecter et ne permet pas d'appeler les interfaces privées d'un éditeur ; lors de la configuration, choisissez une entrée compatible OpenAI ou un fournisseur personnalisé, plutôt que de saisir la clé dans un champ propriétaire.

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. En inversant l'ordre, vous vous épargnez beaucoup d'ennuis :

  1. Ouvrez la page d'inscription à la passerelle IA ZSQH, créez un compte et connectez-vous à la console.
  2. Accédez à la page des clés API et créez une nouvelle clé.
  3. Indiquez clairement l'utilisateur, l'environnement et l'usage, par exemple lobe-team-prod, et évitez test.
  4. Fixez un plafond de dépense et une date d'expiration ; si le périmètre de modèles est pris en charge, limitez les modèles accessibles par projet.
  5. Vérifiez le solde du compte pour ne pas découvrir après configuration que les appels échouent.
  6. Copiez la clé dans un gestionnaire de mots de passe, sans la coller d'abord dans une discussion, un document ou un ticket.

Une fois la clé créée, vérifiez en ligne de commande que la clé, l'adresse et le modèle fonctionnent ensemble :

export ZSQH_API_KEY="sk-votre-cle"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"votre-modele","messages":[{"role":"user","content":"Reponds seulement OK"}]}'

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

3. Variables d'environnement serveur et configuration utilisateur

Les clés LobeChat peuvent se situer à deux niveaux, aux effets très différents :

Niveau Emplacement Portée Adaptation
Variables d'environnement serveur Environnement de déploiement, lobehub.env, gestion des secrets Partagées par toute l'instance Entrée unifiée d'équipe, modèle par défaut
Configuration fournisseur utilisateur Interface de réglages après connexion Un seul compte Clé personnelle, essai temporaire
Clé côté passerelle Console de la passerelle Mesurée par clé Quotas, audit, révocation

La variable serveur OPENAI_API_KEY est une clé partagée : toute personne ayant accès à l'instance peut l'utiliser. Un utilisateur peut aussi saisir sa propre clé dans les réglages ; en mode base de données serveur, les clés utilisateur sont chiffrées avant écriture dans la base, le chiffrement dépendant de KEY_VAULTS_SECRET. Si cette variable est perdue, les clés utilisateur déjà stockées peuvent devenir indéchiffrables : sauvegardez-la dès le déploiement.

Les variables serveur courantes comprennent :

  • OPENAI_API_KEY : clé de passerelle partagée.
  • OPENAI_PROXY_URL : remplace l'adresse OpenAI par défaut et pointe vers une passerelle compatible.
  • OPENAI_MODEL_LIST : contrôle la liste des modèles, sans accorder de droits supplémentaires.
  • KEY_VAULTS_SECRET : chiffre les clés utilisateur et les adresses de proxy stockées en base.
  • AUTH_SECRET : lié aux sessions et à l'authentification, à générer séparément.
  • DATABASE_URL : chaîne de connexion PostgreSQL, indispensable en mode serveur.

Ne placez pas la même clé à la fois dans les variables d'environnement et dans la configuration utilisateur, sauf si vous savez quel niveau s'applique. Pour diagnostiquer, identifiez d'abord quelle clé la requête utilise, puis consultez les journaux de la passerelle.

4. Configurer plusieurs modèles et plusieurs fournisseurs

La syntaxe de OPENAI_MODEL_LIST est la suivante : + ajoute, - masque, ID=modele<capacites> personnalise l'affichage et les capacités, les entrées étant séparées par des virgules. Exemple :

-all,+model-a=Questions quotidiennes<128000:fc:vision>,+model-b=Analyse de documents longs<200000:reasoning>

Le premier élément entre chevrons est la taille maximale de contexte, suivie des étiquettes de capacité : fc (appel de fonctions), vision (vision), file (fichiers), reasoning (raisonnement), search (recherche web). Renseignez les étiquettes selon les capacités réelles du modèle : une erreur ne provoque pas d'échec immédiat, mais se manifestera dans les tâches de plugin ou d'image.

Le principe pour plusieurs fournisseurs est « une configuration par point de terminaison amont » :

  • Un seul fournisseur par passerelle, en distinguant les usages par la liste de modèles.
  • Un fournisseur par passerelle ou par environnement, avec un suffixe d'environnement dans le nom.
  • Une clé indépendante par entrée, pour faciliter quotas et révocations séparés.
  • Ne dupliquez pas la même clé pour afficher plus de modèles : la comptabilité deviendrait illisible.

La liste de modèles ne détermine que l'affichage ; les droits réels sont côté passerelle. Pour limiter les modèles qu'une clé peut appeler, configurez-le dans la console plutôt que de compter sur le masquage côté interface.

5. Où sont stockées les clés et par où elles fuient

Selon le mode de déploiement :

  • Mode local ou navigateur : la configuration est conservée dans le stockage local du navigateur et peut disparaître après un changement d'appareil ou un nettoyage du cache. N'enregistrez pas de clé durable sur un ordinateur partagé.
  • Mode base de données serveur : les clés utilisateur sont chiffrées puis écrites dans PostgreSQL, le chiffrement dépendant de KEY_VAULTS_SECRET. Les sauvegardes contiennent du chiffré, mais le fichier de secret doit être conservé séparément.
  • Fichier de variables d'environnement : lobehub.env est en clair ; limitez la lecture au compte de service, ne le versionnez pas dans Git et ne le distribuez pas avec l'image.
  • S3 et sauvegardes : S3 stocke les fichiers et les connaissances, généralement sans clés ; les sauvegardes de base et la configuration de déploiement peuvent toutefois contenir des informations sensibles indirectement.

Attention aussi aux captures d'écran, aux tickets et aux historiques de discussion. Beaucoup de fuites ne viennent pas d'une intrusion dans la base, mais d'une clé collée au mauvais endroit.

6. Rotation et révocation

Renouvelez les clés tous les 90 jours, ou immédiatement en cas de départ d'un membre, de perte d'appareil ou de suspicion de fuite. L'ordre est « créer la nouvelle, basculer, puis désactiver l'ancienne » :

  1. Créez une nouvelle clé aux mêmes droits, avec un suffixe de date dans le nom.
  2. Mettez à jour lobehub.env ou la configuration fournisseur utilisateur, entrée par entrée.
  3. Redémarrez ou reconstruisez le service, puis envoyez une requête de test.
  4. Vérifiez dans les journaux de la passerelle que la nouvelle clé est utilisée et que l'ancienne ne reçoit plus de trafic.
  5. Observez quelque temps le taux d'erreur et l'usage, pour détecter un script ou un appareil oublié.
  6. Désactivez l'ancienne clé, conservez les enregistrements un certain temps, puis supprimez-la.

Ne supprimez pas l'ancienne clé avant d'avoir configuré la nouvelle : cela créerait une fenêtre d'indisponibilité. En cas de fuite suspectée, désactivez d'abord pour limiter les dégâts, puis examinez l'usage anormal et l'origine des appels.

7. Politique d'équipe : une clé par personne, des environnements séparés

  • Une clé par personne, une clé par usage ; créez des clés distinctes pour les tâches automatisées.
  • Développement, test et production utilisent des clés indépendantes, pour éviter que le trafic de test pollue la comptabilité de production.
  • Activez systématiquement les plafonds, les dates d'expiration et, si possible, le périmètre de modèles ; au minimum les deux premiers.
  • La clé serveur partagée ne sert qu'à l'entrée par défaut, avec un plafond prudent, pour que les anomalies soient visibles.
  • Tenez un registre : nom de clé, titulaire, usage, date de création et d'expiration, jamais la clé complète.
  • Vérifiez chaque mois les clés inutilisées, celles qui dépassent les quotas et les échecs d'authentification anormaux.
  • 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 être envoyées aux modèles cloud ; évaluez les projets sensibles avant usage.
  • Revoyez régulièrement la page Tarifs des modèles : les prix et les modèles disponibles évoluent.

Même dans une petite équipe, conservez la trace de « qui demande, qui utilise, quand la clé expire ». Cela permet de réagir vite en cas d'incident.

8. Diagnostic

Symptôme Cause courante Traitement
401 Clé erronée, désactivée ou contenant un espace Recopiez-la et vérifiez qu'elle appartient à la bonne passerelle
403 Forbidden Quota épuisé, droits insuffisants ou périmètre de modèles restreint Vérifiez quota et droits dans la console
404 Not Found Chemin d'API incorrect Ne conservez que /v1
429 Too Many Requests Limitation de débit ou plafond atteint Vérifiez l'usage et les réglages de concurrence
model not found Identifiant erroné ou modèle non activé Copiez l'identifiant exact depuis la page des tarifs
Clé utilisateur soudainement invalide KEY_VAULTS_SECRET modifié ou absent Restaurez le secret d'origine et saisissez à nouveau la clé
curl fonctionne, l'interface échoue Configuration non enregistrée, cache navigateur ou proxy Enregistrez à nouveau et vérifiez le proxy

Pour diagnostiquer, distinguez d'abord « l'application ne lit pas la configuration » de « la passerelle rejette la requête » : dans le premier cas, examinez variables, base et journaux ; dans le second, le code HTTP.

Questions fréquentes

La clé API LobeChat est-elle stockée dans le navigateur ou sur le serveur ?

Cela dépend du déploiement. En mode navigateur ou local, elle est conservée dans le stockage local ; en mode base de données serveur, les clés utilisateur sont chiffrées dans PostgreSQL, tandis que la clé partagée des variables d'environnement reste en clair dans l'environnement de déploiement.

Si OPENAI_API_KEY est configurée côté serveur, l'utilisateur doit-il encore saisir une clé ?

Non. La clé serveur est partagée et directement utilisable par les membres de l'instance. Un utilisateur peut aussi saisir sa propre clé pour un quota indépendant ou un autre fournisseur ; la priorité dépend de la version actuelle.

Une clé peut-elle appeler plusieurs modèles ?

Généralement oui, si la passerelle accorde ce droit à la clé pour ces modèles. La liste de modèles ne contrôle que l'affichage ; les droits et quotas réels se règlent dans la console de la passerelle.

Quel est l'effet d'une modification de KEY_VAULTS_SECRET ?

Les clés utilisateur et adresses de proxy déjà chiffrées peuvent devenir indéchiffrables, ce qui se traduit par une invalidation soudaine. Sauvegardez avant toute modification et consultez les notes de migration de la version concernée ; ne la changez pas sans nécessité.

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, l'origine et la période des appels. Vérifiez ensuite le fichier de variables, les sauvegardes de base, le dépôt, les discussions et les captures d'écran, et renouvelez si besoin les autres identifiants du même environnement.

En résumé

Configurer les clés LobeChat n'est pas compliqué ; la difficulté est la gestion dans la durée : des noms traçables, des quotas plafonnés, un stockage protégé, des sauvegardes bien délimitées et une fuite que l'on sait contenir. Vous pouvez commencer par créer un compte sur la passerelle IA ZSQH et générer une clé dédiée au client, puis resserrer la politique d'équipe une fois le fonctionnement validé, en revoyant régulièrement les coûts sur la page Tarifs des modèles.

Pour aller plus loin :