Corriger les erreurs du forfait gratuit OpenCode sans risque

Historique de revue et état des tests

• 11 septembre 2026 : la recette DigitalOcean initiale associait les champs documentés du fournisseur personnalisé au point de terminaison Chat Completions, sans compte rendu d’une requête payante réussie.
• 4 octobre 2026 : l’article anglais a ajouté les vérifications du fournisseur existant et de l’offre gratuite avant la voie payante facultative.
• 8 octobre 2026 : une revue documentaire ciblée a vérifié les commandes et le dépannage des modèles, les conditions Zen, la configuration des fournisseurs, les permissions et les références DigitalOcean Chat Completions/facturation. L’introduction française suit désormais le même diagnostic initial. Cette revue documentaire ne constitue pas un nouveau résultat d’exécution.

La recette payante ci-dessous vise le CLI OpenCode 1.x (opencode-ai) et sa configuration de permissions documentée. Aucune combinaison précise de version OpenCode, modèle et système n’a été validée par exécution pour cet article ; aucune version exacte n’est donc présentée comme testée. Notez le résultat réel d’opencode --version avant de remplir la fiche après l’étape 7. La compatibilité OpenCode 2 sort du périmètre vérifié de cette recette.

Sources de la revue : Commandes et mises à jour · Modèles · Dépannage · Conditions Zen · Fournisseurs personnalisés · Permissions · Chat Completions · Facturation de l’inférence.

Identifier l’erreur avant de choisir un fournisseur

Commencez par le message exact et le fournisseur/modèle affichés dans OpenCode. Vous n’avez pas besoin d’acheter de l’inférence pour examiner une erreur de version ou de sélection du fournisseur.

• Si le message exige OpenCode 1.18.0 ou une autre version minimale, vérifiez opencode --version, suivez la procédure officielle opencode upgrade, redémarrez le client puis revérifiez sa version dans le terminal utilisé. Suivez le minimum indiqué par votre erreur actuelle ; 1.18.0 n’est pas une exigence permanente. Une mise à jour n’ajoute ni crédit ni droit d’accès.
• Si le message indique que le forfait gratuit ne peut être utilisé que depuis OpenCode, revenez au client OpenCode plutôt qu’à un autre client ou à un appel API direct. Avec /models, vérifiez le modèle et le fournisseur réellement sélectionnés. Consultez les conditions et tarifs Zen actuels avant un nouvel essai : une offre gratuite peut être temporaire. Si l’erreur persiste dans un client à jour, conservez une copie expurgée et demandez de l’aide au projet ; ne modifiez pas les en-têtes pour imiter un client autorisé.
• Pour ProviderModelNotFoundError ou un modèle inattendu, lancez opencode models, comparez l’identifiant fournisseur/modèle avec les entrées disponibles, puis sélectionnez la bonne entrée avec /models. Si le fournisseur demande une authentification, utilisez son parcours /connect et vérifiez ses conditions d’accès.
• Pour HTTP 401 ou 403, notez quel fournisseur répond. Ce seul statut ne permet pas de distinguer une clé invalide, une restriction de compte ou une règle de l’offre gratuite. Consultez les règles d’authentification et d’accès de ce fournisseur.

Ces messages sont des exemples, pas des erreurs universelles ni des correctifs garantis. Si votre fournisseur actuel répond à votre besoin, conservez-le. La procédure DigitalOcean qui suit est une option payante avec ses propres conditions d’accès et de facturation ; elle ne débloque pas l’offre gratuite d’OpenCode.

Après les vérifications de version et de fournisseur ci-dessus, poursuivez seulement si vous avez choisi la voie payante DigitalOcean. Le dossier jetable et le test en lecture seule servent à distinguer les problèmes de clé, de point de terminaison, de modèle, de compte et de permissions sans ouvrir un vrai projet.

1. Reconnaître la panne

Ce guide concerne une installation OpenCode avec DigitalOcean qui ne parvient pas à s'authentifier, trouver un modèle, joindre le fournisseur ou effectuer une action d'outil. Il n'existe pas de message d'erreur unique à rechercher. La clé, l'URL de base, l'identifiant du modèle, les droits du compte ou l'outil demandé peuvent être en cause.

Cette procédure suppose OpenCode CLI déjà installé sur macOS ou Linux, avec Bash et Python 3.9 ou ultérieur. Sous Windows, utilisez WSL avec ces outils installés dans WSL. Vérifiez d'abord opencode --version et python3 --version. Revenez au guide d'installation si nécessaire.

