Fournisseurs d’IA russes pour OpenCode

OpenCode est un agent de programmation ouvert qui fonctionne directement dans le terminal : lit les fichiers du projet, édite le code, exécute des commandes et des tests, recherche dans le référentiel et fonctionne avec git. Sa force réside dans le fait qu’il n’est pas lié à un seul fournisseur modèle et qu’il peut connecter des dizaines de fournisseurs.

GigaChat est un grand modèle de langage de Sber. Il ne figure pas dans la liste prête des fournisseurs OpenCode, mais ce n’est pas un problème : OpenCode connecte des fournisseurs arbitraires via les packages Vercel AI SDK. Pour GigaChat, il existe un package gigachat-ai-sdk-provider, qui s’occupe de l’autorisation OAuth et de la mise à jour du jeton d’accès. Une nuance distincte concerne les certificats du ministère du Développement numérique : sans eux, Node ne fait pas confiance aux serveurs GigaChat et les demandes échouent avec une erreur de vérification du certificat.

Dans cet article, je vais décrire comment obtenir une clé, installer des certificats et connecter GigaChat à OpenCode.

Ce dont vous avez besoin

Pour travailler, vous avez besoin de trois choses :

• OpenCode installé. Si l’agent n’est pas encore installé, j’ai discuté de la procédure d’installation dans une note séparée sur OpenCode et DeepSeek.
• Compte GigaChat. Inscription dans GigaChat Studio et clé d’autorisation : vous aurez besoin de l’identifiant Sber pour vous connecter.
• Terminal moderne. WezTerm, Alacritty, Ghostty, Kitty ou tout autre feront l’affaire.

Clé d’autorisation GigaChat

La clé est créée dans votre compte personnel GigaChat Studio. Accédez à Developers.sber.ru/studio, connectez-vous et créez un projet dans la section API GigaChat. Dans les paramètres du projet, il y a un bloc avec les données d’autorisation : la ligne qui est copiée à partir de là est une clé d’autorisation prête à l’emploi en base64. C’est celle-ci qui est substituée dans la variable d’environnement, et non la paire client-secret séparément.

Avec la clé, la portée est spécifiée – la zone d’accès :

• GIGACHAT_API_PERS – pour les particuliers.
• GIGACHAT_API_B2B – pour les entrepreneurs individuels et les personnes morales.
• GIGACHAT_API_CORP – accès d’entreprise.

La valeur de clé affichée doit être enregistrée immédiatement : elle ne sera plus affichée plus tard, et si nécessaire, une nouvelle devra être émise.

Il est important de comprendre quelle est cette ligne. La clé d’autorisation n’est pas un secret distinct, mais une paire de client_id:client_secret déjà encodé en base64. La bibliothèque gigachat-js remplace cet en-tête dans la requête OAuth :

Authorization: Basic ваш_ключ_авторизации

En réponse, un jeton d’accès JWE a une durée de vie d’environ une demi-heure, puis la bibliothèque le met à jour automatiquement. Le package lui-même vérifie que la valeur est similaire à base64 et avertit si la variable contient accidentellement un secret client « brut ». Par conséquent, il est nécessaire de transférer la chaîne base64 prête à l’emploi du compte vers la variable de configuration et d’environnement, et non la paire client_id et client_secret séparément.

Certificats du Ministère du Développement Numérique

L’API GigaChat utilise des certificats du ministère du Développement numérique de la NCA. Le magasin de racines de confiance standard ne les a pas, donc lorsque vous essayez d’obtenir un jeton d’accès, la demande échoue avec une erreur telle que :

self-signed certificate in certificate chain

Les certificats peuvent être installés au niveau du système d’exploitation – ils seront alors approuvés par le navigateur et les utilitaires système. Mais OpenCode fonctionne sur Node et Bun, il est donc plus sûr et plus facile de spécifier le fichier de certificat directement dans la variable NODE_EXTRA_CA_CERTS. Téléchargez les certificats racine et émetteur et placez-les dans un seul fichier PEM :

curl -s https://gu-st.ru/content/lending/russian_trusted_root_ca_pem.crt -o russian_trusted_root_ca_pem.crt
curl -s https://gu-st.ru/content/lending/russian_trusted_sub_ca_pem.crt -o russian_trusted_sub_ca_pem.crt
cat russian_trusted_root_ca_pem.crt russian_trusted_sub_ca_pem.crt > russian_trusted_ca_bundle.pem

