Utiliser Ollama avec votre agent de codage

Ce que vous connectez

Vous pouvez utiliser Ollama avec votre agent de programmation. La connexion est plus simple qu’on ne le pense. Vous modifiez une URL de base et choisissez un nom de modèle. Le champ de clé API exige toujours une valeur, mais le serveur local l’ignore. N’importe quelle chaîne convient donc.

Ollama écoute sur le port 11434 et accepte simultanément deux formats de requête. /v1/chat/completions est le format compatible avec OpenAI. La documentation d’Ollama indique que la clé y est obligatoire, mais ignorée. /v1/messages est le format compatible avec Anthropic, utilisé par Claude Code. Votre agent utilise déjà l’un de ces deux formats. Vous n’avez donc rien d’autre à modifier.

Cette configuration prend cinq minutes. L’utilisabilité du résultat dépend de deux paramètres que presque personne ne modifie : la longueur du contexte et le keep-alive. Elle dépend également du type de tâches confiées au modèle. Chaque paramètre fait l’objet d’une section distincte. Les limites réelles sont présentées à la fin.

Quels agents de codage acceptent une URL de base locale

Le test tient en une question : l’outil expose-t-il un paramètre d’URL de base ? Si oui, il peut communiquer avec votre serveur.

Ollama publie des pages d’intégration pour Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, les IDE JetBrains et VS Code. Aider documente séparément sa prise en charge d’Ollama. Cela couvre la plupart des outils désignés par l’expression agent de codage en août 2026. Ils n’utilisent pas tous le même format d’API, et c’est cette différence qui provoque les échecs de configuration.

• La plupart des agents attendent un endpoint compatible avec OpenAI. Indiquez-leur l’URL de base http://localhost:11434/v1 et une chaîne non vide comme clé API.
• Claude Code n’accepte aucune URL de base OpenAI. Il utilise l’API Anthropic Messages et nécessite donc que ANTHROPIC_BASE_URL soit défini sur http://localhost:11434, à l’adresse de laquelle Ollama fournit /v1/messages.
• Codex utilise l’API OpenAI Responses. Ollama fournit également /v1/responses depuis la version 0.13.3.
• Un agent qui ne propose aucun paramètre d’URL de base ne peut pas être redirigé, car l’endpoint est intégré au client. Placez plutôt une couche de traduction devant lui, par exemple une passerelle LiteLLM auto-hébergée, puis exposez à nouveau votre modèle dans le format exigé par le client.

Ollama peut générer ces configurations pour vous. ollama launch opencode démarre OpenCode avec une configuration inline pour le modèle choisi, ollama launch claude fait de même pour Claude Code et ollama launch droid --config écrit la configuration sans lancer l’outil.

Installer Ollama et télécharger un modèle capable d’appeler des outils

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama ls

L’installateur ajoute une unité systemd et la démarre. systemctl status ollama doit donc afficher active (running). Si ce n’est pas le cas, journalctl -e -u ollama affiche la raison.

Le modèle doit prendre en charge les tool calls, car c’est ainsi qu’un agent fonctionne. Il lit un fichier, écrit un patch, exécute le test, puis lit l’échec et réessaie. Un modèle incapable d’émettre un tool call décrira la modification en prose au lieu de l’effectuer, et l’agent bouclera ou s’arrêtera. Recherchez le libellé tools sur la page du modèle sur ollama.com avant de le télécharger. qwen3-coder:30b le prend en charge. En août 2026, ce tag correspond à un téléchargement de 19 GB avec une fenêtre de contexte de 256K.

Vérifiez maintenant les noms effectivement servis par le serveur :

curl http://localhost:11434/v1/models

Les chaînes de caractères de cette réponse sont celles que votre configuration d’agent doit contenir, caractère par caractère. Cette vérification permet de résoudre la plupart des erreurs indiquant qu’un modèle est introuvable. Si Ollama n’est pas encore installé, consultez le guide détaillé héberger vous-même un LLM avec Ollama sur un VPS.

Pointer OpenCode vers Ollama

Modifiez ~/.config/opencode/opencode.json :

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

La valeur sous models correspond au nom du modèle envoyé à Ollama. Elle doit donc correspondre exactement à ollama ls. Le champ name sert uniquement de libellé dans le sélecteur de modèles. Démarrez opencode, sélectionnez le provider Ollama, puis surveillez journalctl -e -u ollama pour confirmer que la requête est bien arrivée sur votre serveur et non ailleurs. La configuration de l’agent lui-même est décrite dans exécuter OpenCode sur un VPS.

