Utilisation d'Ollama avec Claude Code : guide de configuration de modèles locaux

Claude Code est l’agent officiel de programmation en ligne de commande d’Anthropic, qui communique par défaut avec l’API cloud d’Anthropic. Ollama est un moteur d’exécution local de modèles fournissant une API HTTP compatible avec OpenAI. Les deux systèmes n’utilisent pas nativement le même protocole, aussi leur association nécessite-t-elle une couche intermédiaire légère effectuant la traduction entre l’API Messages d’Anthropic et l’API de discussion d’Ollama. Ce guide explique comment cela fonctionne, quels modèles valent la peine d’être exécutés, et où cette configuration atteint ses limites.

Pourquoi Ollama et Claude Code ne se connectent pas directement

Claude Code émet des requêtes au format de l’API Messages d’Anthropic (/v1/messages), comportant des champs spécifiques à Anthropic pour l’utilisation des outils, le contrôle du cache et les invites système. Ollama expose un point de terminaison /api/chat et un point de terminaison compatible avec OpenAI. /v1/chat/completions Aucun des deux ne parle le « dialecte » Anthropic. Pour les relier, un proxy doit :

• Accepter les requêtes au format Anthropic sur un point de terminaison HTTPS.
• Les reformater en demandes de complétion de discussion compatibles avec OpenAI.
• Les transmettre à Ollama, puis traduire les réponses en streaming ainsi que les appels d’outils dans le flux d’événements Anthropic attendu par Claude Code.

Deux projets assurent cette fonctionnalité de façon fiable en 2026 : claude-code-router (routeur dédié à Claude Code, prenant en charge Ollama, OpenRouter et d’autres backends) et LiteLLM (proxy polyvalent doté d’un mode anthropic pass-through). Les deux solutions fonctionnent ; claude-code-router comporte moins de composants si Ollama est votre seul backend.

Prérequis

• Ollama installé et en cours d’exécution. Consultez comment installer Ollama si vous ne l’avez pas encore installé.
• Claude Code installé (npm install -g @anthropic-ai/claude-code).
• Au moins un modèle adapté à la programmation téléchargé localement.
• Node.js 18+ pour claude-code-router, ou Python 3.10+ pour LiteLLM.

Vérifiez que Ollama est joignable :

curl http://localhost:11434/api/tags

Choix d’un modèle local

Claude Code repose fortement sur l’utilisation d’outils, les modifications structurées et le raisonnement sur de longs contextes. Les modèles plus petits destinés aux conversations générales gèrent mal ces tâches. Privilégiez les modèles spécifiquement affinés pour la programmation ou les grands modèles d’instruction.

Modèle (balise Ollama)	Tailles notables	VRAM approximative (quantification Q4)	Remarques
qwen3-coder	30B (MoE A3B), 480B (MoE A35B)	~18 Go (30B) ; la variante 480B est réservée aux serveurs	Ligne de modèles spécialisés dans la programmation développée par l’équipe Qwen ; excellente pour l’utilisation agente des outils.
deepseek-coder-v2	16B, 236B	~10 Go (16B lite)	Performances solides pour les complétions et les refactorisations ; la version 236B est réservée aux serveurs.
llama3.1	8B, 70B	~5 Go / ~40 Go	Modèle général d’instruction ; la version 70B constitue un bon substitut à Claude si vous disposez de suffisamment de VRAM.
qwen2.5-coder	7B, 14B, 32B	~5 / ~9 / ~20 Go	Toujours largement utilisé ; antérieur à qwen3-coder mais très stable.

Le niveau de quantification, la longueur du contexte et la taille du cache KV influencent tous les besoins en VRAM. Utilisez le calculatrice VRAM pour dimensionner une configuration spécifique, et consultez les meilleurs LLM locaux pour Ollama pour une comparaison plus large.

Téléchargez un modèle avant de configurer le proxy :

ollama pull qwen3-coder:30b
ollama pull deepseek-coder-v2:16b

Option 1 : claude-code-router

claude-code-router est la solution la plus directe. Installez-le globalement :

npm install -g @musistudio/claude-code-router

Créez ~/.claude-code-router/config.json:

{
  "Providers": [
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen3-coder:30b", "deepseek-coder-v2:16b"]
    }
  ],
  "Router": {
    "default": "ollama,qwen3-coder:30b",
    "background": "ollama,deepseek-coder-v2:16b"
  }
}

Démarrez Claude Code via le routeur :