Le fichier peut être placé dans un emplacement pratique et son chemin complet peut être spécifié lors du démarrage de l’agent.

Il y a un piège ici. Les fichiers téléchargés utilisent des sauts de ligne CRLF et le certificat racine n’a pas de saut de ligne de fin. Par conséquent, un chat ordinaire concatène la fin du premier certificat et le début du second en une seule ligne :

-----END CERTIFICATE----------BEGIN CERTIFICATE-----

LibreSSL – et le système openssl sur macOS, je vous le rappelle, est exactement LibreSSL – n’accepte pas un tel fichier et répond par une erreur :

PEM routines:CRYPTO_internal:bad end line

Cela signifie que le chat seul ne suffit pas. Chaque certificat doit d’abord être exécuté via openssl : il le recodera en PEM canonique avec des sauts de ligne LF et un saut de ligne final, puis fusionné :

openssl x509 -in russian_trusted_root_ca_pem.crt -out russian_trusted_root_ca.pem
openssl x509 -in russian_trusted_sub_ca_pem.crt -out russian_trusted_sub_ca.pem
cat russian_trusted_root_ca.pem russian_trusted_sub_ca.pem > russian_trusted_ca_bundle.pem

Vous pouvez vérifier que le fichier est lu comme ceci :

openssl x509 -in russian_trusted_ca_bundle.pem -noout -subject

Si les certificats proviennent d’une autre source et sont au format DER ou PKCS#7, ils peuvent également être recodés en PEM :

openssl x509 -in cert.crt -inform DER -outform PEM -out cert.pem
openssl pkcs7 -print_certs -in bundle.p7b -out cert.pem

Connectez-vous à OpenCode

Le fournisseur est décrit dans le fichier de configuration opencode.jsonc. OpenCode lui-même téléchargera et connectera le package npm spécifié dans le champ npm, y trouvera l’usine createGigaChat et lui transmettra les options. Il suffit de lister les modèles par leurs identifiants depuis l’API.

Le fichier peut être placé à deux endroits :

• Global – ~/.config/opencode/opencode.jsonc. Les paramètres s’appliquent à tous les projets utilisateur.
• Dans le projet – opencode.jsonc à la racine du projet. Cette configuration a une priorité plus élevée et peut être validée en toute sécurité sur git.

Les deux fichiers utilisent le même schéma et sont combinés : le fichier de projet chevauche le fichier global uniquement avec les clés correspondantes, les paramètres restants sont enregistrés. L’extension .jsonc est également prise en charge. Si GigaChat n’est nécessaire que pour certains référentiels, il est plus pratique de conserver le fournisseur dans la configuration du projet plutôt que dans la configuration globale.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "gigachat": {
      "npm": "gigachat-ai-sdk-provider",
      "name": "GigaChat",
      "models": {
        "GigaChat-2-Max": { "name": "GigaChat 2 Max" },
        "GigaChat-2-Pro": { "name": "GigaChat 2 Pro" },
        "GigaChat-2": { "name": "GigaChat 2 Lite" },
        "GigaChat": { "name": "GigaChat" }
      }
    }
  }
}

Les modèles disponibles avec une clé personnelle sont répertoriés ici. Si vous avez un projet pour un entrepreneur individuel ou une personne morale ayant accès à GigaChat 3, ajoutez les identifiants nécessaires de la méthode modèles au bloc modèles.

Il est plus pratique de ne pas stocker la clé elle-même dans un fichier, mais de la transmettre à une variable d’environnement : le package gigachat-js la lit automatiquement. La valeur de portée peut également être définie sur une variable. Il ne reste plus qu’à définir le chemin d’accès aux certificats et à lancer l’agent :

export GIGACHAT_CREDENTIALS=ваш_ключ_авторизации
export GIGACHAT_SCOPE=GIGACHAT_API_PERS
export NODE_EXTRA_CA_CERTS=/путь/к/russian_trusted_ca_bundle.pem
opencode

Cette option est également intéressante car le secret ne se retrouve pas dans le stockage local auth.json : il vit uniquement dans l’environnement du processus. Ceci est plus pratique pour les lancements CI et ponctuels.