La configuration ci-dessous associe les champs du fournisseur personnalisé OpenCode au point de terminaison Chat Completions de DigitalOcean. Respectez le périmètre documentaire et les versions indiqués plus haut. Aucun message d’erreur, réponse de modèle ou succès d’exécution précis n’est garanti.

2. Garder le test inoffensif

Ouvrez un nouveau terminal et saisissez bash pour utiliser la syntaxe ci-dessous. N'effectuez pas ce test dans un dépôt de travail. Créez le dossier temporaire avec le bloc suivant, puis gardez ce terminal ouvert. Il contient un seul fichier texte témoin ; vous ajouterez uniquement une configuration sans identifiants secrets.

Notez le chemin affiché et les deux nombres de la somme de contrôle. Le fichier doit contenir exactement une ligne : The demo garden has 7 blue pots. Ne copiez ni secrets, ni dépôt réel, ni fichiers .env, ni extensions personnalisées dans ce dossier. Ne placez jamais d'identifiants secrets dans des fichiers versionnés.

Ces règles limitent les actions des outils de l'agent ; elles ne constituent pas un bac à sable du système d'exploitation. OpenCode fusionne plusieurs configurations. Avant le lancement, examinez la configuration globale, les extensions, les règles d'agent et les paramètres OPENCODE_CONFIG, OPENCODE_CONFIG_DIR et OPENCODE_CONFIG_CONTENT. Utilisez un compte local neuf si vous ne maîtrisez pas la configuration héritée. Consultez votre administrateur pour les paramètres gérés au lieu de les contourner.

TEST_DIR=$(mktemp -d "${TMPDIR:-/tmp}/opencode-provider-test.XXXXXX")
cd "$TEST_DIR" || exit 1
printf 'The demo garden has 7 blue pots.\n' > fixture.txt
pwd
cksum fixture.txt

Fusion des configurations OpenCode

3. Vérifier la clé et les modèles disponibles

La préparation locale et les sommes de contrôle ne demandent aucun compte cloud. Les vérifications réseau suivantes nécessitent un compte DigitalOcean ayant accès à Serverless Inference, une clé d’accès au modèle et des crédits promotionnels admissibles ou des fonds prépayés. L'inférence est facturée. Vérifiez les limites actuelles et le niveau du compte avant les requêtes ; les niveaux 1 et 2 restreignent l'accès aux modèles commerciaux. N'activez pas la recharge automatique uniquement pour ce test.

Utilisez une clé d'accès au modèle destinée à ce petit test et saisissez-la dans l'invite masquée ci-dessous. DO_INFERENCE_API_KEY est notre nom de variable locale, pas un nom imposé par DigitalOcean. La vérification de présence n'affiche pas le secret et ne prouve pas sa validité. Arrêtez si la clé manque.

Une clé limitée à un VPC ne peut pas authentifier un ordinateur ordinaire situé hors de ce VPC. Utilisez une clé de test approuvée, limitée au modèle choisi, avec un accès réseau adapté au test local. N'affaiblissez pas une clé de production. La référence de gestion des clés décrit leur création sous INFERENCE → Manage et les restrictions de modèle et de VPC.

Listez ensuite les identifiants avec GET /v1/models et l'authentification Bearer documentés. Choisissez un modèle texte compatible avec Chat Completions et les appels d'outils selon le catalogue actuel. Les exemples DigitalOcean mentionnent llama3.3-70b-instruct, sans garantir sa disponibilité pour votre compte. Copiez un identifiant actuel, pas un nom d'affichage ni un nom de routeur.

set +x
read -r -s -p 'Model access key: ' DO_INFERENCE_API_KEY
printf '\n'
export DO_INFERENCE_API_KEY
if [ -n "${DO_INFERENCE_API_KEY:-}" ]; then
  printf 'Key is set; value hidden.\n'
else
  printf 'Key is missing. Stop here.\n'
fi

python3 - <<'PYTHON'
import json, os, urllib.request, urllib.error
key = os.environ.get("DO_INFERENCE_API_KEY")
if not key:
    raise SystemExit("Missing key")
request = urllib.request.Request(
    "https://inference.do-ai.run/v1/models",
    headers={"Authorization": "Bearer " + key},
)
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
    for model in result["data"]:
        print(model["id"])
except urllib.error.HTTPError as error:
    raise SystemExit(f"HTTP {error.code}: check account, key and endpoint")
except urllib.error.URLError:
    raise SystemExit("Network/TLS failure: check connection and trusted certificates")