ccr code

Le routeur lance un point de terminaison local compatible Anthropic, définit automatiquement les variables d’environnement pour Claude Code et achemine le trafic vers Ollama. Les noms exacts des champs de configuration ont évolué entre versions mineures — consultez le fichier README du projet si une clé est rejetée.

Option 2 : proxy LiteLLM

Si vous exécutez déjà LiteLLM pour d’autres services, réutilisez-le. Créez config.yaml:

model_list:
  - model_name: claude-sonnet-4
    litellm_params:
      model: ollama_chat/qwen3-coder:30b
      api_base: http://localhost:11434
  - model_name: claude-haiku-4
    litellm_params:
      model: ollama_chat/deepseek-coder-v2:16b
      api_base: http://localhost:11434

Exécutez-le :

litellm --config config.yaml --port 4000

Ensuite, redirigez Claude Code vers le proxy (voir la section suivante). LiteLLM gère la traduction Anthropic → Ollama sur la route /anthropic .

Configurer Claude Code pour qu’il utilise le proxy

Claude Code lit deux variables d’environnement pour rediriger son trafic API. Définissez-les dans votre interpréteur de commandes avant d’exécuter claude.

macOS et Linux

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-anything"
claude

Ajoutez-les à ~/.zshrc ou ~/.bashrc pour qu’elles persistent. La valeur de la clé n’est pas utilisée par le proxy local, mais Claude Code refuse de démarrer sans qu’une valeur soit définie.

Windows (PowerShell)

$env:ANTHROPIC_BASE_URL="http://localhost:4000"
$env:ANTHROPIC_API_KEY="sk-anything"
claude

Pour conserver ces paramètres entre les sessions, utilisez [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "http://localhost:4000", "User"). Si Claude Code est installé via WSL, configurez les variables dans l’interpréteur de commandes WSL plutôt que dans Windows — Ollama s’exécutant nativement sous Windows est accessible depuis WSL à l’adresse http://host.docker.internal:11434 ou à l’IP de l’hôte Windows.

Windows (natif, sans WSL)

Claude Code cible officiellement macOS, Linux et WSL. Le support natif de Windows a historiquement été instable ; exécutez-le plutôt sous WSL2, sauf si vous avez vérifié que la version actuelle fonctionne correctement sur votre configuration.

Configuration du contexte et des délais d’attente

Claude Code suppose un contexte de 200 000 jetons et un délai très court avant le premier jeton. Les modèles locaux ne répondent à aucun de ces deux critères. Deux réglages sont essentiels :

• Longueur du contexte dans Ollama. Définissez-la explicitement par modèle via un fichier Modelfile (PARAMETER num_ctx 32768) ou via la variable d’environnement OLLAMA_CONTEXT_LENGTH sur le serveur Ollama. Par défaut, la longueur du contexte est faible et tronquera silencieusement les conversations longues.
• VRAM dédiée au cache KV. Un contexte de 32 K jetons sur un modèle de 30 milliards de paramètres consomme plusieurs gigaoctets de VRAM uniquement pour le cache KV. Vérifiez la consommation mémoire totale avec ollama ps.

Pour une analyse complète des besoins mémoire à différentes longueurs de contexte, consultez Exigences en VRAM selon le modèle.

Limitations connues

• L’utilisation des outils est fragile. Les outils intégrés de Claude Code (modification de fichiers, exécution de commandes bash, recherche) reposent sur une sortie JSON stricte pour les appels d’outils. Les modèles locaux échouent plus fréquemment à ce niveau, produisant des appels mal formés ou « hallucinant » le contenu des fichiers. qwen3-coder et deepseek-coder-v2 comptent parmi les modèles les plus fiables, mais aucun ne rivalise avec Claude Sonnet.
• La mise en cache des prompts est inefficace. d’Anthropic Les champs sont ignorés par le proxy. Les prompts système longs sont renvoyés à chaque tour.
• Vitesse. Même sur un GPU de 24 Go, un modèle de 30 milliards de paramètres avec un contexte de 32 K génère 15 à 40 jetons/seconde. La boucle agente de Claude Code effectue de nombreux appels par tâche, ce qui peut rallonger le temps réel d’un facteur 5 à 10 par rapport à l’API cloud.
• Sous-agents et MCP. Les fonctionnalités avancées de Claude Code (agents en arrière-plan, serveurs MCP) fonctionnent généralement toujours, car elles passent toutes par le même proxy ; toutefois, toute fonctionnalité dépendant d’un comportement spécifique du serveur Anthropic peut échouer silencieusement.

