Lorsque OpenCode avec Ollama cesse de fonctionner, vérifiez le point de terminaison du serveur et l’identifiant exact du modèle avant de changer de modèle. Si ces deux vérifications passent, testez une petite modification de fichier pour distinguer un problème d’appel d’outil d’un problème de connexion. Un modèle qui répond à une requête de chat n’a franchi que la première étape d’un workflow d’agent de codage.
Ce guide suppose qu’Ollama et OpenCode sont déjà installés. Pour l’installation et la configuration du fournisseur, consultez le guide de configuration Ollama avec OpenCode. La procédure présentée ici isole les pannes sans modifier à répétition votre configuration fonctionnelle.
Identifier quelle requête échoue
Une panne d’OpenCode peut survenir avant l’inférence, pendant la génération ou lors de l’exécution d’un outil. Vérifiez ces étapes séparément. Une connexion refusée révèle un problème différent de celui d’un modèle renvoyant un paragraphe ressemblant à du JSON. Notez le point de terminaison, le modèle sélectionné et l’erreur avant de modifier un paramètre, afin de pouvoir déterminer si le changement a été utile.
| Observation | Vérification suivante | Ce que le résultat confirme |
|---|---|---|
| Connexion refusée | Envoyer une requête à /api/version sur l’hôte et le port configurés | Si ce point de terminaison Ollama est accessible |
| Modèle introuvable | Lire /v1/models et comparer l’identifiant exact | Si le modèle demandé existe sur ce serveur |
| Le chat fonctionne, les fichiers restent inchangés | Inspecter les appels d’outils et les résultats de permission | Si OpenCode a tenté et terminé une action |
| Les petites modifications fonctionnent, les tâches volumineuses échouent | Inspecter le contexte alloué et les logs d’exécution | Si la tâche plus volumineuse rencontre une limite mesurable |
| Le local fonctionne, le cloud reste bloqué | Tester les deux routes séparément | Si la panne est spécifique au chemin cloud |
Notez les versions avant de reproduire une panne :
opencode --version
ollama --version
Les vérifications locales de cet article ont utilisé OpenCode 1.19.4 et Ollama 0.32.9 sur un Apple M3 Ultra avec 96 Go de mémoire unifiée. Ce matériel peut exécuter notre modèle 31B choisi ; ce n’est pas une recommandation de mémoire pour un ordinateur portable plus modeste. Pour la sélection de modèle sur d’autres configurations matérielles, consultez le guide des modèles de codage Ollama.
Vérifier le point de terminaison avant de changer le modèle
Envoyez une requête au même hôte et au même port que ceux utilisés par OpenCode. Un serveur local sur 127.0.0.1:11434 et un serveur sur 127.0.0.1:11435 sont des points de terminaison différents. Si la requête échoue, réparez d’abord le serveur ou l’adresse. Changer le modèle ne peut pas réparer une connexion réseau refusée.
curl --fail-with-body --max-time 5 \
http://127.0.0.1:11434/api/version
curl --fail-with-body --max-time 5 \
http://127.0.0.1:11434/v1/models
Si vous recevez une version en réponse, c’est qu’Ollama est bien accessible. La liste des modèles indique ensuite quels identifiants ce serveur expose. Une liste vide signifie que le serveur est joignable mais qu’aucun modèle n’y est référencé ; c’est différent d’une erreur de connexion.
Si Ollama est arrêté, lancez l’application ou exécutez son serveur dans un terminal :
ollama serve
Si le port est déjà occupé, vérifiez quel serveur est en cours d’exécution plutôt que d’en démarrer une autre instance. Une installation Ollama distante nécessite son adresse distante ; 127.0.0.1 fait toujours référence à la machine exécutant le client.
La documentation d’intégration OpenCode d’Ollama utilise une URL de base compatible OpenAI se terminant par /v1. Conservez ce suffixe dans la configuration du fournisseur d’OpenCode. Les routes de diagnostic natives telles que /api/version se situent en dehors de celui-ci.
Faire correspondre le modèle configuré à l’identifiant exact du serveur
Utilisez l’identifiant de modèle renvoyé par le serveur, y compris son tag. Un modèle téléchargé sur un serveur Ollama n’est pas disponible sur un autre serveur à moins que ce modèle n’y soit également présent. Vérifiez ensemble le fournisseur sélectionné, son URL de base et la déclaration du modèle avant de relancer la requête.
Voici la configuration du fournisseur utilisée pour nos vérifications avec OpenCode 1.19.4 :
{
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"options": {
"baseURL": "http://127.0.0.1:11434/v1"
},
"models": {
"gemma4:31b": {
"name": "Gemma 4 31B",
"limit": {
"context": 65536,
"output": 2048
}
}
}
}
}
}
Remplacez gemma4:31b par un identifiant que votre serveur liste réellement. L’exemple ne télécharge pas ce modèle. Le sélecteur complet d’OpenCode combine le nom du fournisseur et l’identifiant du modèle :
opencode run -m ollama/gemma4:31b "Reply with one short sentence."
Nous avons délibérément demandé un modèle absent via le point de terminaison compatible d’Ollama et avons reçu un HTTP 404 avec un not_found_error. Ce résultat confirme une erreur de sélection de modèle. Il n’indique ni un manque de mémoire ni un parseur d’outils défectueux.
Les configurations peuvent également provenir de plusieurs emplacements. La documentation de configuration d’OpenCode décrit comment les paramètres fusionnent. Inspectez la configuration résolue localement lorsqu’une valeur semble ignorée :
opencode debug config
La configuration résolue peut contenir des identifiants sensibles. Extrayez les paramètres du fournisseur concerné avant de partager un rapport de diagnostic, puis supprimez les clés ou les détails de compte sans rapport avec le problème.
Vérifier une action avec un banc d’essai de code jetable
Vérifiez vous-même le fichier modifié et exécutez son test. Donnez à OpenCode un petit fichier contenant un bug connu, demandez-lui de le corriger, puis exécutez une vérification indépendante. Cela teste l’accès aux fichiers, la modification et l’exécution tout en gardant le diagnostic suffisamment simple pour être inspecté.
Créez un nouveau répertoire et placez-vous dedans :
mkdir opencode-ollama-check
cd opencode-ollama-check
cat > add.mjs <<'JS'
export function add(a, b) {
return a - b;
}
JS
cat > check.mjs <<'JS'
import { add } from './add.mjs';
if (add(2, 3) !== 5) throw new Error('Expected add(2, 3) to return 5');
console.log('PASS');
JS
node check.mjs
La première vérification devrait échouer. Copiez votre configuration de fournisseur testée dans ce répertoire jetable, puis exécutez :
opencode run -m ollama/gemma4:31b \
"Read add.mjs. Fix add so it adds its arguments. Run node check.mjs."
node check.mjs
Inspectez add.mjs vous-même. Un message de succès du modèle est insuffisant si le fichier soustrait toujours ou si la vérification indépendante échoue. Gardez les invites de permission visibles afin de pouvoir distinguer une modification refusée d’un appel d’outil manquant. Lors de nos vérifications, macOS a résolu le banc d’essai sous /private/tmp tandis qu’un outil demandait son alias /tmp. OpenCode a traité le chemin aliasé comme externe et l’a rejeté lors d’une exécution non interactive. L’utilisation du répertoire résolu et de chemins de fichiers relatifs a permis au banc d’essai de s’exécuter avec des permissions à portée limitée.
Pour une inspection plus approfondie, le CLI d’OpenCode prend en charge la sortie JSON :
opencode run --format json -m ollama/gemma4:31b \
"Read add.mjs and explain the implementation."
Recherchez un outil exécuté et son résultat. Un texte contenant un nom de fonction ou un objet JSON ne prouve pas à lui seul qu’OpenCode a exécuté quoi que ce soit. Après correction du point de terminaison et des permissions du banc d’essai, une exécution de réparation a lu le banc d’essai, remplacé la soustraction par une addition et passé une vérification Node indépendante. Une deuxième exécution a passé la même vérification après remplacement de l’identifiant de modèle délibérément absent. Lors de notre requête de test directe sur l’API, Gemma 4 31B a renvoyé un appel read_file structuré avec un contexte de 65 536. Ce résultat unique valide le format de réponse de la requête de test, pas la fiabilité sur l’ensemble des tâches de codage.
Vérifier le contexte réellement alloué par Ollama
La limite de modèle affichée par OpenCode et l’allocation d’exécution d’Ollama doivent correspondre. Augmenter un nombre dans la configuration du client ne démontre pas que le serveur a alloué davantage de contexte. Inspectez le modèle en cours d’exécution pendant une requête, puis comparez son contexte réel avec le prompt de la tâche et l’historique des outils.
La documentation sur le contexte d’Ollama recommande au moins 64 000 tokens pour les outils et agents de codage. Elle explique également que des allocations plus importantes consomment davantage de mémoire. Un serveur lancé manuellement peut définir une allocation explicite :
OLLAMA_CONTEXT_LENGTH=65536 ollama serve
Définissez cette variable sur le processus exécutant Ollama. L’exporter uniquement dans le terminal exécutant OpenCode ne reconfigure pas une application Ollama déjà en cours d’exécution. Utilisez le paramètre de contexte de l’application si celle-ci gère votre serveur.
Pendant que le modèle est chargé, inspectez-le :
ollama ps
Vérifiez les colonnes CONTEXT et PROCESSOR. Si Ollama utilise un hôte ou un port personnalisé, pointez également le CLI vers ce serveur. La pression mémoire, le déchargement CPU, la troncature et les échecs de format d’outil nécessitent des preuves distinctes ; une réponse lente ne suffit pas à identifier laquelle de ces causes est en jeu.
Si votre matériel ne peut pas accueillir le contexte requis, choisissez un modèle plus petit prenant en charge les outils et répétez le même banc d’essai. Évitez de comparer deux modèles en utilisant des tâches différentes puis d’attribuer la différence à la qualité du modèle.
Conserver un rapport de panne utile
Un rapport utile permet à un autre développeur de reproduire la même requête. Incluez les versions, la configuration du fournisseur expurgée, le tag exact du modèle, le contexte alloué et le plus petit fixture qui échoue toujours. Notez si une requête directe réussit et si OpenCode atteint le serveur de modèle. Ces détails aident les mainteneurs à localiser la panne.
Le guide de dépannage OpenCode explique comment localiser les logs. Sur la version testée, cette commande identifie les chemins de données et de logs configurés :
opencode debug paths
Distinguez clairement les résultats locaux des résultats cloud. Un test de codage local ne peut pas valider l’authentification ou la disponibilité d’Ollama Cloud, et une panne cloud ne prouve pas une régression locale de l’utilisation des outils. De même, un ancien ticket décrivant le même symptôme ne prouve pas que le correctif proposé s’applique à votre version installée.
Si le fixture réussit mais que la tâche de votre dépôt échoue, conservez le fixture fonctionnel et ajoutez de la complexité progressivement : un fichier supplémentaire, une entrée plus volumineuse ou une séquence d’outils plus longue. Le premier changement qui reproduit la panne est plus utile que de réinstaller les deux applications sans point de comparaison.
Pour une configuration de fournisseur distincte après avoir terminé le diagnostic local, le guide de fournisseur personnalisé OpenCode couvre la configuration Haimaker. Gardez vos tests locaux privés ; changer de fournisseur est une option à envisager ensuite, si la charge de travail le permet.
Questions fréquemment posées
Une réponse de chat Ollama réussie signifie-t-elle que les outils OpenCode fonctionneront ?
Non. Une réponse de chat prouve que le modèle peut générer du texte. OpenCode a également besoin d’appels d’outils structurés, de la permission de les exécuter et d’un contexte suffisant pour la tâche. Vérifiez une modification de fichier réelle et le résultat de son test.
Augmenter la limite de contexte d’OpenCode alloue-t-elle plus de mémoire à Ollama ?
Une limite de contexte affichée dans OpenCode ne prouve pas qu’Ollama a alloué ce contexte. Configurez le serveur Ollama et inspectez le modèle en cours d’exécution avec ollama ps. Un contexte plus large augmente également les besoins en mémoire.
Faut-il tout réinstaller lorsqu’un modèle Ollama disparaît d’OpenCode ?
Commencez par comparer les identifiants de modèle renvoyés par Ollama avec le modèle déclaré dans votre configuration OpenCode. Vérifiez le point de terminaison et le fournisseur sélectionné avant de réinstaller l’une ou l’autre application.