OpenCode prend en charge plus de 75 fournisseurs LLM via son annuaire, mais les fournisseurs personnalisés restent essentiels. Ils permettent d’ajouter une passerelle, un runtime local, un endpoint d’inférence interne ou un modèle qui n’a pas encore été intégré à l’annuaire.

Le principe est simple : enregistrez les identifiants, ajoutez un bloc provider, redémarrez OpenCode, puis sélectionnez le modèle depuis /models.

Vous configurez Haimaker en particulier ? Sautez les étapes manuelles — exécutez npx -y @haimaker/connect --opencode et l’outil CLI écrit le bloc provider et enregistre vos identifiants automatiquement (ajoutez --project pour une configuration locale au projet). La procédure ci-dessous est la méthode générale pour tout fournisseur compatible OpenAI — Ollama, LM Studio, une passerelle interne ou tout service qui n’est pas encore dans l’annuaire. Consultez le guide de connexion pour la méthode en une seule commande.

Quand utiliser un fournisseur personnalisé

Utilisez un fournisseur personnalisé lorsque le modèle ou l’endpoint n’est pas déjà disponible dans la liste des fournisseurs intégrés à OpenCode.

Exemples typiques :

  • Haimaker — une seule clé API pour plusieurs familles de modèles via une passerelle compatible OpenAI.
  • Ollama — modèles locaux à l’adresse http://localhost:11434/v1.
  • LM Studio — modèles locaux à l’adresse http://127.0.0.1:1234/v1.
  • Passerelles internes — endpoints compatibles OpenAI hébergés par l’entreprise.
  • Nouveaux fournisseurs — tout service qui implémente l’API de chat compatible OpenAI avant que l’annuaire d’OpenCode ne soit mis à jour.

Si le fournisseur existe déjà dans OpenCode, privilégiez d’abord le fournisseur intégré. La configuration personnalisée est surtout utile lorsque vous avez besoin d’une URL de base spécifique, d’une passerelle ou d’un modèle absent de la liste par défaut.

Étape 1 : Ajouter les identifiants

La documentation actuelle d’OpenCode recommande d’utiliser opencode auth login pour les identifiants des fournisseurs. Pour un fournisseur personnalisé compatible OpenAI, choisissez Other, saisissez un identifiant de fournisseur, puis collez la clé API :

opencode auth login

Choisissez un identifiant de fournisseur court que vous réutiliserez dans la configuration. Par exemple :

haimaker
ollama
mygateway

OpenCode stocke les identifiants dans :

~/.local/share/opencode/auth.json

Vous pouvez modifier ce fichier manuellement si nécessaire, mais utiliser opencode auth login évite les erreurs de format de clé.

Étape 2 : Configurer le fournisseur

Ouvrez ou créez votre fichier de configuration OpenCode. Selon votre configuration, il peut s’agir de opencode.json dans le projet ou d’un fichier global sous ~/.config/opencode/.

Ajoutez un bloc provider avec le même identifiant de fournisseur que celui utilisé lors de l’authentification. Voici un exemple avec haimaker.ai :

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haimaker",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "z-ai/glm-4.6": {
          "name": "GLM 4.6"
        },
        "minimax/minimax-m2.5": {
          "name": "MiniMax M2.5"
        },
        "qwen/qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

À quoi correspond chaque champ :

  • npm : l’adaptateur SDK. Pour toute API compatible OpenAI, utilisez @ai-sdk/openai-compatible. OpenCode charge l’adaptateur à la demande.
  • name : le nom d’affichage dans OpenCode.
  • options.baseURL : l’URL de base de l’API du fournisseur. Elle doit se terminer par /v1 ou le préfixe de version utilisé par le fournisseur.
  • models : les modèles que vous souhaitez rendre disponibles dans OpenCode. Les clés doivent correspondre exactement à ce que l’API du fournisseur accepte dans le champ model d’une requête de complétion.

Vous pouvez ajouter autant de fournisseurs personnalisés que vous le souhaitez, chacun sous la forme d’une entrée distincte dans provider.

Étape 3 : Redémarrer et vérifier

OpenCode peut ne pas prendre en compte les changements de fournisseur tant qu’il n’a pas été redémarré. Quittez-le complètement, relancez-le, puis exécutez :

/models

Vous devriez voir le nom d’affichage du fournisseur et les modèles configurés. Sélectionnez-en un et envoyez une courte requête avant de l’utiliser sur du code réel.