Quand utiliser cette configuration plutôt que l’API cloud

Utiliser Claude Code localement est pertinent lorsque : le code ne doit pas quitter votre réseau, vous êtes soumis à un forfait API limité et effectuez des refactorisations massives, ou vous expérimentez l’auto-hébergement. En revanche, cela l’est moins pour une utilisation quotidienne en programmation agente, où la capacité de raisonnement de classe Claude Sonnet constitue précisément l’objectif.

Pour décider de façon quantitative, comparez les coûts des deux approches. L’ Calculateur de coûts d’API estime la dépense mensuelle auprès d’Anthropic, tandis que le Calculatrice du seuil de rentabilité auto-hébergement vs API la compare au coût amorti du GPU. Pour la plupart des développeurs indépendants, l’API reste la solution la plus avantageuse ; pour les équipes sollicitant fortement l’API, un serveur local partagé peut s’amortir en moins d’un an. Si vous dimensionnez ce serveur, le meilleurs GPUs pour les LLMs locaux guide couvre la gamme actuelle.

Solutions alternatives à Ollama pour ce flux de travail

Si les performances d’Ollama constituent un goulot d’étranglement, d’autres moteurs compatibles avec l’API OpenAI fonctionnent de façon identique derrière le même proxy : LM StudiovLLM et le serveur de llama.cpp conviennent tous deux. Consultez le guide LM Studio pour une option axée sur l’interface graphique, ou le Guide complet Ollama pour une analyse approfondie d’Ollama lui-même.

Questions fréquemment posées

Claude Code peut-il utiliser Ollama sans proxy ?

Non. Claude Code utilise l’API Messages d’Anthropic, que Ollama n’implémente pas. Vous avez besoin d’une couche de traduction telle que claude-code-router ou LiteLLM. La configuration ANTHROPIC_BASE_URL directement sur http://localhost:11434 échouera dès la première requête.

Quel modèle local se rapproche le plus de Claude Sonnet pour la programmation ?

Aux tailles que la plupart des utilisateurs peuvent réellement exécuter, qwen3-coder (30B MoE) et deepseek-coder-v2 (16B lite) sont actuellement les meilleurs choix. Aucun des deux ne rivalise avec Sonnet sur les tâches agenty multi-fichiers, mais tous deux conviennent aux éditions mono-fichier, aux complétions et à l’analyse de code. Comparez leurs scores d’intelligence sur le Classement des grands modèles linguistiques (LLM).

La mise en cache des prompts fonctionne-t-elle avec Ollama derrière Claude Code ?

Non. La mise en cache des prompts d’Anthropic est une fonctionnalité côté serveur propre à leur API. Les proxies suppriment ou ignorent les champs Les champs ; ainsi, chaque requête traite à nouveau intégralement le prompt système et l’historique de la conversation. C’est l’une des raisons pour lesquelles les configurations locales semblent plus lentes par tour que l’API cloud, même avec un débit brut de jetons comparable.

De combien de VRAM ai-je besoin pour une expérience satisfaisante ?

Une seule carte graphique de 24 Go (classe RTX 3090/4090/5090) permet d’exécuter un modèle codeur de 30B en quantification Q4 avec environ 32K de contexte. Pour les modèles de classe 70B ou des contextes plus longs, prévoyez au moins 48 Go (RTX 6000 Ada ou deux RTX 3090) ou davantage. Utilisez le calculatrice VRAM pour obtenir les chiffres exacts par modèle et par niveau de quantification.

Puis-je mélanger des modèles locaux et des modèles cloud dans une même session Claude Code ?

Oui, via un routeur. claude-code-router vous permet d’assigner différents modèles à différents rôles — par exemple, Sonnet en cloud pour l’agent principal, et un modèle local pour les tâches secondaires ou les complétions. Cela peut réduire considérablement les coûts liés à l’API tout en maintenant une haute qualité sur le chemin critique.

Existe-t-il une méthode officiellement prise en charge par Anthropic pour exécuter Claude Code localement ?

Non. Anthropic distribue Claude Code sous forme de client pour leur API et ne diffuse pas les poids de Claude. Toutes les configurations locales reposent sur des proxies communautaires pointant vers des modèles tiers. Si Anthropic modifie l’API Messages, ces proxies devront probablement être mis à jour avant que Claude Code puisse à nouveau fonctionner avec eux.