Configurer Claude Code avec Ollama

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30b

ANTHROPIC_API_KEY est volontairement défini comme une chaîne vide. Si une véritable clé reste présente dans l’environnement, vos requêtes sont envoyées à l’API hébergée. Vous recevez alors une facture et aucune inférence locale. ollama launch claude configure tout cela pour vous.

Sachez ce que la couche de compatibilité ne prend pas en charge. Elle n’implémente pas tool_choice ni la mise en cache des prompts. Elle ne dispose pas non plus d’un endpoint de comptage des tokens. Les nombres de tokens affichés sont donc des approximations produites par le tokenizer du modèle. Claude Code fournit également un system prompt volumineux et un ensemble d’outils important. Il nécessite donc davantage de contexte qu’un client de chat. La question plus générale de ce qui est conservé ou non est traitée dans la possibilité d’auto-héberger Claude.

Diriger Aider vers Ollama

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30b

La documentation d’Aider recommande le préfixe ollama_chat/ plutôt que ollama/. Elle permet également de définir la fenêtre de contexte par modèle dans .aider.model.settings.yml, ce qui est utile lorsqu’un modèle nécessite une fenêtre différente de celle définie par défaut sur le serveur :

- name: ollama_chat/qwen3-coder:30b
  extra_params:
    num_ctx: 65536

Pourquoi une configuration fonctionnelle produit quand même des résultats incohérents

C’est la section importante. Ollama choisit une longueur de contexte par défaut en fonction de la VRAM (mémoire vidéo du GPU) qu’il détecte, et ces valeurs par défaut sont publiées :

[
  {
    "label": "Under 24 GiB VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "24 to 48 GiB VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "48 GiB VRAM or more",
    "default_context_tokens": "262,144"
  }
]

La plupart des offres VPS, ainsi que tous les serveurs uniquement équipés d’un CPU, utilisent la première ligne : 4,096 tokens. Seul un GPU puissant permet d’utiliser les 262,144 tokens de la dernière ligne.

Un agent consomme 4096 tokens avant même de commencer son travail. Le prompt système, les définitions des outils, la liste du dépôt et le premier fichier qu’il ouvre dépassent déjà cette taille. C’est là que le problème apparaît : aucune erreur n’est signalée. La documentation d’Aider indique qu’Ollama supprime silencieusement le contexte qui dépasse la fenêtre. Les tokens les plus anciens sortent de la fenêtre. Le modèle répond donc avec assurance au sujet d’un fichier qu’il ne peut plus voir, ou oublie une instruction donnée deux étapes plus tôt. Ce mécanisme explique la plupart des signalements selon lesquels un modèle local est trop limité pour écrire du code.

La documentation d’Ollama indique qu’il faut définir au moins 64000 tokens pour les tâches comme les agents et les outils de programmation. Définissez cette valeur sur le serveur :

sudo systemctl edit ollama.service

Ajoutez ces lignes dans le fichier d’override :

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Rechargez ensuite la configuration et redémarrez le service :

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps permet de vérifier le résultat. Cette commande affiche une colonne CONTEXT. Sa valeur indique le contexte réellement reçu par le modèle. Vos valeurs ID et SIZE seront différentes :

NAME               ID              SIZE     PROCESSOR    CONTEXT    UNTIL
qwen3-coder:30b    a1b2c3d4e5f6    24 GB    100% GPU     64000      4 minutes from now

Définissez cette valeur sur le serveur plutôt que dans l’agent, pour deux raisons. Le schéma OpenAI chat completions ne possède aucun champ pour la longueur du contexte. Un client compatible avec OpenAI ne peut donc pas la demander. De plus, le paramètre s’applique au serveur. Tous les agents configurés pour utiliser ce serveur en héritent. Si un modèle a besoin d’une fenêtre différente, intégrez cette valeur dans une copie du modèle avec un Modelfile :

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

Le contexte n’est pas gratuit. Une fenêtre plus longue consomme davantage de mémoire. Surveillez donc la colonne PROCESSOR. 100% GPU est la valeur recherchée. Dès qu’une partie du modèle est exécutée sur le CPU, le débit de tokens diminue suffisamment pour rendre une boucle d’agent inutilisable. Mesurer le nombre de tokens par seconde d’un LLM local permet de trouver la limite réelle de votre serveur. Le dimensionnement de la machine avant l’achat est expliqué dans la quantité de RAM et de CPU nécessaire pour un VPS exécutant un agent de programmation.

