Utiliser Ollama avec votre agent de code

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 attend 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êtes. /v1/chat/completions correspond au format compatible avec OpenAI. La documentation d’Ollama indique que la clé y est obligatoire, mais qu’elle est ignorée. /v1/messages correspond au 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 aussi du type de tâches confiées au modèle. Ces deux paramètres font chacun l’objet d’une section. Les limites réelles sont présentées à la fin.

Quels agents de code acceptent une URL de base locale

Le test tient en une question : l’outil permet-il de configurer une 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 que l’on désigne par agent de code 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. Fournissez-leur l’URL de base http://localhost:11434/v1 et n’importe quelle chaîne non vide comme clé d’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, où Ollama expose /v1/messages.
• Codex utilise l’API OpenAI Responses. Ollama expose également /v1/responses, ajoutée dans la version 0.13.3.
• Un agent qui ne permet pas de configurer une 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 requis 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 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 cause.

Le modèle doit prendre en charge les appels 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 toutes lettres 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 télécharger. qwen3-coder:30b le possède. En août 2026, ce tag correspond à un téléchargement de 19 GB avec une fenêtre de contexte de 256K. Si votre machine utilise uniquement le CPU ou manque de RAM, le calcul de la mémoire nécessaire 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 téléchargé, ces gigaoctets occupent 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 la manière de les déplacer ailleurs 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 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 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.

Dirigez 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 sur 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 tous ces paramètres à votre place.

Vous devez connaître les éléments 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 calculées à partir du tokenizer du modèle. Claude Code fournit également un prompt système volumineux et un ensemble d’outils étendu. Il nécessite donc davantage de contexte qu’un client de chat. La question plus générale de ce qui est transposable 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 peut utiliser. 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, se trouvent sur la première ligne : 4,096 tokens. Seul un GPU puissant permet d’atteindre les 262,144 tokens de la dernière ligne.

Un agent consomme déjà 4096 tokens avant 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 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 alors 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 serait 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 de cache KV selon chaque taille mérite d’être lu avant de choisir une valeur.

La documentation d’Ollama indique que les tâches utilisant des agents ou des outils de programmation doivent être configurées avec au moins 64000 tokens. Configurez 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 est le contrôle à effectuer. Cette commande affiche une colonne CONTEXT, dont la 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 de contexte. Un client compatible avec OpenAI ne peut donc pas en demander une. De plus, ce paramètre est propre au serveur. Tous les agents auxquels vous connectez cette machine en héritent. La sortie possède sa propre limite. Contrairement à la longueur de contexte, elle est transmise par l’endpoint de compatibilité. Utilisez donc num_predict et le champ max_tokens qui lui correspond lorsqu’une réponse s’arrête au milieu d’un patch. Si un modèle nécessite 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 déplacée vers le CPU, le débit de tokens diminue 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 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 interrompez votre travail pour lire un diff, le délai expire, puis la requête suivante recharge plusieurs dizaines de gigaoctets de poids depuis le disque avant l’affichage du premier token. Cela ressemble à un blocage.

OLLAMA_KEEP_ALIVE accepte une durée telle que 10m ou 24h, un nombre de secondes simple, -1 pour conserver le modèle chargé indéfiniment, 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 avez besoin de 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 maintien des poids en mémoire toute la journée à 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 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 la liaison sur localhost et redirigez 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 pas la 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, le scheduler d’Ollama n’est pas conçu pour cette charge. la comparaison entre Ollama et vLLM montre à partir de quel niveau la différence de débit devient problématique.

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 d’échec et chaînes affichées

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. Le serveur n’est pas en cours d’exécution 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 pas à un nom fourni par le serveur. Comparez-le à curl http://localhost:11434/v1/models et copiez la chaîne affichée à cet endroit. Le tag fait partie du nom. Une configuration qui mentionne 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 tools, soit la requête et leurs définitions occupent déjà toute la context window. 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 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é appliquée à 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. Avant de télécharger de nouveau le modèle, ce que q4_K_M, q8_0 et fp16 coûtent chacun en mémoire, et où la qualité baisse réellement vous indique l’espace gagné en descendant d’un niveau et les compromis associés.

FAQ

Puis-je connecter Claude Code à Ollama ?

Oui, mais pas avec une URL compatible avec 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, puis définissez ANTHROPIC_API_KEY sur une valeur vide avant de le démarrer 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 de point d’accès pour compter les tokens. Les nombres de tokens indiqués sont donc approximatifs.

Pourquoi mon modèle local répond-il au sujet d’un code auquel il n’a pas accès ?

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 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 programmation 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 privilégiez 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. Si ce tag est trop volumineux pour votre serveur, les besoins en RAM et les vitesses en mode CPU uniquement de Nemotron 3.5 Lightning constituent une comparaison utile avant de lancer le téléchargement. En dessous d’environ 14B paramètres, un modèle peut encore répondre correctement à des questions sur le code tout en échouant lors de modifications en plusieurs étapes. Le travail d’agent tolère mal 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 programmation sur mon propre modèle ?

En pratique, oui. L’inférence avec le CPU uniquement 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 ainsi une tâche de deux minutes en une 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, ce qui réduit fortement le débit de tokens.