À retenir
- Ollama v0.14.0 minimum requis — la commande
ollama launch claudeconfigure automatiquement les 3 variables d'environnement en une seule ligne - num_ctx est le réglage qui fait tout échouer — la valeur par défaut du Modelfile de référence (2048 tokens) est catastrophiquement insuffisante ; réglez-la à 65 536 avec un Modelfile
- Modèles recommandés en 2026 — qwen3-coder et GLM-4.7-Flash ont la meilleure compatibilité avec le tool use de Claude Code
- Zéro frais d'API, mais pas "gratuit" — comptez l'électricité (environ 4 €/mois) et évaluez honnêtement si votre matériel suffit avant de vous lancer
Un développeur freelance passe 40 €/mois en API Claude pour des tâches de refactoring routinières. Il installe Ollama, lance qwen3-coder en local, et ramène cette ligne de coût à 0 — sans changer son workflow Claude Code d'une ligne. C'est le scénario que permet l'intégration native Ollama × Claude Code depuis janvier 2026. Mais entre la promesse et la réalité, il y a un réglage que personne ne documente correctement — et qui fait planter la plupart des installations.
Ce guide couvre la configuration pas à pas, le choix du bon modèle selon votre matériel, les erreurs courantes et leur résolution, et une réponse honnête à la question : « est-ce vraiment rentable pour moi ? » Si vous cherchez d'abord une prise en main complète de Claude Code avant d'aller plus loin, notre guide de référence couvre les fondamentaux de l'outil.
La configuration en 4 étapes
Avant tout : vérifiez votre version d'Ollama. L'intégration native avec Claude Code nécessite Ollama v0.14.0 ou supérieure — publiée en janvier 2026, elle a introduit le support de l'API Anthropic Messages (/v1/messages), permettant à Claude Code de communiquer avec des modèles open-source en local (documentation officielle Ollama).
ollama --version
# doit afficher 0.14.0 ou supérieur
Installer Ollama
Téléchargez Ollama depuis ollama.com. Sur macOS, l'installation prend moins d'une minute ; sur Windows, récupérez OllamaSetup.exe et ajoutez manuellement C:\Users\VOTRE_NOM\.local\bin au PATH système après installation (Propriétés système → Variables d'environnement → PATH utilisateur).
Télécharger un modèle compatible
Lancez votre premier modèle. qwen3-coder est le plus fiable pour le tool use de Claude Code en 2026 :
ollama pull qwen3-coder
Si votre machine a moins de 10 Go de VRAM disponible, préférez GLM-4.7-Flash (~9 Go).
Configurer la fenêtre de contexte (étape critique)
Créez un Modelfile pour étendre num_ctx — sans cette étape, Claude Code recevra des contextes tronqués en silence :
cat > Modelfile << 'EOF'
FROM qwen3-coder
PARAMETER num_ctx 65536
EOF
ollama create qwen3-coder-64k -f Modelfile
Vérifiez : ollama show qwen3-coder-64k doit afficher num_ctx: 65536.
Connecter Claude Code à Ollama
La méthode recommandée utilise la commande unifiée d'Ollama, qui configure automatiquement les variables d'environnement :
ollama launch claude
Si vous préférez le contrôle manuel, exportez ces trois variables avant de lancer Claude Code :
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder-64k
ANTHROPIC_AUTH_TOKEN=ollama et ANTHROPIC_API_KEY="" ? Ollama ne nécessite pas d'authentification locale. La valeur fictive ollama satisfait le format attendu par Claude Code, et la clé vide empêche l'utilisation accidentelle d'une vraie clé API Anthropic. (Medium — Pulak Bararia, fév. 2026)Le num_ctx : le réglage que personne n'explique vraiment
La valeur par défaut de num_ctx dans le Modelfile de référence Ollama est 2048 tokens — catastrophiquement insuffisante pour Claude Code, qui envoie des contextes de projet entiers à l'IA. Les versions récentes d'Ollama utilisent un défaut dynamique selon la VRAM disponible (4 096, 32 768 ou 262 144 tokens selon la mémoire GPU), mais même ce défaut dynamique peut être insuffisant pour des repositions de code complexes (documentation Modelfile Ollama).
Le problème aggravant : Ollama tronque le contexte en silence sans avertissement. Vous ne verrez pas d'erreur ; votre modèle répondra simplement avec une vision partielle du code. Ce comportement a été qualifié de « harsh foot-gun » par les mainteneurs d'Aider sur Hacker News (discussion #42833427).
Claude Code gère mieux les repositions de code avec un contexte large — visez au minimum 16 000 à 32 000 tokens, et idéalement 65 536 pour les projets conséquents. Une exception notable : GLM-4.7-Flash, pour lequel DataCamp recommande de rester autour de 20 000 tokens (DataCamp, fév. 2026) — des contextes très grands peuvent faire chuter le débit du modèle de plus de 100 tokens/s à environ 2 tokens/s.
💡 Bon à savoir : L'augmentation de
num_ctxa un coût mémoire direct. Pour un modèle 8B, chaque doublement du contexte ajoute environ 1 à 2 Go de VRAM. Activez Flash Attention pour réduire cette empreinte sans perte de qualité (FAQ Ollama) :export OLLAMA_FLASH_ATTENTION=1. Pour aller plus loin, activez aussi la quantification du cache KV avecexport OLLAMA_KV_CACHE_TYPE=q8_0— ces deux features sont complémentaires mais distinctes (voir section ci-dessous).
export OLLAMA_FLASH_ATTENTION=1
export OLLAMA_KV_CACHE_TYPE=q8_0
Choisir son modèle selon son matériel
Les modèles ne se valent pas pour le tool use multi-étapes de Claude Code. Les issues GitHub actives (#15390, #16094) documentent des incompatibilités réelles avec certains modèles non spécialisés — notamment des échecs de formatage JSON des tool calls avec certains modèles (comme gemma4) dans Claude Code + Ollama, liés au schéma d'outils attendu.
Voici les modèles testés et leur bilan en 2026 :
Le bon modèle dépend avant tout de votre RAM ou VRAM disponible. Apple Silicon bénéficie d'une architecture à mémoire unifiée (UMA) — le CPU et le GPU partagent le même pool mémoire — ce qui élimine la contrainte VRAM des GPU discrets et en fait une excellente plateforme pour le LLM local (SitePoint, mars 2026).
8 Go de RAM unifiée (M1 base)
16 Go de RAM unifiée (M2/M3)
32 Go de RAM unifiée (M2/M3 Pro)
48+ Go VRAM (GPU dédié)
Configuration Windows : les pièges spécifiques
Claude Code supporte nativement Windows depuis fin 2025. En PowerShell, la syntaxe des variables d'environnement est différente de Bash — c'est une source d'erreur fréquente (Towards Data Science, jan. 2026) :
# PowerShell — syntaxe CORRECTE
$env:ANTHROPIC_AUTH_TOKEN = "ollama"
$env:ANTHROPIC_API_KEY = ""
$env:ANTHROPIC_BASE_URL = "http://localhost:11434"
claude --model qwen3-coder-64k
Deux gotchas Windows à mémoriser : le PATH n'est pas mis à jour automatiquement après installation de Claude Code — ajoutez manuellement C:\Users\VOTRE_NOM\.local\bin. Et si vous utilisez WSL2 avec un GPU NVIDIA, Ollama doit tourner dans WSL, pas en natif Windows — sinon Claude Code reçoit une erreur Connection Refused.
💡 Bon à savoir : Sur WSL2, exposez Ollama à Claude Code via
ANTHROPIC_BASE_URL=http://localhost:11434depuis l'intérieur du sous-système Linux. Si Ollama tourne en Windows natif, remplacezlocalhostpar l'IP de l'hôte WSL (généralement172.x.x.x, récupérable aveccat /etc/resolv.conf).
Troubleshooting : les 8 erreurs les plus fréquentes
Issues GitHub actives (Ollama #13949, #15390, #16094) et retours communautaires convergent sur les mêmes blocages.
Découvrez nos formations IA
Local vs cloud : une comparaison honnête
L'argument « gratuit » mérite une nuance. Zéro frais d'API, oui — mais pas zéro coût.
Un laptop existant avec au moins 16 Go de RAM coûte environ 4 €/mois en électricité supplémentaire pour faire tourner Ollama 8 heures par jour. C'est le seul cas où l'économie est immédiate et réelle. Pour tout achat de matériel dédié, le calcul change : la différence de prix entre un MacBook Pro M3 standard (environ 1 999 €) et un M3 Max 36 Go entrée de gamme (environ 3 499 €) avoisine 1 500 €, soit environ 42 €/mois amorti sur 3 ans — seuil de rentabilité atteint seulement si vos dépenses API actuelles dépassent ce montant (ArtisanDev.fr, PowerLab.fr).
Il y a aussi un coût d'opportunité souvent ignoré. Si un modèle local 14B prend 15 secondes là où Claude Sonnet prend 3 secondes, vous perdez 12 secondes par échange. À 60 échanges de coding par jour, c'est 12 minutes perdues — soit environ 130 heures par an pour un développeur senior, une valeur supérieure à de nombreux abonnements cloud.
💡 Bon à savoir : Si vos dépenses API dépassent régulièrement 50 $/mois (environ 45 €) avec des données sensibles, le local devient stratégiquement pertinent — c'est un seuil de pertinence, pas une règle absolue. En dessous, l'API cloud reste souvent plus économique compte tenu de la qualité des modèles : les meilleurs modèles open-weights atteignent 70 à 77 % au SWE-bench Verified (Kimi K2.5, GLM-5, DeepSeek V3.2) contre 75 à 80 % pour les meilleurs modèles Claude cloud — un écart aujourd'hui réduit à quelques points, mais réel sur les tâches de débogage complexes (swebench.com, août 2026).
Pour aller plus loin sur les workflows hybrides local/cloud dans un contexte professionnel, consultez notre guide complet de Claude Code pour les débutants ou notre comparatif Claude Code vs Cursor. Et si vous souhaitez structurer votre apprentissage, notre formation Claude Code couvre l'ensemble des fonctionnalités avancées avec des cas pratiques.
Flash Attention et cache KV : deux features distinctes
Un point souvent confondu dans les tutoriels : Flash Attention et la quantification du cache KV sont deux optimisations mémoire séparées, complémentaires mais indépendantes.
Flash Attention (OLLAMA_FLASH_ATTENTION=1) réduit la complexité mémoire de l'attention de O(N²) à O(N) linéaire en longueur de séquence — ce qui permet de tenir des contextes longs sans explosion mémoire quadratique. C'est le prérequis pour activer la quantification KV.
La quantification du cache KV (OLLAMA_KV_CACHE_TYPE=q8_0 ou q4_0) réduit l'empreinte mémoire du cache KV par compression numérique : q8_0 divise la taille du cache par environ 2 (par rapport au f16 par défaut), q4_0 par environ 4. Ces réductions de 50 à 75 % s'appliquent au cache KV, pas à la mémoire du modèle en lui-même (FAQ Ollama).
# Activer les deux (recommandé pour les contextes longs)
export OLLAMA_FLASH_ATTENTION=1
export OLLAMA_KV_CACHE_TYPE=q8_0
Sources et références
- Documentation officielle Ollama — Claude Code Integration (2026) — configuration des variables d'environnement et liste des capabilities
- Documentation Ollama — Modelfile — référence num_ctx et paramètres
- GitHub Ollama #13949 (jan. 2026) — issue compatibilité API Ollama / Claude Code
- GitHub Ollama #15390 (avr. 2026) — tool use invalide et CPU fallback
- DataCamp — Utilisation de Claude Code avec Ollama (fév. 2026) — recommandation num_ctx 20k pour GLM-4.7-Flash
- Hacker News #42833427 — discussion sur la troncature silencieuse du contexte Ollama
- LocalLLM.in — VRAM Requirements 2026 — benchmarks VRAM par taille de modèle et contexte
- ArtisanDev.fr — LLM local vs API — analyse de rentabilité par profil d'usage
- SWE-bench leaderboard officiel — classement des modèles sur les tâches de débogage GitHub réels
FAQ
Quelle version d'Ollama faut-il pour utiliser Claude Code ?
Ollama version 0.14.0 minimum, publiée en janvier 2026. Vérifiez avec ollama --version. C'est cette version qui a introduit le support de l'API Anthropic Messages (/v1/messages) — en dessous de cette version, Claude Code ne peut pas se connecter au serveur local.
Claude Code avec Ollama fonctionne-t-il sans GPU dédié ?
Oui, mais avec des performances sensiblement réduites. Sur CPU seul (Intel i7 12e génération), le débit observé est de 5 à 10 tokens par seconde pour un modèle 7B — soit des réponses de 30 à 120 secondes pour des tâches complexes. C'est acceptable pour des sessions de coding non-interactives (génération de code en batch), pénalisant pour un dialogue agentique fluide. Sur Apple Silicon, la mémoire unifiée GPU/CPU offre des performances intermédiaires très satisfaisantes sans GPU discret.
Pourquoi le tool use de Claude Code échoue avec certains modèles Ollama ?
Claude Code envoie des définitions de tools complexes (format JSON Anthropic) que les modèles généralistes non spécialisés interprètent mal. L'issue GitHub #15390 documente des échecs de formatage JSON du tool-call avec certains modèles (notamment gemma4) dans Claude Code + Ollama, liés au schéma d'outils attendu. La solution est de choisir des modèles entraînés spécifiquement sur du tool use et du code : qwen3-coder et GLM-4.7-Flash ont en 2026 la meilleure réputation de compatibilité.
Comment passer facilement entre le modèle local et Claude cloud selon les tâches ?
Créez deux alias dans votre .bashrc ou .zshrc : l'un qui exporte les variables Ollama avant de lancer Claude Code, l'autre qui les désactive pour revenir à l'API Anthropic. Une variante populaire dans la communauté utilise claude-local pour Ollama (tâches simples, données confidentielles) et claude nu pour l'API cloud (tâches complexes, projets critiques). La formation Code with AI de The Intelligence Academy couvre ces workflows hybrides dans le contexte d'un pipeline professionnel.
Quelle configuration matérielle recommandez-vous pour démarrer ?
Le point d'entrée le plus rationnel en 2026 est un Mac avec 16 Go de RAM unifiée (M2 ou M3, configuration standard). Vous pouvez faire tourner qwen3-coder 7B confortablement à 20-26 tokens/seconde, avec un contexte de 16 à 32k tokens — suffisant pour la plupart des tâches Claude Code courantes. En dessous, expérimentez d'abord avec votre matériel existant avant tout achat ; au-dessus, un M3 Pro 36 Go ouvre la porte aux modèles 30B pour les projets complexes.
Pourquoi Ollama devient-il parfois non-réactif avec Claude Code ?
Ollama peut devenir non-réactif lorsque Claude Code envoie des requêtes vers des endpoints non supportés (comme /v1/messages/count_tokens?beta=true). Ces requêtes déclenchent un comportement inattendu côté serveur Ollama, nécessitant un redémarrage manuel du service. Ce bug est documenté dans l'issue GitHub #13949 (jan. 2026).