Conserver le modèle chargé entre les requêtes

Par défaut, Ollama décharge un modèle 5 minutes après sa dernière requête. Ce comportement convient à une boîte de dialogue, mais pas au travail avec un agent. Vous vous arrêtez pour lire un diff, le délai expire, puis la requête suivante recharge des dizaines de gigaoctets de poids depuis le disque avant l’apparition du premier token. Cela ressemble à un blocage.

OLLAMA_KEEP_ALIVE accepte une durée telle que 10m ou 24h, un simple nombre de secondes, -1 pour conserver indéfiniment le modèle chargé, ou 0 pour le décharger immédiatement. Définissez cette valeur à côté de la longueur du contexte :

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"

Le champ de requête keep_alive existe uniquement sur les endpoints natifs /api/generate et /api/chat d’Ollama, pas sur les endpoints de compatibilité. Un agent ne peut donc pas le définir pour chaque requête. La variable d’environnement est le seul levier disponible. Lorsque vous devez récupérer la mémoire, ollama stop qwen3-coder:30b décharge le modèle sans arrêter le serveur.

Exécuter Ollama sur un serveur distinct

Ollama écoute sur localhost. Pour y accéder depuis une autre machine, définissez OLLAMA_HOST=0.0.0.0:11434 dans le même override systemd, puis redémarrez le service.

Faites-le uniquement sur un réseau privé. La documentation d’Ollama indique qu’aucune authentification n’est requise pour l’API locale. Le port 11434 exposé sur Internet permet donc à n’importe qui d’utiliser votre matériel et de lire tout ce que votre agent envoie. Deux options sûres sont possibles. Conservez l’écoute sur localhost et transférez le port via SSH depuis votre ordinateur portable :

ssh -N -L 11434:localhost:11434 you@your-vps

Votre agent continue d’utiliser http://localhost:11434/v1 et ne voit aucune différence. L’autre option consiste à utiliser un VPN et à faire écouter Ollama sur l’adresse du VPN plutôt que sur 0.0.0.0. Si plusieurs personnes ou plusieurs agents doivent partager la même machine, le scheduler d’Ollama n’est pas conçu pour cette charge. La comparaison entre Ollama et vLLM montre à partir de quel point la différence de débit devient pénalisante.

Quand un modèle de code local est avantageux, et quand il ne l’est pas

Un agent piloté par un modèle que vous hébergez ne remplace pas une API frontier pour toutes les tâches. Il est clairement avantageux dans quatre types de travaux.

• Les modifications mécaniques en masse, lorsque chaque changement est limité et vérifiable. Renommer des éléments dans un repository, ajouter des annotations de type, rédiger des docstrings, traduire des commentaires. Le modèle peut fonctionner pendant des heures sans augmenter la facture.
• Les travaux qui ne doivent pas quitter votre matériel. Il peut s’agir de code client couvert par un accord de confidentialité ou d’un repository interne que vous n’avez pas le droit d’envoyer à un tiers.
• Les machines hors ligne et isolées du réseau, lorsqu’aucune API hébergée n’est disponible.
• Un coût prévisible. Une fois le serveur payé, un agent qui consomme des tokens dans une boucle ne coûte rien de plus, contrairement à une API facturée à l’usage. Quand un GPU VPS atteint le seuil de rentabilité par rapport aux tokens d’une API présente le calcul.

Il est moins performant pour les tâches longues comportant plusieurs étapes. « Trouver pourquoi ce test échoue, corriger la cause, mettre à jour les appelants » nécessite de nombreux appels d’outils corrects à la suite, tout en conservant l’historique complet dans le contexte. Un modèle de 8B à 14B sur un serveur modeste produira un appel d’outil mal formé ou perdra le plan après quelques échanges. Vous passerez alors plus de temps à le guider que la tâche n’en aurait demandé. Ce n’est pas un problème de prompt que vous pouvez résoudre en rédigeant mieux le prompt. C’est une limite de capacité.

