Configuration du fournisseur compatible OpenAI pour OpenCode : Router les modèles d'agent de codage via Flatkey

Une configuration de fournisseur compatible OpenAI pour OpenCode est utile lorsque vous souhaitez qu'OpenCode communique avec une route de modèle qui se comporte comme l'API Chat Completions d'OpenAI, tout en permettant à votre équipe de conserver la propriété des clés, le routage des modèles et l'examen de l'utilisation dans une seule passerelle.

L'important est qu'OpenCode dispose d'un chemin documenté pour les fournisseurs personnalisés. Dans la documentation des fournisseurs OpenCode, vérifiée le 8 juillet 2026, le processus est le suivant : ajouter un identifiant avec /connect, choisir Autre pour un fournisseur qui n'est pas déjà listé, donner à ce fournisseur un ID mémorable, configurer le fournisseur dans opencode.json, puis exécuter /models pour sélectionner parmi les modèles configurés.

Flatkey correspond à ce modèle en tant que passerelle derrière le fournisseur. Vous conservez OpenCode comme agent de codage, pointez le fournisseur vers l'URL de base de l'API compatible OpenAI de Flatkey, et vérifiez que le trafic du modèle OpenCode apparaît dans les journaux d'utilisation ou de requêtes de Flatkey avant d'en faire la route par défaut.

Réponse rapide pour la configuration du fournisseur compatible OpenAI pour OpenCode

Utilisez cette forme de configuration lorsque le point de terminaison du modèle est compatible avec Chat Completions.

Ce guide sur le fournisseur compatible OpenAI pour OpenCode utilise des modèles. Validez les alias de modèle exacts et la famille de points de terminaison par rapport à votre compte Flatkey avant de router le travail de l'agent de codage en production.

Ce que requiert OpenCode

OpenCode a deux éléments d'état distincts pour un fournisseur personnalisé.

La configuration d'OpenCode peut être en JSON ou JSONC. Vous pouvez la placer globalement dans ~/.config/opencode/opencode.json, ou à la racine d'un projet en tant que opencode.json. La configuration du projet a une précédence standard plus élevée, donc utilisez un fichier de projet lorsque vous voulez qu'un dépôt teste Flatkey sans modifier chaque espace de travail OpenCode.

Étape 1 : Créer une clé Flatkey pour OpenCode

Créez une clé Flatkey pour cette charge de travail et notez trois valeurs en dehors du contrôle de code source.

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_MODEL=your-current-flatkey-model-alias

Gardez la racine de l'API séparée du chemin du point de terminaison. La configuration du fournisseur OpenCode doit utiliser https://router.flatkey.ai/v1 comme options.baseURL ; les tests de fumée HTTP directs ajoutent /chat/completions.

Avant de connecter OpenCode, effectuez un test direct avec la même clé Flatkey et le même alias de modèle.

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      { "role": "user", "content": "Reply with exactly: flatkey route ok" }
    ]
  }'

Si cette requête directe échoue, corrigez la clé Flatkey, l'alias de modèle, la famille de points de terminaison ou la route du compte avant de déboguer OpenCode. Un fournisseur compatible OpenAI pour OpenCode ne peut pas compenser un alias de modèle que le compte de la passerelle ne peut pas appeler.

Étape 2 : Ajouter l'identifiant Flatkey dans OpenCode

OpenCode stocke les identifiants des fournisseurs via /connect. Dans le TUI d'OpenCode :

/connect

Choisissez Autre, saisissez un ID de fournisseur tel que flatkey, puis collez la clé API Flatkey. Ne collez pas l'URL de base dans l'invite d'identifiant. La clé prouve l'identité ; l'URL de base doit être dans opencode.json.

Utilisez un ID de fournisseur simple. flatkey est préférable à flatkey-prod-openai-compatible-gateway-v2 car vous le saisirez dans les ID de modèle et les notes de restauration.

Étape 3 : Ajouter la configuration du fournisseur OpenCode

Créez ou mettez à jour opencode.json à la racine du projet que vous souhaitez tester.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Flatkey",
      "options": {
        "baseURL": "https://router.flatkey.ai/v1"
      },
      "models": {
        "your-current-flatkey-model-alias": {
          "name": "Flatkey primary model"
        }
      }
    }
  },
  "model": "flatkey/your-current-flatkey-model-alias"
}

Ceci est la configuration la plus simple pour un fournisseur compatible OpenAI pour OpenCode. Elle fournit à OpenCode un fournisseur nommé flatkey, lui indique d'utiliser le package AI SDK compatible OpenAI et expose un alias de modèle dans le sélecteur de modèle.

