Faire tourner Claude Code en local avec Ollama

Pourquoi faire tourner Claude Code en local

Claude Code parle à un modèle à travers une API. Par défaut, ce modèle est Claude, chez Anthropic : chaque fichier que l’agent lit part dans la requête. Pointe-le vers Ollama et le modèle tourne sur ta machine. Les requêtes vont vers localhost, pas vers internet.

Ce que tu gagnes

• La confidentialité. Code client, code sous NDA, fichiers de config avec des secrets : rien ne part chez un fournisseur d’IA.
• Le coût. Pas de facture au token. Tu paies la machine et l’électricité.
• L’autonomie. Une fois le modèle téléchargé, l’inférence n’a plus besoin d’internet.

Ce que tu perds

Soyons clairs : un modèle de 9 milliards de paramètres qui tient sur un Mac n’est pas Claude. Il comprend une consigne nette et sait appeler les outils de Claude Code, mais il raisonne moins loin, se trompe plus souvent et prend des raccourcis. Il est aussi plus lent : sur notre Mac mini, la première réponse d’une session arrive après une minute et demie à trois minutes environ.

Autre point à connaître : Anthropic indique dans sa documentation ne pas prendre en charge Claude Code branché sur des modèles qui ne sont pas Claude. Ça fonctionne, c’est Ollama qui documente l’intégration, mais en cas de souci c’est de son côté qu’il faut chercher.

Ce qu’il te faut

Un Mac Apple Silicon (M1 ou plus récent), Claude Code installé, et de la mémoire. Sur ces Mac, la mémoire est unifiée : le GPU puise dans la RAM, mais Ollama ne peut pas tout prendre. Sur notre Mac mini M4 de 24 Go, ses logs de démarrage annoncent 17,8 Gio de mémoire GPU disponible.

Le modèle de ce guide, qwen3.5 en version 9B, occupe 7,9 Go une fois chargé avec 64 000 tokens de contexte (mesuré avec ollama ps). Ce qui donne, en ordre de grandeur :

Installer et lancer Ollama

Avec Homebrew, une commande installe Ollama. Une deuxième lance le serveur, avec un contexte assez grand pour Claude Code.

$ brew install ollama
$ OLLAMA_CONTEXT_LENGTH=64000 ollama serve

ollama serve écoute sur http://localhost:11434 et reste au premier plan : laisse ce terminal ouvert et ouvre-en un autre pour la suite. Si tu préfères l’app Ollama pour Mac, le contexte se règle avec le curseur de ses réglages.

Choisir et télécharger un modèle

$ ollama pull qwen3.5
$ ollama show qwen3.5

qwen3.5 est le modèle local pris en exemple sur la page Claude Code de la doc Ollama. Le tag par défaut est la version 9B quantifiée en Q4_K_M : 6,6 Go à télécharger. ollama show liste ses capacités : tools, thinking, vision, et un contexte maximal de 262 144 tokens.

L’appel d’outils n’est pas une option

Claude Code ne fait rien sans outils : lire un fichier, l’écrire, lancer une commande, tout passe par des appels d’outils. Un modèle qui n’affiche pas tools dans ollama show ne pourra que discuter. Vérifie avant de télécharger.

La page de compatibilité Anthropic d’Ollama cite aussi qwen3-coder pour le code et gpt-oss:20b comme modèle généraliste. Nous ne les avons pas testés : regarde leur taille sur ollama.com avant de les tirer.

Brancher Claude Code sur Ollama

Ollama expose une API compatible avec celle d’Anthropic. Il suffit de dire à Claude Code de l’utiliser, avec trois variables d’environnement, plus une quatrième pour le contexte.

$ export ANTHROPIC_BASE_URL=http://localhost:11434
$ export ANTHROPIC_AUTH_TOKEN=ollama
$ export ANTHROPIC_API_KEY=""
$ export CLAUDE_CODE_MAX_CONTEXT_TOKENS=64000
$ claude --model qwen3.5

• ANTHROPIC_BASE_URL envoie les requêtes vers Ollama au lieu d’Anthropic.
• ANTHROPIC_AUTH_TOKEN doit exister. La doc Ollama y met simplement ollama. Tant qu’il est défini, Claude Code l’utilise à la place de ton compte claude.ai.
• ANTHROPIC_API_KEY="" neutralise une clé Anthropic qui traînerait dans ton environnement.
• CLAUDE_CODE_MAX_CONTEXT_TOKENS donne la vraie taille du contexte. Claude Code ne connaît pas qwen3.5 : sans cette variable, il affiche un avertissement et suppose 200 000 tokens. Avec elle, l’avertissement disparaît et la compaction automatique se cale sur les 64 000 du serveur.

Pour vérifier, tape /status dans Claude Code : une ligne Anthropic base URL doit afficher http://localhost:11434.

Le raccourci : ollama launch

$ ollama launch claude --model qwen3.5

Ollama sait lancer Claude Code déjà branché, sans exports. On l’a testé en mode non interactif (ollama launch claude --model qwen3.5 --yes -- -p "…") : ça marche, et la commande ne touche pas aux réglages de Claude Code. Elle note seulement le modèle choisi dans ~/.ollama/config.json. Deux limites : elle ne règle pas le contexte du serveur, donc OLLAMA_CONTEXT_LENGTH reste nécessaire, et elle ne pose pas CLAUDE_CODE_MAX_CONTEXT_TOKENS, donc l’avertissement de Claude Code revient.

Une première tâche, chronomètre en main

