Documentation

opencode

opencode construit ses fournisseurs sur le SDK Vercel AI ; pour le diriger vers un nouvel endpoint, il suffit d’un bloc qui indique un paquet npm et une baseURL. Le paquet indiqué détermine lequel des deux formats de protocole il utilise.

Un bloc fournisseur dans opencode.json — @ai-sdk/openai-compatible pour les complétions de chat, @ai-sdk/openai lorsque vous voulez la surface /v1/responses.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "kunavo": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kunavo",
      "options": {
        "baseURL": "https://api.kunavo.com/v1",
        "apiKey": "{env:KUNAVO_API_KEY}"
      },
      "models": {
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5",
          "limit": { "context": 200000, "output": 64000 }
        },
        "claude-haiku-4-5": { "name": "Claude Haiku 4.5" }
      }
    }
  }
}

Le champ npm sélectionne le format de protocole. @ai-sdk/openai-compatible utilise /v1/chat/completions ; @ai-sdk/openai utilise /v1/responses. Kunavo prend les deux en charge, les deux conviennent donc : utilisez le paquet Responses lorsque vous souhaitez que les éléments de raisonnement soient conservés dans la famille GPT, et le paquet Chat Completions pour tout le reste.

"apiKey": "{env:KUNAVO_API_KEY}" lit la clé dans l’environnement au chargement. opencode.json est un fichier qui finit dans les dépôts ; une clé en clair qu’il contient ne reste pas secrète.

Définissez limit.context et limit.output pour chaque modèle. opencode suit le contexte restant en fonction de ces nombres ; sans ces valeurs, un modèle est soumis à un budget par défaut qui ne lui correspond pas.

Pas encore de clé ? Créez un compte Kunavo, créez une clé (elle commence par sk-kn-) et ajoutez un crédit à partir de 10 $ — les appels sont payés sur ce solde et les appels échoués ne sont pas facturés. Le tableau de bord s’ouvre ensuite sur la configuration opencode.

Étape par étape

Créez une clé sur /app/keys et copiez-la — elle n’est affichée qu’une seule fois.
Exportez-la : export KUNAVO_API_KEY=sk-kn-...
Ajoutez le bloc de fournisseur à opencode.json — le fichier global situé dans ~/.config/opencode/opencode.json pour tous les projets, ou celui qui se trouve à la racine du projet pour ce dépôt uniquement.
Lancez opencode et choisissez le modèle dans la liste ; le fournisseur apparaît sous le name que vous lui avez attribué.
Pour ajouter un modèle ultérieurement, ajoutez une autre clé sous models — l’identifiant est celui transmis sur le protocole, tandis que name n’est qu’une étiquette.

Vérifié avec Documentation des fournisseurs d’opencode le 6 septembre 2026. Les paramètres tiers évoluent ; si le nom d’un champ ne correspond plus à ce que vous voyez ici, cette page fait autorité, pas celle-ci.

Vérifiez avant de déboguer le client

Une requête suffit à déterminer si l’échec vient de l’endpoint, de la clé ou du fichier de configuration. Si cette requête renvoie du JSON, la même URL de base et la même clé fonctionnent dans opencode.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Quel identifiant de modèle saisir dans le champ

Tous les modèles textuels sont accessibles sous forme d’identifiant de modèle — la liste à jour se trouve sur GET /v1/models, et le catalogue avec les prix sur la page des modèles. Les tarifs sont en USD par million de tokens, entrée / sortie.

Identifiant du modèle	Entrée / sortie sur Kunavo	Où cela s’intègre dans opencode
`claude-sonnet-5`	$1.40 / $7.00	le modèle de développement par défaut
`claude-opus-5`	$3.50 / $17.50	le mode plan, où tout ce qui suit dépend du plan
`claude-haiku-4-5`	$0.70 / $3.50	le travail des sous-agents et de recherche, où le nombre de requêtes est élevé
`gpt-5-6-sol`	$2.00 / $12.00	utilisez-le avec @ai-sdk/openai pour préserver les éléments de raisonnement pendant l’aller-retour

La facturation se fait au token à partir d’un solde prépayé, sans frais mensuels — consultez la facturation. Avec un contexte répété — ce qu’envoient la plupart des éditeurs et clients de chat — la mise en cache des prompts influe davantage sur la facture que le choix du modèle.

Questions fréquentes

Comment ajouter un fournisseur personnalisé à opencode ?

Ajoutez un bloc sous « provider » dans opencode.json en indiquant un paquet npm, un nom d’affichage, options.baseURL, options.apiKey et une map models. Utilisez @ai-sdk/openai-compatible pour un endpoint qui fournit /v1/chat/completions et @ai-sdk/openai pour un endpoint qui fournit /v1/responses. Le fournisseur apparaît ensuite dans la liste des modèles d’opencode, sous le nom que vous lui avez attribué.

Comment éviter d’inscrire la clé API dans opencode.json ?

Utilisez la syntaxe d’interpolation {env:VAR_NAME} dans options.apiKey — par exemple "apiKey": "{env:KUNAVO_API_KEY}" — et exportez la variable dans votre shell. opencode la résout au chargement de la configuration ; le fichier peut donc être validé avec le projet qu’il configure sans exposer la clé.

Quelle est la différence entre @ai-sdk/openai et @ai-sdk/openai-compatible dans opencode ?

Ils sélectionnent des endpoints différents sur la même URL de base. @ai-sdk/openai-compatible appelle /chat/completions, implémenté par presque toutes les passerelles ; @ai-sdk/openai appelle /responses, la nouvelle interface OpenAI. Choisissez celui que votre endpoint fournit réellement — utiliser le mauvais paquet provoque une erreur 404 depuis une URL de base par ailleurs correcte.

Pourquoi opencode épuise-t-il son contexte plus tôt que prévu ?

Parce que l’entrée du modèle ne contient aucun bloc de limite, et opencode calcule donc son budget à partir d’une valeur par défaut au lieu de la fenêtre réelle du modèle. Ajoutez "limit": { "context": <window>, "output": <max output> } à ce modèle dans opencode.json, en utilisant les valeurs du catalogue du fournisseur ; l’indicateur de contexte et les points de compaction correspondront alors à la réalité.