Utiliser Ollama avec votre agent de code

Ce à quoi vous vous connectez

Vous pouvez utiliser Ollama avec votre agent de code. La connexion est plus simple que prévu. Vous modifiez une seule URL de base et vous choisissez un nom de modèle. Le champ de clé d’API attend toujours une valeur, mais le serveur local l’ignore. N’importe quelle chaîne convient donc.

Ollama écoute sur le port 11434 et expose trois interfaces d’API en parallèle. /api est l’API native d’Ollama. /v1 est la couche compatible avec OpenAI. Elle couvre elle-même plusieurs formats : /v1/chat/completions, /v1/responses, /v1/completions, /v1/models et /v1/embeddings. La documentation d’Ollama indique que la clé est obligatoire à cet endroit, mais qu’elle est ignorée. La troisième interface est compatible avec Anthropic : le client utilise http://localhost:11434 comme URL de base et lui ajoute /v1/messages, le format utilisé par Claude Code. La plupart des agents utilisent /v1/chat/completions, Codex utilise /v1/responses et Claude Code utilise /v1/messages. Votre agent prend déjà en charge l’un de ces formats. Rien d’autre ne change donc pour lui.

Cette configuration prend cinq minutes. L’utilité 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 aussi du type de tâches confiées au modèle. Chacun de ces deux paramètres fait l’objet d’une section. Les limites réelles sont présentées à la fin.

Quels agents de programmation acceptent une URL de base locale

Le test ne comporte qu’une question : l’outil expose-t-il un paramètre d’URL de base ? Si c’est le cas, 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 propre prise en charge d’Ollama. Cela couvre la plupart des outils désignés comme agents de programmation en octobre 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. Fournissez-leur l’URL de base http://localhost:11434/v1 et n’importe quelle chaîne non vide comme clé API.
• Claude Code n’accepte pas du tout une 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, où Ollama expose /v1/messages.
• Codex utilise l’API OpenAI Responses. Ollama expose é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. Si l’agent accepte une URL personnalisée mais nécessite un autre format d’API, 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 attendu 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 de votre choix, 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 récupérez 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 cause.

Le modèle doit prendre en charge l’appel d’outils, car c’est ainsi qu’un agent fonctionne. Il lit un fichier, écrit un correctif, exécute le test, puis lit l’échec et réessaie. Un modèle incapable d’émettre un appel d’outil décrira la modification en prose au lieu de l’effectuer. L’agent bouclera alors ou s’arrêtera. Recherchez le libellé `tools sur la page du modèle sur ollama.com avant de le récupérer. qwen3-coder:30b` le possède et, en octobre 2026, ce tag correspond à un téléchargement de 19 GB avec une fenêtre de contexte de 256K. Si votre serveur fonctionne uniquement sur CPU ou dispose de peu de RAM, le calcul de mémoire pour le tag Qwen 27B sur un VPS montre ce qui tient réellement dans 8 à 64 GB avant de lancer le téléchargement. Une fois le modèle récupéré, ces gigaoctets sont stockés sur le disque root du serveur. C’est la partie d’un VPS qui offre généralement le moins d’espace disponible. Consultez donc l’emplacement des fichiers de modèles d’Ollama et leur déplacement vers un autre emplacement avant que le disque ne soit plein.

Vérifiez maintenant les noms réellement 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, à l’identique. Cette vérification règle la plupart des erreurs de modèle introuvable. Si Ollama n’est pas encore installé, consultez le guide détaillé auto-héberger 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 clé 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 fournisseur Ollama et surveillez journalctl -e -u ollama pour vérifier 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.

Pointer Claude Code vers 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. L’URL de base détermine la destination des requêtes. Effacer cette clé évite d’utiliser des identifiants hébergés dans cette configuration locale. ollama launch claude configure tous ces paramètres à votre place.

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 fournit pas non plus de endpoint de comptage des tokens. Les nombres de tokens affichés sont donc des approximations fondées sur le tokenizer du modèle. Claude Code fournit également un prompt système volumineux et un ensemble d’outils important. Il a donc besoin de davantage de contexte qu’un client de chat. La question plus générale de ce qui est pris en charge ou non est traitée dans la possibilité d’auto-héberger Claude.

