Développement IA

Corriger une erreur de fournisseur OpenCode avec un test en lecture seule

11 septembre 2026

Diagnostiquez les erreurs de clé, de modèle et de permissions OpenCode avec un fichier temporaire, une lecture seule et une modification refusée.

Aller aux étapes ↓

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.

Les références officielles ont été vérifiées le 11 septembre 2026. La configuration associe les champs documentés du fournisseur personnalisé OpenCode au point de terminaison Chat Completions de DigitalOcean. C'est une procédure à tester, pas le compte rendu d'une requête payante réussie. Aucun message d'erreur ni aucune réponse précise du modèle ne sont garantis.

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

Vérifiez avant de continuer : Notez le dossier temporaire et les deux nombres de la somme.

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 un solde prépayé positif. 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.

Avant de continuer : Saisissez la clé uniquement dans l'invite Bash masquée, jamais dans la commande.

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

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.

Remplacez chaque valeur surlignée avant d’exécuter la commande.

{
  "$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"
      }
    }
  }
}

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. 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.

Avant de continuer : Cette sonde envoie une requête d'inférence facturée au modèle choisi.

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_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

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. 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

Vérifiez avant de continuer : Les deux nombres correspondent à la référence.

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é.

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.

Vérifier le résultat

Résultat attendu: Une lecture enregistrée, une somme inchangée et une écriture bloquée ou rejetée.
Arrêter si: Arrêter si une écriture s'exécute sans accord, si le témoin change ou si aucune preuve d'outil n'apparaît.
Étape suivante: Utiliser une branche ou un worktree et garder l'approbation des écritures et du shell.