Il est également moins performant lorsque les erreurs coûtent cher et que vous ne vérifierez pas chaque ligne. Confiez au modèle local des tâches ciblées dont vous vérifiez le résultat. Réservez un modèle hébergé aux travaux que vous ne contrôlerez pas étape par étape.

Modes de panne et chaînes affichées

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. Le serveur ne fonctionne pas ou l’agent pointe vers un autre hôte. Exécutez systemctl status ollama, puis journalctl -e -u ollama.

L’agent indique que le modèle n’existe pas. Le nom défini dans votre configuration ne correspond à aucun nom proposé par le serveur. Comparez-le avec curl http://localhost:11434/v1/models et copiez la chaîne affichée à cet endroit. Le tag fait partie du nom. Une configuration qui indique un tag que vous n’avez jamais téléchargé échoue donc, même si un modèle similaire est installé.

L’agent répond en prose et ne modifie jamais de fichier. Soit le modèle ne prend pas en charge les outils, soit la requête et les définitions de ses outils remplissent déjà la context window. Vérifiez l’indication tools sur la page du modèle, puis la colonne CONTEXT dans ollama ps.

Un long silence avant le premier token, puis une vitesse normale. Le keep-alive a expiré et les weights sont de nouveau lus depuis le disque. Définissez OLLAMA_KEEP_ALIVE.

Le modèle contredit un fichier qu’il vient de lire. Il s’agit d’une troncature du contexte. ollama ps affiche généralement une valeur CONTEXT inférieure à celle que vous pensez avoir définie, car la variable d’environnement a été définie dans votre shell au lieu de l’unité systemd.

Tout fonctionne, mais lentement, et PROCESSOR n’est pas 100% GPU. Le modèle et son contexte ne tiennent pas dans la VRAM. Réduisez la longueur du contexte ou utilisez un modèle plus petit ou une quantisation plus légère.

FAQ

Puis-je diriger Claude Code vers Ollama ?

Oui, mais pas avec une URL compatible avec OpenAI. Claude Code utilise l’Anthropic Messages API, et Ollama expose ce format sur /v1/messages, avec le même port 11434. Exportez ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama et une valeur vide pour ANTHROPIC_API_KEY, puis démarrez-le avec claude --model qwen3-coder:30b. ollama launch claude écrit ces paramètres à votre place. La couche de compatibilité n’implémente pas tool_choice ni la mise en cache des prompts. Elle ne fournit pas non plus de endpoint de comptage des tokens. Les nombres de tokens indiqués sont donc des approximations.

Pourquoi mon modèle local répond-il au sujet d’un code qu’il ne peut pas voir ?

Parce que la requête ne tient plus dans la fenêtre de contexte et que sa partie la plus ancienne a été supprimée sans message d’erreur. Ollama définit son contexte par défaut selon la VRAM détectée. En dessous de 24 GiB, cette valeur est de 4,096 tokens. Le prompt système et les définitions des outils d’un agent dépassent déjà cette valeur à eux seuls. Définissez OLLAMA_CONTEXT_LENGTH=64000 dans l’unité systemd, redémarrez Ollama, puis vérifiez que la colonne CONTEXT de ollama ps affiche la nouvelle valeur.

Quel modèle dois-je exécuter pour un agent de codage sur un VPS ?

Choisissez le plus grand modèle portant le label tools qui tient encore en mémoire avec une fenêtre de contexte de 64k, et préférez un modèle optimisé pour le code. qwen3-coder:30b est le choix courant sur un serveur équipé d’un GPU et disposant de suffisamment de VRAM. En dessous d’environ 14B paramètres, un modèle peut encore répondre correctement aux questions sur le code tout en échouant lors de modifications en plusieurs étapes. Le travail d’agent pénalise en effet les petites erreurs de formatage dans les appels d’outils. Testez-le avec une tâche réelle de votre propre dépôt plutôt qu’avec un prompt d’exemple.

Ai-je besoin d’un GPU pour exécuter un agent de codage avec mon propre modèle ?

En pratique, oui. L’inférence uniquement sur CPU fonctionne et convient aux questions isolées, mais un agent envoie de nombreuses requêtes par tâche et relit un long historique à chaque requête. Un débit de tokens faible transforme donc une tâche de deux minutes en tâche d’une heure. Vérifiez la colonne PROCESSOR dans ollama ps : toute valeur différente de 100% GPU signifie qu’une partie du modèle s’exécute sur le CPU, et le débit de tokens chute fortement.