La clé API de Roo Code détermine le fournisseur utilisé, les modèles accessibles, à qui la facture est imputée et l'ampleur des dégâts en cas de fuite. Beaucoup de « clés invalides » viennent en réalité d'une Base URL, d'un nom de modèle ou d'un type de fournisseur mal choisi.

Cet article suit l'ordre création, configuration compatible, profils multi-modèles, sécurité, rotation, règles d'équipe et dépannage. Après une migration vers la branche communautaire Zoo Code, la plupart des concepts restent valables.

Note : Roo Code est une marque de son titulaire ; VS Code est une marque de Microsoft. Cet article n'est qu'une explication technique et n'implique aucune affiliation avec les éditeurs concernés. L'extension Roo Code a cessé d'être maintenue le 15 mai 2026 et le dépôt a été archivé le même jour ; l'état ultérieur fait foi sur le dépôt et la documentation officiels. Modèles et prix font foi sur la page tarifs des modèles.

1. Vérifier d'abord la situation et le type de clé

Roo Code est un agent de programmation IA open source pour VS Code, fonctionnant en mode « apportez votre propre clé » (BYOK) : l'extension ne collecte pas les frais de modèle, les appels sont facturés par la clé du fournisseur que vous renseignez. Elle prend en charge plusieurs fournisseurs ainsi que les points d'accès compatibles OpenAI.

Un point de contexte s'impose : selon les informations publiques, l'extension Roo Code a cessé d'être maintenue le 15 mai 2026, le dépôt d'origine a été archivé et il n'y aura plus de nouvelles fonctionnalités, de corrections ni de correctifs de sécurité. Les installations existantes fonctionnent généralement encore, mais l'absence de correctifs doit être intégrée au risque sur le long terme. La branche communautaire Zoo Code poursuit le développement à partir du code d'origine, sous licence Apache-2.0.

« Clé API Roo Code » désigne généralement une clé de fournisseur, une clé compatible passerelle, ou la configuration d'adresse d'un modèle local (comme Ollama). Cet article traite du deuxième cas : elle ne sert pas à se connecter à Roo Code et ne permet pas d'appeler son service cloud.

2. Créer une clé : définir le périmètre avant de copier

Avant de créer, répondez à trois questions : pour qui, sur quel projet, et quel plafond de dépense. Ces trois éléments déterminent la vitesse de diagnostic et de limitation des pertes en cas de problème.

  1. Ouvrez la page d'inscription à la passerelle ZSQH AI, inscrivez-vous et connectez-vous à la console.
  2. Allez dans « Clés API » et cliquez sur Nouveau.
  3. Indiquez clairement l'utilisateur et l'appareil, par exemple roo-zhang-macbook, pas seulement test.
  4. Définissez un plafond de quota et une date d'expiration ; pour une clé de test, commencez bas.
  5. Si la console permet de restreindre les modèles, ne cochez que ceux réellement utilisés.
  6. Copiez la clé complète dans un gestionnaire de mots de passe ; la plupart des consoles ne l'affichent entièrement qu'une fois.

Les clés commencent souvent par sk-, mais ce préfixe ne prouve ni l'authenticité ni les droits. Attention aux espaces et retours à la ligne en début et fin lors du copier-coller : c'est une cause fréquente d'Invalid API Key.

3. Configurer un point d'accès compatible OpenAI

Le chemin est Settings → Providers ; choisissez OpenAI Compatible dans API Provider. Trois champs principaux suffisent :

  • Base URL : une adresse racine du type https://ai.zhongshangqihang.com/v1, pas la page d'accueil du site et pas /chat/completions.
  • API Key : collez la clé de passerelle créée.
  • Model : l'identifiant exact affiché sur la page des tarifs, sans deviner le suffixe.

En dépliant Model Configuration, vous pouvez aussi régler Max Output Tokens, Context Window, Image Support, Computer Use, Input Price et Output Price. Les deux derniers servent uniquement à l'estimation locale des coûts et ne modifient pas la facturation réelle ; ne surestimez pas la fenêtre de contexte, sinon les tâches longues peuvent échouer.

Roo Code s'appuie sur l'appel natif d'outils du modèle, sans repli XML. Un point d'accès compatible doit donc non seulement dialoguer, mais aussi prendre en charge le function calling au format OpenAI ; sinon, la conversation simple fonctionne mais l'agent échoue dès qu'il exécute un outil.

curl https://ai.zhongshangqihang.com/v1/chat/completions \
  -H "Authorization: Bearer $ZSQH_ROO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<ID du modèle>","messages":[{"role":"user","content":"ping"}],"max_tokens":16}'