Exemple complet : passerelle Haimaker

Utilisez cette configuration lorsque vous souhaitez un seul endpoint compatible OpenAI pour plusieurs familles de modèles :

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haimaker",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "anthropic/claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6"
        },
        "openai/gpt-5.4-mini": {
          "name": "GPT-5.4 Mini"
        },
        "minimax/minimax-m2.5": {
          "name": "MiniMax M2.5"
        },
        "qwen/qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

Pourquoi cette configuration fonctionne bien : OpenCode voit un seul fournisseur, tandis que Haimaker gère l’accès à plusieurs familles de modèles en amont. Votre configuration OpenCode reste ainsi plus légère et le changement de modèle est moins fastidieux.

Exemple complet : fournisseur local Ollama

Ollama expose un endpoint local compatible OpenAI à l’adresse http://localhost:11434/v1 :

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "Qwen3 Coder 30B"
        },
        "gemma4:e4b": {
          "name": "Gemma 4 E4B"
        }
      }
    }
  }
}

Récupérez les modèles avant de démarrer OpenCode :

ollama pull qwen3-coder:30b
ollama pull gemma4:e4b

Si OpenCode exige une authentification pour le fournisseur local, exécutez opencode auth login, choisissez Other, utilisez ollama comme identifiant de fournisseur et saisissez n’importe quelle clé non vide, par exemple ollama. Ollama ne valide pas les clés API locales.

Erreurs courantes et solutions

Le fournisseur n’apparaît pas dans /models

Vérifiez quatre points :

  1. L’identifiant de fournisseur issu de opencode auth login correspond à la clé du fournisseur dans la configuration.
  2. Le fichier de configuration est un JSON ou JSONC valide.
  3. Vous avez redémarré OpenCode après modification de la configuration du fournisseur.
  4. Le modèle est listé sous l’objet models du fournisseur.

L’authentification échoue à la première requête

Les identifiants de connexion sont manquants ou associés au mauvais identifiant de fournisseur. Exécutez :

opencode auth list

Puis confirmez que l’identifiant de fournisseur correspond exactement à votre configuration. N’incluez pas Bearer dans le champ de clé.

Le modèle apparaît mais les requêtes échouent

L’identifiant du modèle ne correspond probablement pas à ce que l’API en amont attend. Les fournisseurs personnalisés transmettent les identifiants de modèle sans modification. Si votre configuration indique qwen/qwen3-coder, l’API doit accepter exactement qwen/qwen3-coder.

Pour Haimaker, testez la clé et l’endpoint :

curl https://api.haimaker.ai/v1/models \
  -H "Authorization: Bearer your-haimaker-api-key"

Pour Ollama, vérifiez les modèles locaux :

ollama list

Utilisez le nom exact du modèle issu de cette sortie.

Les appels d’outils échouent avec les modèles locaux

Les modèles locaux sont plus sensibles aux limites de contexte et au formatage des appels d’outils. Commencez par un modèle reconnu pour bien gérer les tâches de codage agentique, comme Qwen3 Coder, et conservez un contexte modeste. La documentation d’OpenCode recommande également d’augmenter le paramètre num_ctx d’Ollama lorsque les appels d’outils ne fonctionnent pas.

Les fournisseurs intégrés ont cessé de fonctionner

Vous avez probablement modifié plus d’éléments de configuration que prévu. Gardez les fournisseurs personnalisés sous l’objet provider et évitez de supprimer les entrées de fournisseurs existantes. En cas de doute, effectuez la modification de configuration la plus simple possible : ajoutez un identifiant de fournisseur et un modèle, redémarrez, testez, puis ajoutez-en davantage.

La configuration recommandée

Pour la plupart des utilisateurs d’OpenCode, la configuration idéale est :

  1. Haimaker pour les modèles cloud et le routage avec une seule clé.
  2. Ollama pour le travail local et privé.
  3. Un modèle premium de secours pour le débogage complexe et les refactorisations multi-fichiers.

Vous bénéficiez ainsi de la confidentialité locale quand elle est nécessaire, de modèles cloud à faible coût pour le travail courant et d’un modèle plus puissant quand la tâche de développement est complexe et exigeante.

UTILISER HAIMAKER AVEC OPENCODE

Pour la configuration locale, consultez Utiliser Ollama avec OpenCode. Pour un classement plus complet des modèles locaux, consultez Meilleurs modèles Ollama pour les agents de codage.