PYTHON

Limites du compte et des modèles · Exemples officiels Chat Completions · Catalogue actuel des modèles · Créer et gérer les clés d'accès aux modèles

4. Configurer un fournisseur et interdire les écritures

Dans votre éditeur, enregistrez le JSON suivant sous opencode.json dans le dossier temporaire affiché. Remplacez les trois occurrences de MODEL_ID par le même identifiant vérifié de modèle Chat Completions. Ne remplacez pas {env:DO_INFERENCE_API_KEY} par le secret.

do-readonly est un identifiant local arbitraire du fournisseur. model et small_model sélectionnent fournisseur/modèle pour utiliser le même fournisseur lors des tâches auxiliaires. La clé du tableau models est l'identifiant API ; name est seulement un libellé. options.apiKey lit la variable d'environnement. options.baseURL se termine par /v1, pas /chat/completions : l'adaptateur @ai-sdk/openai-compatible ajoute la route Chat Completions.

Ce fournisseur de diagnostic est distinct de la connexion DigitalOcean intégrée via /connect, qui propose aussi OAuth. Conservez votre installation existante. Un modèle réservé à Responses nécessite un autre adaptateur ; ne le forcez pas à utiliser cet exemple Chat Completions.

La plupart des permissions OpenCode autorisent les actions par défaut. Ici, la règle générale interdit les outils et read ne permet que le fichier témoin. edit couvre aussi les écritures et les correctifs ; bash et l'accès hors dossier sont explicitement interdits. L'agent Build répète ces restrictions, car ses règles sont prioritaires. Restez sur Build pendant le test.

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "build",
  "model": "do-readonly/MODEL_ID",
  "small_model": "do-readonly/MODEL_ID",
  "share": "disabled",
  "provider": {
    "do-readonly": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "DigitalOcean read-only diagnostic",
      "options": {
        "baseURL": "https://inference.do-ai.run/v1",
        "apiKey": "{env:DO_INFERENCE_API_KEY}"
      },
      "models": {
        "MODEL_ID": {
          "name": "Selected chat model"
        }
      }
    }
  },
  "permission": {
    "*": "deny",
    "read": {
      "*": "deny",
      "fixture.txt": "allow",
      "*/fixture.txt": "allow"
    },
    "edit": "deny",
    "bash": "deny",
    "external_directory": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "*": "deny",
        "read": {
          "*": "deny",
          "fixture.txt": "allow",
          "*/fixture.txt": "allow"
        },
        "edit": "deny",
        "bash": "deny",
        "external_directory": "deny"
      }
    }
  }
}

Champs du fournisseur personnalisé · Permissions par défaut et priorité des agents

5. Effectuer une requête en lecture seule

Lancez opencode dans le même terminal Bash. Vérifiez que Build et do-readonly/votre-modèle sont actifs ; utilisez /models pour sélectionner cette entrée précise si nécessaire. Collez l'invite ci-dessous. Ne joignez pas le fichier avec @ et ne collez pas son contenu dans l'invite : le test doit utiliser l'outil de lecture.

Le test réussit si la session montre une lecture de fixture.txt et si la réponse indique sept pots bleus dans un jardin de démonstration. Quittez OpenCode, exécutez vous-même cksum fixture.txt et comparez les deux nombres à la référence. Cherchez des fichiers inattendus dans le dossier. Une réponse sans événement de lecture ne valide pas l'outil. Un refus de lire peut venir des permissions ou de la compatibilité des outils, pas forcément de la clé.

Une fois ce test réussi, le lien de parrainage ci-dessous peut servir si vous avez besoin d'un compte distinct pour de futurs tests. Je peux percevoir une commission. Il ouvre la destination de parrainage DigitalOcean ; vous devez encore créer la clé dans le panneau de contrôle. Il ne configure pas OpenCode et ne garantit ni éligibilité, ni crédits, ni accès.

opencode

Utilise l'outil read pour inspecter uniquement fixture.txt. Résume son unique information en une phrase. Ne modifie ni ne crée aucun fichier, n'exécute aucune commande et n'accède à aucun autre chemin.

6. En cas de panne, isoler la cause

Authentification : un HTTP 401 ou 403 est un indice, pas un diagnostic exact. Vérifiez le compte prévu, la validité et la portée de la clé, puis sa présence dans le même terminal. Remplacez une clé révoquée ou exposée dans le panneau de contrôle. Ne l'affichez pas, ne la placez pas dans le JSON et ne multipliez pas les clés pour résoudre une erreur d'URL.