Pointer 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/. Par défaut, Aider demande suffisamment de contexte pour chaque requête, plus 8k tokens pour la réponse. Il 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 à partir de la VRAM totale (la mémoire vidéo des GPU) qu’il détecte, en soustrayant OLLAMA_GPU_OVERHEAD pour chaque GPU détecté. L’implémentation utilise les seuils suivants :

[
  {
    "label": "Under 23 GiB aggregate VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "23 to under 47 GiB aggregate VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "47 GiB aggregate VRAM or more",
    "default_context_tokens": "262,144"
  }
]

La plupart des offres VPS, ainsi que tous les serveurs uniquement équipés d’un CPU, se trouvent sur la première ligne : 4,096 tokens. Plusieurs GPU de plus petite capacité peuvent atteindre ensemble le seuil de 47 GiB et obtenir les 262,144 tokens de la dernière ligne.

Un agent envoie 4096 tokens avant même d’effectuer la moindre opération. 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 commence : aucune erreur n’est généré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. Le choix de cette valeur est une décision distincte, et le coût de num_ctx en mémoire KV cache pour chaque taille mérite d’être consulté avant de choisir une valeur.

La documentation d’Ollama indique que les tâches comme les agents et les outils de développement doivent utiliser au moins 64000 tokens. Configurez cette valeur sur le serveur :

sudo systemctl edit ollama.service

Ajoutez ces lignes au 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

Envoyez une requête depuis votre agent après le redémarrage, puis exécutez à nouveau ollama ps pour disposer d’un modèle chargé à inspecter. ollama ps est le contrôle à effectuer. Il affiche une colonne CONTEXT, et cette valeur correspond à ce que le modèle a réellement reçu. 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

Configurez 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 en demander une. De plus, ce paramètre s’applique au serveur. Tous les agents que vous dirigez vers cette machine en héritent. La sortie possède sa propre limite. Contrairement à la longueur du contexte, elle est transmise via l’endpoint compatible. Il faut donc utiliser num_predict et le champ max_tokens qui lui correspond lorsqu’une réponse s’interrompt au milieu d’un patch. Si un modèle a besoin d’une fenêtre différente, intégrez cette valeur dans une copie 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 correspond à la valeur recherchée. Dès qu’une partie du modèle est déplacée vers le CPU, le débit de tokens baisse suffisamment pour rendre une boucle d’agent inutilisable. Mesurer le nombre de tokens par seconde sur un LLM local permet de trouver la limite réelle de votre machine. Le dimensionnement de la machine avant l’achat est traité dans la quantité de RAM et de CPU nécessaire à un VPS pour agent de développement.

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 interface de chat, mais pas au travail avec un agent. Vous vous arrêtez pour lire un diff, le délai expire et la requête suivante recharge plusieurs dizaines de gigaoctets de poids depuis le disque avant l’apparition du premier token. Cela ressemble à un blocage.

OLLAMA_KEEP_ALIVE accepte une chaîne de durée telle que 10m ou 24h, un nombre entier de secondes, -1 pour conserver le modèle chargé indéfiniment, ou 0 pour le décharger immédiatement. Définissez ce paramètre avec la longueur du contexte :

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

Le champ de requête keep_alive existe sur les endpoints natifs /api/generate et /api/chat d’Ollama, ainsi que comme extension Ollama sur /v1/chat/completions. Un agent qui expose des champs de requête supplémentaires peut l’envoyer à cet endroit ; sinon, utilisez la variable d’environnement. Lorsque vous devez récupérer la mémoire, ollama stop qwen3-coder:30b décharge le modèle sans arrêter le serveur. Si vous voulez conserver ce réglage après un redémarrage, ou comparer le fait de garder les poids en mémoire toute la journée avec la récupération de cette mémoire, conserver un modèle Ollama chargé en mémoire fonctionne dans les deux cas.

Exécuter Ollama sur un serveur distinct

Ollama est lié à 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 précise qu’aucune authentification n’est requise pour l’API locale. Un port 11434 ouvert sur Internet permet donc à n’importe qui d’utiliser votre matériel. Deux options sûres sont possibles. Conservez la liaison 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 de pointer vers http://localhost:11434/v1 et ne voit aucune différence. L’autre option consiste à utiliser un VPN, en liant Ollama à l’adresse du VPN plutôt qu’à 0.0.0.0. Si plusieurs personnes ou plusieurs agents doivent partager la même machine, Ollama prend en charge les requêtes parallèles lorsque la mémoire disponible le permet. La comparaison entre Ollama et vLLM indique à partir de quel point la différence de débit devient pénalisante.

