OpenCode + Ollama : un agent de code dans votre terminal

#OpenCode avec Ollama : qui fait quoi

OpenCode est un agent de code open source qui s'exécute dans le terminal : il lit votre projet, modifie des fichiers et lance des commandes. Il ne fournit pas de modèle par lui-même. Ollama, lui, télécharge et exécute des modèles sur votre machine, et expose une API locale. Les deux se complètent : OpenCode envoie ses requêtes à Ollama, qui répond avec un modèle local. La question « OpenCode ou Ollama » ne se pose donc pas, on utilise les deux.

L'intérêt du local n'est pas idéologique. Un agent de code voit tout : l'arborescence, les fichiers de configuration, la logique métier. Avec un modèle local, ce contexte reste sur la machine, sans facturation au token ni dépendance au réseau. Le prix à payer est la capacité : un modèle local de quelques dizaines de milliards de paramètres n'égale pas les plus gros modèles hébergés, et les tâches longues se déroulent plus lentement.

#Prérequis : machine, terminal et Ollama

Ollama en service

Vérifiez qu'un modèle répond avant de configurer quoi que ce soit : ollama list, puis ollama run avec un modèle de code. Si cela marche, il ne reste que la configuration d'OpenCode.

Un terminal moderne

La documentation d'OpenCode cite WezTerm, Alacritty, Ghostty et Kitty. Sous Windows, elle recommande d'utiliser WSL pour de meilleures performances et une compatibilité complète.

De la mémoire pour le contexte

Un agent lit des fichiers et accumule l'historique. Ollama indique qu'OpenCode exige une longueur de contexte d'au moins 64 000 tokens, ce qui augmente la mémoire nécessaire au-delà des poids du modèle.

Un dépôt git

Pas obligatoire, mais conseillé : un git diff ou un git restore annule proprement une session ratée.

#Installer OpenCode et le relier à Ollama

OpenCode s'installe par un script ou par les gestionnaires de paquets. La documentation liste le script officiel, npm, bun, pnpm, yarn, Homebrew, Arch, Chocolatey, Scoop, Mise et Docker. Pour macOS et Linux avec Homebrew, elle recommande le tap officiel plutôt que la formule de base, qui est mise à jour moins souvent.

curl -fsSL https://opencode.ai/install | bash

npm install -g opencode-ai

brew install anomalyco/tap/opencode

choco install opencode
scoop install opencode

#Méthode rapide : ollama launch opencode

Ollama sait lancer OpenCode avec un modèle choisi. La commande ollama launch opencode démarre OpenCode avec une configuration passée en ligne, sans écraser votre fichier ~/.config/opencode/opencode.json ; vos réglages OpenCode existants continuent de s'appliquer. Avec l'option --config, Ollama configure OpenCode sans ouvrir de session interactive. Les modèles définis seulement dans opencode.json n'apparaissent pas dans le sélecteur de ollama launch.

ollama launch opencode

#Méthode manuelle : déclarer Ollama comme fournisseur

Si vous préférez garder la main, ajoutez un fournisseur à opencode.json, global (~/.config/opencode/opencode.json) ou à la racine du projet. L'endpoint compatible OpenAI d'Ollama est http://localhost:11434/v1. Chaque clé sous models doit reprendre exactement le nom du modèle tel qu'affiché par ollama list.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": {
        "qwen3-coder:30b": { "name": "Qwen3-Coder 30B" },
        "devstral-small-2:24b": { "name": "Devstral Small 2" }
      }
    }
  }
}

Relancez OpenCode : le sélecteur de modèle propose les modèles déclarés sous le fournisseur Ollama.

#Le piège numéro un : la longueur de contexte

Beaucoup de premiers essais échouent parce que le contexte est trop court : l'agent perd le début de la tâche, répète ses lectures de fichiers ou produit des modifications incohérentes. Ollama ne fixe pas un contexte unique : la documentation indique 4k tokens en dessous de 24 Go de VRAM, 32k entre 24 et 48 Go, 256k à partir de 48 Go. Elle précise que les tâches qui demandent un grand contexte, comme les agents et les outils de code, doivent être réglées à au moins 64 000 tokens.

Pour changer la valeur, deux voies existent. Dans l'application Ollama, un curseur des réglages fixe le contexte. En ligne de commande, la variable OLLAMA_CONTEXT_LENGTH s'applique au lancement du serveur. Un contexte plus grand consomme davantage de mémoire : contrôlez avec ollama ps que le modèle tient entièrement sur le GPU, car un modèle qui déborde sur le processeur devient très lent.

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

#Quel modèle local pour un agent de code