Point de terminaison : comparez l'URL de base caractère par caractère avec https://inference.do-ai.run/v1. Un /v1 répété ou un /chat/completions ajouté peut viser la mauvaise route. N'utilisez ni api.digitalocean.com, destiné au contrôle des ressources, ni une URL Agent Platform.

Modèle : comparez les trois identifiants configurés avec la liste et les capacités actuelles. Une entrée dans la liste ne prouve ni la compatibilité des outils ni les droits du compte. Compte et réseau : vérifiez le solde prépayé, le niveau, les quotas, le DNS, le proxy et les certificats TLS approuvés. En cas de limitation, attendez et respectez les consignes de nouvelle tentative. Ne désactivez pas la vérification des certificats.

Si la liste fonctionne mais OpenCode échoue, lancez la sonde de chat directe facultative après avoir enregistré la configuration. Elle effectue une petite requête facturée, sans outils ni contenu de dépôt. Elle utilise la limite documentée max_completion_tokens ; max_tokens est obsolète. Chat response received: True oriente le diagnostic vers OpenCode ou les fonctions avancées du modèle ; cela ne valide ni le streaming ni les appels d'outils. Un échec HTTP maintient l'enquête sur le fournisseur, le compte ou l'API.

Si le chat direct réussit, vérifiez le fichier chargé, le fournisseur et les règles prioritaires, puis consultez le dépannage officiel pour votre version. Notez la version, l'identifiant du modèle, le statut HTTP et une erreur expurgée. Les journaux peuvent contenir des invites ou identifiants secrets : relisez-les avant partage. Ne supprimez pas toute la configuration ou le stockage des identifiants comme première mesure.

python3 - <<'PYTHON'
import json, os, urllib.request, urllib.error
with open("opencode.json", encoding="utf-8") as file:
    config = json.load(file)
model = config["model"].removeprefix("do-readonly/")
if model == "MODEL_ID":
    raise SystemExit("Replace MODEL_ID first")
key = os.environ.get("DO_INFERENCE_API_KEY")
if not key:
    raise SystemExit("Missing key")
payload = {"model": model, "messages": [{"role": "user", "content": "Reply with OK."}], "max_completion_tokens": 32}
request = urllib.request.Request(
    "https://inference.do-ai.run/v1/chat/completions",
    data=json.dumps(payload).encode(),
    headers={"Authorization": "Bearer " + key, "Content-Type": "application/json"},
)
try:
    with urllib.request.urlopen(request, timeout=60) as response:
        result = json.load(response)
    print("Chat response received:", bool(result.get("choices")))
except urllib.error.HTTPError as error:
    raise SystemExit(f"HTTP {error.code}: consult the troubleshooting branches")
except urllib.error.URLError:
    raise SystemExit("Network/TLS failure")
PYTHON

Dépannage officiel OpenCode · Points de terminaison d'inférence

7. Prouver le refus avant une première modification

Relancez OpenCode avec la même configuration et collez l'invite de refus ci-dessous. Résultat attendu : l'écriture est indisponible ou bloquée, et fixture.txt conserve sa somme de contrôle après fermeture. Inspectez le journal des outils et le fichier ; une phrase disant « je ne peux pas » ne prouve pas seule l'application de la règle.

Si l'interface ne montre ni tentative ni preuve d'outil indisponible, le contrôle est non concluant. Après la lecture seule réussie, fermez OpenCode et passez volontairement edit de deny à ask dans permission et agent.build.permission. Gardez bash et tous les autres refus. Laissez l’approbation automatique désactivée et ne lancez pas OpenCode avec --auto : ce mode approuve les actions qui demanderaient normalement une autorisation. Relancez et répétez l'invite d'écriture. Rejetez la véritable demande d'approbation. L'événement de rejet et la somme inchangée constituent la preuve observable. Sans demande d'approbation, arrêtez et cherchez la cause au lieu de valider le test.

Si une écriture s'exécute sans approbation ou si un nombre de la somme change, arrêtez. N'ouvrez pas de dépôt réel. Corrigez la configuration et repartez d'un fichier témoin neuf. Pour une première modification volontaire ultérieure, gardez edit sur ask, examinez la modification limitée au témoin et approuvez une seule fois. Évitez always, qui autorise davantage d'actions pour le reste de la session. Remettez edit sur deny aux deux endroits à la fin.

Essaie de remplacer blue par red dans fixture.txt avec l'outil edit. Ne contourne aucun refus par une commande shell ou un autre outil. Rapporte le résultat de l'outil.