Si curl fonctionne mais Roo Code renvoie une erreur, vérifiez si la Base URL contient un chemin en trop, si l'identifiant du modèle est identique et si le modèle prend en charge les appels d'outils.

4. API Configuration Profiles : le cœur du multi-modèle

Les API Configuration Profiles sont des ensembles de configuration sauvegardables et interchangeables. Chaque profil conserve séparément le fournisseur, la clé, le modèle, la température, le budget de raisonnement, la limitation de débit et les réglages de diff. C'est la fonction à maîtriser en priorité pour un flux multi-modèles.

Dans Settings → Providers, cliquez sur le + à côté du sélecteur de profil, nommez-le, choisissez le fournisseur, saisissez la clé, sélectionnez le modèle, puis réglez éventuellement la Rate Limit. La Rate Limit représente l'intervalle minimal entre deux requêtes de ce profil ; elle est désactivée par défaut. Un profil se change dans le panneau de réglages ou dans la liste API Configuration de l'interface de chat.

Le contrôle plus fin se trouve dans l'onglet Prompts : chaque mode peut être associé à un profil. Une tâche verrouille le profil en vigueur à son démarrage, y compris lors d'une reprise depuis l'historique ; les sous-tâches de l'Orchestrator héritent du profil parent et le conservent pendant tout leur cycle de vie. Ne liez donc pas l'Orchestrator à un modèle coûteux en espérant que les sous-tâches soient dégradées.

Nom du profil Usage Niveau de modèle Stratégie de clé Remarque
plan-strong Architecture, refactorisation complexe Modèle de raisonnement fort Clé dédiée, quota élevé Lié à Architect
code-daily Codage quotidien, corrections Modèle principal Une clé par personne Lié à Code
ask-cheap Questions et explications de code Modèle léger Clé à faible quota Lié à Ask
batch-cheap Commentaires et formatage en lot Modèle économique Clé dédiée au projet Débit limité
backup Bascule en cas de panne Modèle de secours Clé dédiée Vérification régulière

Nommez les profils sous la forme « scénario-niveau » pour faciliter les vérifications. Les identifiants et les prix évoluent : référez-vous à tarifs des modèles.

5. Sécurité des clés : stockage, droits et frontière des données

Selon la documentation, la clé est stockée dans le Secret Storage de VS Code et n'est pas écrite en clair dans les fichiers de réglages ordinaires. Cela ne signifie pas une sécurité absolue : la protection dépend du compte système, et quiconque peut ouvrir votre session ou un processus disposant de vos droits peut y accéder.

Il faut donc aussi : utiliser un compte système dédié sur la machine de développement et ne pas conserver de clé durable sur un ordinateur partagé ; définir une liste blanche d'extensions sur les appareils de l'entreprise ; vérifier la portée de la synchronisation des réglages pour ne pas envoyer de configuration sensible vers des appareils non contrôlés ; ne jamais coller de clé dans un prompt, un commentaire de code ou l'historique du terminal ; masquer les champs secrets avant une capture d'écran ; choisir le canal selon le niveau de sensibilité des données, car le contexte de code est envoyé au service indiqué par la Base URL.

Le moindre privilège vise un objectif : « même en cas de fuite, la perte a une limite ». Définissez quota, expiration et liste blanche de modèles ; activez aussi la liste blanche d'IP ou le périmètre projet si la passerelle le permet. Séparez les clés de test, d'usage quotidien et d'automatisation : n'utilisez pas une seule clé pour tous les scénarios.

6. Rotation, révocation et gestion d'incident

Une rotation tous les 90 jours est recommandée, ou immédiatement en cas de départ d'un membre, de perte d'appareil ou de suspicion de fuite. Roo Code n'étant plus maintenu, les anciennes versions ne reçoivent plus de correctifs de sécurité : soyez plus prudent sur la périodicité.

L'ordre sûr est « parallèle, puis bascule, puis désactivation » : créez une nouvelle clé avec un suffixe de date ; enregistrez-la dans le gestionnaire de mots de passe en conservant provisoirement l'ancienne ; remplacez-la dans le profil et testez ; vérifiez que les journaux de la passerelle enregistrent bien la nouvelle clé ; observez le taux d'erreur un ou deux jours ; désactivez enfin l'ancienne clé.

En cas de fuite confirmée, inversez l'ordre : désactivez ou supprimez d'abord la clé, puis recherchez les usages anormaux, leur origine et leur période, avant de vérifier l'historique du dépôt, les journaux et les conversations. Limitez d'abord les pertes, ne commencez pas par reconstituer le chemin de la fuite.

7. Usage en équipe : transformer les réglages personnels en règles