Dans un dossier jetable, on a donné une consigne volontairement simple, en mode non interactif. Les deux options autorisent l’écriture de fichiers et la commande python3 sans demander de permission.

$ mkdir /tmp/essai && cd /tmp/essai
$ claude -p "Utilise l'outil Write pour créer le fichier hello.py contenant print('Bonjour depuis Ollama'). Ensuite lance python3 hello.py." --model qwen3.5 --permission-mode acceptEdits --allowedTools "Bash(python3:*)"

Résultat : hello.py est créé avec le bon contenu, le script tourne, la réponse tient en une ligne. Les appels d’outils fonctionnent.

Avec une consigne plus vague (« crée un fichier hello.py qui affiche… puis exécute-le »), le modèle a pris un raccourci : il a lancé python3 -c directement, sans créer le fichier, et l’a signalé après coup. La leçon : avec un petit modèle, sois explicite et découpe les tâches.

Ce que ça coûte en temps

Voici nos mesures sur le Mac mini M4 de 24 Go, lues dans les logs d’Ollama. Ce ne sont pas des benchmarks, juste ce qu’on a observé :

• Première requête d’une session : Claude Code envoie son prompt système et la définition de ses outils. Environ 29 500 tokens avec notre configuration habituelle (plugins, skills), 17 000 avec une configuration vierge. Le Mac les traite à environ 180 tokens par seconde : entre 1 min 30 et un peu plus de 3 min avant le premier mot.
• Échanges suivants dans la même session : seul le nouveau texte est traité. Quelques secondes.
• Génération : environ 14 tokens par seconde.

Conclusion pratique : ouvre une session interactive et garde-la, plutôt que d’enchaîner des claude -p qui repaient chacun le prix de départ.

Les pièges à connaître

Le contexte par défaut est trop petit

C’est le piège numéro un, détaillé plus haut. Le symptôme : des réponses sans rapport avec ta demande. Vérifie avec ollama ps : la colonne CONTEXT doit afficher 64000.

Un modèle trop gros pour ta mémoire

Toujours dans ollama ps, la colonne PROCESSOR doit afficher 100% GPU. Sinon, une partie du modèle tourne sur le CPU et tout ralentit. Plus de contexte veut aussi dire plus de mémoire : si ça déborde, prends un modèle plus petit avant de rogner le contexte sous 64 000.

Le premier mot se fait attendre

Une minute et demie à trois minutes de silence au démarrage d’une session, c’est normal (voir les mesures). Claude Code abandonne une requête après 10 minutes : sur une machine plus lente, API_TIMEOUT_MS repousse cette limite, en millisecondes.

Tes réglages Claude Code passent avant ton shell

Si ~/.claude/settings.json contient déjà un bloc env avec ANTHROPIC_BASE_URL, sa valeur l’emporte sur tes export. /status te dit quelle adresse est réellement utilisée.

Oublier de revenir à Claude dans le cloud

Les export restent actifs jusqu’à la fermeture du terminal. Tant qu’ils sont là, chaque claude lancé depuis ce terminal part sur Ollama. Pour revenir à ton compte claude.ai :

$ unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY CLAUDE_CODE_MAX_CONTEXT_TOKENS

Plus simple : ne fais pas d’export et préfixe la commande. Les variables ne valent alors que pour cette session.

$ ANTHROPIC_BASE_URL=http://localhost:11434 ANTHROPIC_AUTH_TOKEN=ollama ANTHROPIC_API_KEY="" CLAUDE_CODE_MAX_CONTEXT_TOKENS=64000 claude --model qwen3.5

La télémétrie, elle, sort encore

Les requêtes au modèle, celles qui contiennent ton code, vont vers Ollama. Mais d’après la doc de Claude Code, l’outil continue d’envoyer de la télémétrie et des vérifications de version à Anthropic. Pour couper ce trafic, ajoute CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1. Ça désactive aussi les mises à jour automatiques : pense à mettre Claude Code à jour toi-même.

Local pour le sensible, cloud pour le reste

Tu n’as pas à choisir une fois pour toutes. Un modèle local de 9B suffit pour des tâches cadrées sur du code confidentiel : écrire un test, renommer, expliquer un fichier. Pour une refonte qui touche vingt fichiers, Claude dans le cloud va plus loin. Deux alias dans ton ~/.zshrc et tu choisis tâche par tâche :

# Claude dans le cloud : la commande habituelle
# claude
 
# Le même agent, sur le modèle local
alias claude-local='ANTHROPIC_BASE_URL=http://localhost:11434 ANTHROPIC_AUTH_TOKEN=ollama ANTHROPIC_API_KEY="" CLAUDE_CODE_MAX_CONTEXT_TOKENS=64000 claude --model qwen3.5'

Envie de plusieurs agents locaux en parallèle, chacun dans son dossier ? Le guide git worktree montre comment isoler les tâches. Avec une réserve : dans sa configuration par défaut, Ollama traite une requête à la fois (OLLAMA_NUM_PARALLEL vaut 1 dans ses logs). Deux agents sur le même modèle font la queue.

Ton code reste chez toi.
Ton agent, lui, ne dort pas.

Brancher Claude Code sur Ollama règle la question du modèle. Restent la machine à garder allumée, le choix local ou cloud à faire tâche par tâche, et la garantie que rien ne sort par erreur. Vision Island tourne 24/7 sur un Mac mini, avec un LLM local ou hybride, et son Privacy Gateway bloque ou redirige vers le modèle local ce qui ne doit pas sortir.