cksum fixture.txt

Modèle de fiche de validation, sans résultat exécuté

Aucune requête payante ni aucun événement réel de lecture ou de refus n’a été enregistré pour cette revue. Remplissez cette fiche uniquement à partir de votre propre essai. Laissez les étapes non observées sur « non exécuté » ou « non concluant ». Masquez les identifiants secrets, les informations de compte et les chemins sans rapport avant tout partage.

État : NON EXÉCUTÉ
Date et heure de l’essai : non enregistrées
Versions du système, de Bash et de Python : non enregistrées
Résultat exact d’opencode --version : non enregistré
Identifiant fournisseur/modèle : non enregistré
Configuration héritée examinée : non enregistré
Somme de contrôle initiale de fixture.txt (deux nombres) : non enregistrée
Événement de lecture observé et fait résumé : non enregistrés
Événement edit bloqué/indisponible, ou approbation ask rejetée : non enregistré
Approbation automatique désactivée pour le contrôle ask : non confirmé
Somme de contrôle finale de fixture.txt (deux nombres) : non enregistrée
Fichiers inattendus ou commandes shell : non vérifiés
Sonde directe de chat facturée, facultative : non exécutée
Erreur expurgée/statut HTTP éventuel : non enregistrés
Résultat global (réussite/échec/non concluant) : non exécuté

Une réussite exige l’événement réel de lecture, une modification visiblement bloquée ou rejetée, des sommes identiques et aucune écriture ou commande inattendue de l’agent. Un simple refus écrit est non concluant. Notez séparément un succès partiel : un point de terminaison de chat fonctionnel ne valide pas les permissions des outils.

8. Revenir prudemment au dépôt réel et nettoyer

Reprenez uniquement les paramètres de fournisseur vérifiés et les permissions comprises. Conservez la version OpenCode, l'identifiant du modèle, la somme du témoin, l'événement de lecture et celui de blocage ou de rejet de modification. N'incluez pas la clé.

Pour nettoyer, quittez OpenCode et exécutez unset DO_INFERENCE_API_KEY dans le terminal de test. Avec le gestionnaire de fichiers, placez à la corbeille uniquement le dossier opencode-provider-test exact affiché au début. Ne supprimez pas son parent. Les sessions et caches OpenCode peuvent rester ailleurs ; consultez sa documentation pour les retirer aussi. Révoquez la clé temporaire dans le panneau de contrôle lorsqu'elle n'est plus utile.

• Commencez sur une branche ou un worktree isolé avec un état initial propre connu.
• Examinez les différences proposées avant acceptation ou commit.
• Gardez une approbation pour les écritures et commandes shell ; autorisez uniquement les commandes comprises.
• Ne collez jamais de secrets de production dans les invites. Vérifiez le contexte transmis au modèle hébergé.

Installation initiale d'OpenCode · Déboguer un build avec l'IA

Questions fréquentes

Pourquoi OpenCode signale-t-il une clé invalide ?

Vérifiez d'abord que la variable est renseignée dans le terminal qui lance OpenCode. Cela ne valide pas la clé. Utilisez une clé d'accès au modèle Serverless Inference du compte prévu, vérifiez son expiration ou sa révocation, puis relancez la liste des modèles. Ne collez jamais la clé dans une invite ou un rapport de bogue.

Que faire si le modèle est incompatible ?

Copiez l'identifiant exact dans la liste actuelle et vérifiez sa compatibilité avec Chat Completions et les appels d'outils dans le catalogue officiel. Remplacez les trois occurrences de MODEL_ID. La présence du modèle dans la liste ne prouve pas que votre compte peut effectuer tous les types de requêtes.

Ce test modifie-t-il des fichiers ?

Vous créez vous-même fixture.txt et opencode.json. L'agent doit laisser le fichier témoin intact, sans créer de fichiers dans le dossier ni exécuter de commandes shell. OpenCode peut néanmoins enregistrer ses sessions et ses caches. Comparez la somme de contrôle et inspectez le dossier après chaque test.

Que faire si le point de terminaison répond mais OpenCode échoue ?

Une sonde de chat directe réussie confirme l'authentification de base et l'accès au modèle. Vérifiez le fournisseur do-readonly sélectionné, la configuration chargée, les règles de l'agent et la version d'OpenCode. Une réponse de chat ne prouve pas la compatibilité des appels d'outils. Ne partagez qu'une erreur expurgée et la version pour demander de l'aide.