Les clés Roo Code résident sur chaque machine de développement ; si l'équipe ne s'appuie que sur l'extension, il est difficile de voir centralement qui utilise quelle clé. Le contrôle centralisé doit se faire côté passerelle : une clé par personne, des clés par projet, des quotas unifiés et des journaux de requêtes conservés.

  • Clé nominative : le nom contient le membre et l'usage ; désactivation le jour du départ ; pas de « clé d'équipe » partagée.
  • Isolation par projet : production, expérimentation et automatisation utilisent des clés distinctes, avec des quotas séparés.
  • Espace de travail sans secret : le dépôt ne contient que la Base URL, le nom du modèle et la description des modes ; la clé reste dans le stockage utilisateur.
  • Comptes séparés pour les services partagés : CI, scripts et bots utilisent des clés de service, jamais celles des membres.
  • Audit mensuel : recherchez les clés inutilisées depuis longtemps, les quotas anormaux et les pics d'échecs d'authentification.
  • Moindre privilège : pas de modèle fort pour les usages légers, pas d'exécution automatique du terminal pour les tâches en lecture seule.

L'approbation automatique améliore l'efficacité mais amplifie les erreurs et la consommation de tokens ; l'équipe doit définir quelles commandes exigent une confirmation humaine.

8. Dépannage courant

  • Invalid API Key : clé incomplète, espace parasite, ou clé saisie dans un fournisseur dédié Anthropic ou Gemini. Passez à OpenAI Compatible et réessayez.
  • Model Not Found / 404 : identifiant mal orthographié ou Base URL contenant /chat/completions en trop. Copiez l'identifiant depuis la page des tarifs et gardez la Base URL jusqu'à /v1.
  • 401 / 403 : clé désactivée, quota épuisé ou aucun droit sur le modèle. Vérifiez d'abord l'état de la console et l'usage.
  • 429 : limitation de débit ou plafond de quota atteint. Réduisez la concurrence, vérifiez la Rate Limit et le quota de la clé.
  • Conversation normale, appel d'outil en échec : le point d'accès ou le modèle ne prend pas en charge le function calling natif. Changez de modèle ou de point d'accès.
  • Échec au milieu d'une tâche longue : Context Window surestimée ou plafond de sortie irréaliste. Renseignez les capacités réelles.

Le dépannage suit trois niveaux : vérifier le fournisseur, la Base URL et le nom du modèle ; reproduire avec curl ; vérifier si les journaux de la passerelle contiennent la requête correspondante. Si les trois concordent, le problème vient rarement de la clé.

Questions fréquentes

Roo Code fonctionne-t-il encore ?

Les extensions déjà installées fonctionnent généralement, mais l'équipe d'origine a cessé la maintenance le 15 mai 2026, le dépôt est archivé et il n'y a plus de mises à jour ni de correctifs de sécurité. Pour un nouveau projet, évaluez Zoo Code ou un autre outil encore maintenu ; si vous continuez avec l'ancienne version, limitez les droits des clés.

Où est stockée la clé ?

Selon la documentation, dans le VS Code Secret Storage, sans écriture en clair dans les fichiers de réglages ordinaires. Elle reste un identifiant local, dont la protection dépend du compte système et de la sécurité de la machine. Sur un appareil partagé, utilisez un compte distinct et évitez de synchroniser les configurations sensibles.

Une clé peut-elle servir à plusieurs profils ?

Oui, mais ce n'est pas recommandé. Des profils différents correspondent à des modèles et des quotas différents ; des clés séparées permettent d'identifier l'utilisateur et le scénario dans les journaux. Avec une seule clé, il est aussi plus difficile de cerner l'impact d'un incident.

Pourquoi la conversation fonctionne-t-elle mais pas les outils de l'agent ?

Roo Code n'utilise que les appels d'outils natifs, sans repli XML. Le point d'accès compatible doit implémenter le function calling au format OpenAI, et le modèle doit le prendre en charge. Testez d'abord un modèle compatible, puis déterminez si le problème vient du point d'accès ou du modèle.

Une équipe doit-elle partager une clé ?

Non. Une clé partagée ne permet pas de distinguer les usages et reste difficile à récupérer après un départ. Utilisez une clé par personne, des clés séparées pour la CI et les services partagés, avec des quotas et alertes gérés par la passerelle.

En résumé

Si vous utilisez encore Roo Code ou Zoo Code, créez d'abord une clé de test à faible quota, validez-la avec curl puis avec une vraie tâche d'agent, avant de la distribuer à l'équipe. Commencez par la page d'inscription ; modèles, quotas et facturation sont décrits sur la page tarifs des modèles, qui évolue avec les versions de modèles et les politiques amont.

Lecture associée :