Modèles

L’ensemble des modèles disponibles dépend de la clé de portée. La clé personnelle (GIGACHAT_API_PERS) est disponible pour la famille GigaChat et GigaChat 2 :

• GigaChat – modèle de base.
• GigaChat-2 : un modèle rapide et léger pour les tâches quotidiennes, affiché en version Lite dans l’interface.
• GigaChat-2-Pro : un modèle amélioré pour les tâches gourmandes en ressources.
• GigaChat-2-Max est le plus puissant disponible en utilisant une clé personnelle.

La famille GigaChat 3 (GigaChat-3-Ultra, GigaChat-3-Pro, modèles ouverts comme GigaChat3.5-432B-A28B-Reasoning) est visible dans le catalogue de la console, mais elle n’est pas disponible à la clé personnelle : elle nécessite un projet d’entrepreneur individuel ou une personne morale de portée GIGACHAT_API_B2B ou GIGACHAT_API_CORP et un tarif adapté. Sur une clé personnelle, un tel modèle répond par une erreur :

{"status":404,"message":"No such model"}

Vous pouvez vérifier ce que votre clé génère réellement en interrogeant la liste des modèles :

curl -H "Authorization: Bearer <токен_доступа>" https://gigachat.devices.sberbank.ru/api/v1/models

Encore deux points. Les ID de modèle dans l’API ne correspondent pas aux noms affichés : le modèle léger est appelé GigaChat-2 et non GigaChat-2-Lite. Et le catalogue dans la console ne montre pas la même chose que ce qui est disponible sur votre clé, vous devez donc vous concentrer sur la réponse de la méthode des modèles, et non sur la liste avec les prix.

Dans l’interface, la liste des modèles s’ouvre avec la commande :

/models

Pour le travail de routine dans le référentiel – navigation dans les fichiers, modifications mineures, exécution de tests – GigaChat-2 est largement suffisant. Pour les tâches et la conception complexes, il est logique de passer à Pro ou Max.

Premier lancement dans le projet

Accédez au répertoire du projet et lancez l’agent :

cd ваш_проект
opencode

La première étape consiste à initialiser l’agent :

/init

OpenCode analysera la structure du projet et créera un fichier AGENTS.md – instructions pour l’agent. Ce fichier vaut la peine d’être engagé dans git : il aide l’agent à comprendre les conventions et les modèles adoptés dans le projet.

Alternative : proxy local

Si, pour une raison quelconque, vous ne souhaitez pas utiliser le fournisseur npm, un proxy local donne le même résultat. L’équipe GigaChat dispose d’un service officiel gpt2giga – FastAPI qui traduit les requêtes au format OpenAI, Anthropic et Gemini dans l’API GigaChat et met à jour le jeton d’accès lui-même. Il est généré localement sur le port 8090, après quoi un fournisseur compatible OpenAI standard est configuré dans OpenCode via le package @ai-sdk/openai-compatible avec l’adresse de base http://localhost:8090/v1. L’inconvénient de cette voie est que vous devez également conserver un service Python en cours d’exécution à côté d’OpenCode.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "gigachat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "GigaChat (proxy)",
      "options": {
        "baseURL": "http://localhost:8090/v1"
      },
      "models": {
        "GigaChat-2-Max": { "name": "GigaChat 2 Max" }
      }
    }
  }
}

DeepSeek et autres modèles via Cloud.ru

L’API GigaChat elle-même n’a pas de modèles DeepSeek : il existe uniquement la famille GigaChat et des modèles pour les intégrations. Si vous avez besoin de DeepSeek dans OpenCode, mais via une passerelle cloud russe, le service Foundation Models de Cloud.ru convient. Il fournit des modèles utilisant le protocole compatible OpenAI, il est donc connecté à l’aide du package standard @ai-sdk/openai-compatible.

Dans le catalogue Cloud.ru Foundation Models, il existe, par exemple, les modèles suivants :

deepseek-ai/DeepSeek-V4.1-Flash
deepseek-ai/DeepSeek-V4-Flash
deepseek-ai/DeepSeek-V4-Pro