Dans quels cas un modèle de code local est efficace, et dans quels cas il ne l’est pas

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

• Les modifications mécaniques en masse, lorsque chaque changement est limité et que vous pouvez le vérifier. Renommer des éléments dans un dépôt, ajouter des annotations de type, rédiger des docstrings ou traduire des commentaires. Le modèle peut fonctionner pendant des heures sans faire évoluer 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 dépôt interne que vous n’êtes pas autorisé à envoyer à un tiers.
• Les machines hors ligne ou isolées, 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 en boucle ne coûte rien de plus. C’est l’inverse d’une API facturée à l’usage. Quand un GPU VPS atteint le seuil de rentabilité par rapport aux tokens d’une API contient le calcul.

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

Il est également moins efficace lorsque l’erreur coûte cher et que vous ne lirez pas chaque ligne. Confiez au modèle local des tâches étroitement définies dont vous vérifiez la sortie. Réservez un modèle hébergé aux travaux que vous ne contrôlerez pas étape par étape.

Modes de défaillance 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 de votre configuration ne correspond à aucun nom fourni par le serveur. Comparez-le à curl http://localhost:11434/v1/models et copiez la chaîne affichée. 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 aucun fichier. Soit le modèle ne prend pas en charge les outils, soit la requête et les définitions de ses outils occupent déjà toute la fenêtre de contexte. Vérifiez l’étiquette 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 poids 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é appliquée à votre shell au lieu de l’unité systemd.

Tout fonctionne, mais lentement, et PROCESSOR n’est pas 100% GPU. En général, le modèle et son contexte ne tiennent pas dans la VRAM. Si PROCESSOR renvoie 100% CPU sur une machine équipée d’un GPU, écartez d’abord l’autre cause : Ollama n’a peut-être pas détecté le GPU. La documentation d’Ollama indique que sous Linux, après une mise en veille suivie d’une reprise, le logiciel ne détecte parfois plus un GPU NVIDIA et repasse sur le CPU. Le rechargement du pilote avec sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm permet alors de contourner le problème. Si le GPU est détecté et que la répartition persiste, réduisez la longueur du contexte ou utilisez un modèle plus petit, ou une quantification plus légère. Avant de télécharger à nouveau le modèle, ce que q4_K_M, q8_0 et fp16 consomment chacune en mémoire, et à quel moment la qualité baisse réellement vous indique l’espace libéré par un niveau inférieur et ce que vous perdez en contrepartie.

FAQ

Puis-je connecter Claude Code à Ollama ?

Oui, mais pas avec une URL compatible OpenAI. Claude Code utilise l’API Anthropic Messages, et Ollama expose ce format sur /v1/messages, sur le même port 11434. Exportez ANTHROPIC_BASE_URL=http://localhost:11434 et ANTHROPIC_AUTH_TOKEN=ollama, définissez ANTHROPIC_API_KEY sur une valeur vide, puis démarrez-le avec claude --model qwen3-coder:30b. ollama launch claude applique 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 d’endpoint de comptage des tokens. Les nombres de tokens affichés sont donc approximatifs.

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 à partir de la VRAM totale détectée, après déduction de la surcharge configurée pour chaque GPU : en dessous de 23 GiB, la valeur par défaut est de 4,096 tokens ; de 23 à moins de 47 GiB, elle est de 32,768 tokens ; à partir de 47 GiB, elle est de 262,144 tokens. 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 utiliser pour un agent de programmation sur un VPS ?

Choisissez le plus grand modèle portant le label tools qui tient en mémoire avec une fenêtre de contexte de 64k, et privilégiez un modèle optimisé pour le code. qwen3-coder:30b est le choix courant sur un serveur équipé d’un GPU disposant de suffisamment de VRAM. Si ce modèle est trop volumineux pour votre serveur, les besoins en RAM et les performances en mode CPU uniquement de Nemotron 3.5 Lightning constituent un point de comparaison utile avant de lancer le téléchargement. 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, car le travail d’agent tolère mal les petites erreurs de formatage dans les tool calls. 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 programmation 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 historique volumineux à 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 autre que 100% GPU signifie qu’une partie du modèle s’exécute sur le CPU, et le débit de tokens diminue fortement.