Si vous souhaitez qu'OpenCode utilise une route plus petite pour les tâches légères, ajoutez small_model uniquement après que la route principale fonctionne.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Flatkey",
      "options": {
        "baseURL": "https://router.flatkey.ai/v1"
      },
      "models": {
        "primary-flatkey-model-alias": {
          "name": "Flatkey primary"
        },
        "lighter-flatkey-model-alias": {
          "name": "Flatkey lightweight"
        }
      }
    }
  },
  "model": "flatkey/primary-flatkey-model-alias",
  "small_model": "flatkey/lighter-flatkey-model-alias"
}

Utilisez les alias de modèle que votre clé Flatkey peut réellement appeler. Si votre compte expose une route authentifiée /v1/models, comparez les ID de modèle configurés à cette réponse. Sinon, copiez les alias depuis le tableau de bord Flatkey actuel ou le répertoire de modèles et vérifiez-les avec une requête réelle.

Étape 4 : Sélectionner et tester le modèle dans OpenCode

Après avoir enregistré la configuration, ouvrez le sélecteur de modèle.

/models

Sélectionnez le modèle du fournisseur Flatkey. Ensuite, exécutez une petite invite dans OpenCode :

Reply with exactly: opencode flatkey route ok

Ne déplacez pas encore un flux de travail de codage complet. Enregistrez d'abord un paquet de vérification compact.

Cela transforme une migration de fournisseur compatible OpenAI pour OpenCode en un petit changement opérationnel au lieu d'un échange de fournisseur à l'aveugle.

Étape 5 : Garder les Chat Completions et les Responses séparés

La documentation des fournisseurs personnalisés d'OpenCode signale une limite de package : utilisez @ai-sdk/openai-compatible pour les fournisseurs compatibles OpenAI qui utilisent /v1/chat/completions ; si un fournisseur ou un modèle utilise /v1/responses, utilisez @ai-sdk/openai.

Cela signifie que la première route Flatkey doit être un modèle de type Chat Completions, sauf si vous avez des preuves actuelles que votre modèle sélectionné et le chemin du client utilisent une famille de points de terminaison différente.

Utilisez ce tableau de décision avant d'ajouter d'autres modèles.

Pour la plupart des travaux de configuration, commencez avec une seule route Chat Completions. Ajoutez le streaming, les appels d'outils et les alias de modèles secondaires après que le premier test de fumée du fournisseur compatible OpenAI pour OpenCode est visible dans Flatkey.

Étape 6 : Ajouter les contrôles d'équipe une fois que la route fonctionne

Une fois qu'OpenCode peut appeler Flatkey, rendez la route observable.

C'est là que Flatkey devient plus qu'une simple URL de base. Un fournisseur compatible OpenAI pour OpenCode fonctionnel devrait également offrir aux équipes de plateforme, financières et opérationnelles un endroit pour examiner l'utilisation des modèles et modifier la route sans demander à chaque développeur de gérer des comptes de fournisseur distincts.

Pour une planification de migration plus large, associez ce guide au guide de migration de l'API compatible OpenAI de Flatkey. Si vous comparez des outils de codage adjacents, consultez le guide du fournisseur compatible OpenAI pour Continue.dev et le guide de configuration compatible OpenAI pour Roo Code.

Dépannage d'un fournisseur compatible OpenAI pour OpenCode

Si la première requête échoue, ne modifiez pas encore les invites, les agents, les autorisations ou le code du dépôt. Gardez la surface de débogage du fournisseur compatible OpenAI pour OpenCode petite : informations d'identification, ID du fournisseur, URL de base, package, alias du modèle et une simple requête de chat.

Liste de contrôle finale

Avant d'utiliser Flatkey comme route par défaut pour OpenCode, confirmez :

1. /connect possède des informations d'identification Flatkey sous le même ID de fournisseur que celui utilisé dans opencode.json.
2. provider.flatkey.npm est @ai-sdk/openai-compatible pour la route Chat Completions.
3. provider.flatkey.options.baseURL est https://router.flatkey.ai/v1.
4. model pointe vers une valeur flatkey/<model-alias> configurée.
5. /models affiche le modèle Flatkey configuré.
6. Une invite OpenCode d'une seule ligne est retournée avec succès.
7. Les journaux d'utilisation ou de requêtes de Flatkey affichent la requête de test OpenCode.
8. La route précédente du fournisseur/modèle est documentée pour la restauration.

Une configuration de fournisseur compatible OpenAI pour OpenCode est complète lorsque le fournisseur est configuré, sélectionnable, vérifié dans les journaux Flatkey et réversible. Lorsque vous êtes prêt à router le trafic du modèle d'agent de codage via une seule clé, obtenez une clé Flatkey et commencez avec une seule invite OpenCode à faible risque.