La clé est émise dans la console Cloud.ru : section Utilisateurs, onglet Comptes de service. Nous créons un compte de service au niveau du projet, puis dans ses informations d’identification, nous créons une clé API avec le service Foundation Models. La clé secrète est affichée une fois et nous la sauvegardons.

La configuration du fournisseur dans opencode.json ressemble à ceci :

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "cloudru": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Cloud.ru Foundation Models",
      "options": {
        "baseURL": "https://foundation-models.api.cloud.ru/v1",
        "apiKey": "{env:CLOUDRU_API_KEY}"
      },
      "models": {
        "deepseek-ai/DeepSeek-V4.1-Flash": { "name": "DeepSeek V4.1 Flash", "limit": { "context": 1048576, "output": 1048576 } },
        "deepseek-ai/DeepSeek-V4-Flash": { "name": "DeepSeek V4 Flash", "limit": { "context": 1048576, "output": 1048576 } },
        "deepseek-ai/DeepSeek-V4-Pro": { "name": "DeepSeek V4 Pro", "limit": { "context": 1048576, "output": 1048576 } }
      }
    }
  }
}

On passe la clé à la variable d’environnement :

export CLOUDRU_API_KEY=ваш_ключ_cloudru
opencode

Les certificats du ministère du Développement numérique ne sont pas nécessaires ici : le domaine api.cloud.ru a un TLS régulier, contrairement à GigaChat. Mais cela vaut la peine de surveiller le reste du projet. Si le compte est nul, l’autorisation est acceptée et les demandes sont abandonnées avec la réponse de facturation :

{"message":"Not enough money"}

Ce n’est pas une erreur de configuration, mais un signal indiquant que vous devez mettre à jour le projet dans la console Cloud.ru.

À quoi faire attention

Quelques points pratiques qui gênent le plus souvent lors de la première mise en place :

• Erreur de vérification du certificat. Le message concernant le certificat auto-signé dans la chaîne signifie que la variable NODE_EXTRA_CA_CERTS n’a pas été récupérée. Vérifiez le chemin d’accès au fichier, que l’agent s’exécute dans le même environnement, ainsi que le fichier lui-même : si, lors de la fusion de deux certificats à l’aide de cat, leurs extrémités se retrouvent sur la même ligne, LibreSSL renverra une mauvaise ligne de fin et le bundle devra être reconstruit via openssl, comme dans la section sur les certificats.
• Erreur 401. En règle générale, il s’agit d’une clé d’autorisation incorrecte ou d’un champ d’application incompatible : pour un individu, vous avez besoin de GIGACHAT_API_PERS.
• Erreur 404 avec le texte Aucun modèle de ce type. Il ne s’agit pas d’un échec de connexion, mais d’un manque d’accès à un modèle spécifique. Supprimez-le de la configuration ou remplacez-le par un disponible. Dans un message tel que GigaChat 404 : Erreur inconnue, la même réponse GigaChat est à blâmer : le fournisseur n’a tout simplement pas pu analyser le corps de l’erreur.
• Coût. OpenCode ne nécessite pas d’abonnement : vous payez GigaChat directement lorsque vous dépensez des jetons, le prix des longues sessions est donc prévisible.
• Qualité du modèle. Pour les tâches architecturales complexes, les modèles de différentes classes diffèrent. Par conséquent, pour la conception, il est logique de prendre un modèle plus solide et de confier la routine à un modèle plus rapide.

Liens

https://opencode.ai/
https://opencode.ai/docs/providers/
https://developers.sber.ru/studio/
https://developers.sber.ru/docs/ru/gigachat/guides/main
https://github.com/nyddle/gigachat-ai-sdk-provider
https://github.com/ai-forever/gpt2giga
https://cloud.ru/docs/foundation-models/ug/topics/quickstart

Sources

https://opencode.ai/docs/providers/#custom-provider
https://developers.sber.ru/docs/ru/gigachat/certificates
https://developers.sber.ru/docs/ru/gigachat/models/main
https://developers.sber.ru/docs/ru/gigachat/guides/selecting-a-model
https://github.com/nyddle/gigachat-ai-sdk-provider
https://github.com/ai-forever/gpt2giga
https://cloud.ru/docs/foundation-models/ug/topics/quickstart
https://cloud.ru/docs/foundation-models/ug/topics/overview__available__models