Un agent doit appeler des outils de manière fiable : lire, écrire, exécuter. Choisissez un modèle qui affiche la capacité tools dans la bibliothèque Ollama. Voici des candidats dont les tags et tailles ont été relevés sur ollama.com.

Ces tailles sont celles des fichiers ; ajoutez le cache de contexte, qui grossit avec les 64 000 tokens demandés. Le modèle de 15 Go (Devstral Small 2) est le plus accessible sur une machine de 24 Go ; celui de 19 Go (Qwen3-Coder 30B) demande davantage de marge. Sur une machine plus modeste, un modèle plus petit exécute des tâches simples et ciblées, mais décroche plus vite sur un refactoring qui touche plusieurs fichiers.

#Un workflow réel : ajouter une route et son test

Cas concret : ajouter une route GET /health à une petite API Express et la couvrir par un test. La documentation d'OpenCode recommande de commencer par /init, qui analyse le projet et crée un fichier AGENTS.md à la racine, à committer dans git pour aider l'agent à comprendre la structure.

1. 01
   Ouvrir le projet

   Placez-vous à la racine du dépôt, lancez opencode, puis /init la première fois. Vérifiez en bas que le modèle sélectionné est bien un modèle Ollama.
2. 02
   Passer en mode Plan

   La touche Tab bascule entre les modes Plan et Build. Le mode Plan désactive les modifications : l'agent propose seulement comment il procéderait. Demandez-lui un plan avant tout changement.
3. 03
   Décrire la tâche

   Donnez le contexte comme à un développeur junior : « Ajoute une route GET /health dans src/server.js qui renvoie status ok, puis un test dans test/health.test.js. » Le caractère @ permet de chercher un fichier dans le projet.
4. 04
   Passer en mode Build

   Quand le plan vous convient, appuyez de nouveau sur Tab et demandez d'appliquer les modifications.
5. 05
   Exécuter et itérer

   L'agent peut lancer npm test, lire la sortie et corriger. Cette boucle exécuter, observer, corriger est le cœur de l'agentique.
6. 06
   Vérifier et committer

   Relisez git diff avant de committer. Si la session a dérapé, git restore ramène les fichiers à l'état précédent.

Avec un modèle local, chaque étape est plus lente qu'avec un modèle hébergé, et une consigne ambiguë demande parfois une reformulation. Le gain est la maîtrise : le code et le contexte restent sur votre machine, et vous choisissez le modèle, sa quantification et sa taille de contexte en fonction de votre matériel.

#Permissions : ce que l'agent peut faire sans vous demander

Une idée répandue est que l'agent ne modifie rien sans votre accord. Ce n'est pas le comportement par défaut. La documentation d'OpenCode indique que, sans configuration, la plupart des permissions valent allow, c'est-à-dire qu'elles s'exécutent sans demander ; seules quelques-unes, comme external_directory et doom_loop, valent ask. Les fichiers .env sont refusés en lecture par défaut, sauf .env.example.

Pour un agent qui pilote un modèle local moins fiable, un réglage plus strict est prudent. Le fichier opencode.json accepte une section permission où chaque action vaut allow, ask ou deny, y compris avec une règle globale * à ask.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": { "*": "ask" }
}

#OpenCode, Cline ou Aider : lequel choisir

Les trois utilisent l'API d'Ollama ; essayer les deux plus proches de vos habitudes prend une heure et vaut mieux qu'un comparatif. Pour l'autocomplétion en ligne plutôt qu'un agent, regardez Tabby.

#Dépannage

Le modèle n'apparaît pas

Le nom dans opencode.json ne correspond pas à ollama list. Copiez le nom exact, tag compris. Avec ollama launch, un modèle défini seulement dans opencode.json n'apparaît pas dans son sélecteur.

L'agent oublie ce qu'il vient de lire

Le contexte est trop court : passez à 64 000 tokens (OLLAMA_CONTEXT_LENGTH) et vérifiez avec ollama ps.

Connexion refusée

Le serveur Ollama ne tourne pas ou n'écoute pas sur le port par défaut 11434. Testez ollama list, puis l'URL de baseURL.

Appels d'outils qui échouent

Le modèle ne gère pas bien les outils. Prenez un modèle marqué tools dans la bibliothèque Ollama.

Réponses très lentes

Le modèle et son contexte débordent de la VRAM et une partie s'exécute sur le processeur. Réduisez le contexte, la taille du modèle ou la quantification.

#Pour aller plus loin

• Cline + Ollama dans VS Code
• Aider + Ollama en terminal
• Tabby : autocomplétion de code locale
• Choisir sa quantification
• Comprendre la fenêtre de contexte
• Installer Ollama en 5 minutes

• Source : Ollama, intégration OpenCode
• Source : Ollama, longueur de contexte
• Source : documentation OpenCode
• Source : permissions OpenCode