Utiliser un modèle local dans Claude Code avec Ollama, puis revenir au cloud

Claude Code peut appeler un modèle local via l’API compatible Anthropic d’Ollama, mais une réponse correcte dans le chat ne prouve pas que le modèle est prêt pour un agent de développement. Avant de lui confier un vrai projet, vérifiez trois conditions : prise en charge des appels d’outils, capacité de la machine à maintenir au moins 64k de contexte, et tâche assez délimitée pour être contrôlée par des commandes et un diff.

Ce guide conserve un chemin de retour. Vous allez connecter Claude Code à qwen3.5 par la méthode officielle d’Ollama, exécuter un test d’acceptation sur un seul fichier, vérifier si l’inférence se déroule réellement en local, examiner les limites de l’API et des données, puis supprimer la redirection locale avant de revenir à un endpoint cloud. Les commandes utilisent Bash sous macOS, Linux ou WSL. Ce sont des procédures à exécuter vous-même, pas des résultats prétendument obtenus sur votre matériel.

Décider d’abord : local, cloud ou fonctionnement hybride

Un modèle local est surtout utile pour une tâche bornée dont le résultat se vérifie mécaniquement. Un grand dépôt, une migration entre services ou une investigation complexe tirent généralement davantage parti d’un modèle cloud que d’un petit modèle local fortement déchargé sur le CPU.

Charge de travail	Point de départ conseillé	Pourquoi
Correction d’un fichier, ajout d’un test ou explication d’une fonction locale	Essayer d’abord en local	Le contexte est borné et le résultat se contrôle par commande et diff
Petit ou moyen module aux dépendances claires	Local ou hybride	Passez le smoke test, puis élargissez progressivement le périmètre
Grand monorepo, refactorisation interservices ou diagnostic complexe	Cloud d’abord	Ces tâches demandent plus de contexte effectif et une planification d’outils plus fiable
Le modèle ne maintient pas 64k sans fort offload CPU	Cloud d’abord	La latence et les blocages annulent une grande partie de l’intérêt du local
Le processus exige prompt caching, Batches API, blocs PDF ou comptage exact des tokens	Cloud d’abord	Ollama n’implémente actuellement qu’une partie d’Anthropic Messages API
Le code ne doit pas être transmis à un modèle distant	Local, avec fonctions cloud désactivées	Il faut encore auditer les outils web, serveurs MCP et commandes shell

Une stratégie hybride simple consiste à garder en local les modifications ciblées et répétables, puis à passer explicitement au cloud pour le raisonnement à l’échelle du dépôt, les fonctions d’API non prises en charge ou les échecs locaux répétés. Vous conservez ainsi une seule interface Claude Code sans supposer que les deux backends sont équivalents.

Étape 1 : choisir un modèle avec outils et allouer 64k de contexte

Claude Code a besoin de plus que de la génération de texte. Le modèle doit produire des appels d’outils de manière fiable pour que le client puisse lire des fichiers, appliquer des modifications et exécuter des commandes. La page Qwen3.5 d’Ollama annonce la capacité tools et fournit une commande de lancement Claude Code. Vous pouvez aussi inspecter le modèle exact téléchargé avec l’API de détails d’Ollama.

Téléchargez le modèle et examinez capabilities :

ollama pull qwen3.5

curl http://localhost:11434/api/show \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.5"}'

Avant de continuer, vérifiez que capabilities contient tools. Si ce n’est pas le cas, une conversation normale ne remplace pas une validation d’agent. Choisissez dans la bibliothèque actuelle d’Ollama un modèle explicitement compatible avec les outils, téléchargez-le et recommencez la vérification.

Le contexte est le deuxième filtre. La documentation Ollama sur la longueur de contexte recommande au moins 64 000 tokens pour web search, les agents et les outils de programmation, et précise qu’un contexte plus grand consomme davantage de mémoire. Dans l’application Ollama, réglez context length sur 64000 ou plus. Pour un service lancé depuis le shell, arrêtez d’abord l’instance existante, puis exécutez ceci dans un terminal dédié :

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Gardez ce terminal ouvert. Attendez le démarrage du serveur, puis poursuivez dans un second terminal. Si le port est déjà occupé, une instance Ollama tourne déjà : modifiez son contexte plutôt que d’en lancer une deuxième.

Étape 2 : lancer Claude Code avec l’intégration officielle Ollama

Le chemin officiel le plus court est :

ollama launch claude --model qwen3.5

C’est la façon la plus simple d’établir l’intégration. Après le démarrage de Claude Code, exécutez /status et notez les sources de paramètres actives. Cette information sera utile si une couche persistante continue d’envoyer le client vers Ollama après votre retour au cloud.

Pour limiter le changement au terminal actuel, définissez les variables manuellement. L’exemple suivant reste en Bash :

read -rs ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL="http://localhost:11434"
claude --model qwen3.5

read -rs accepte la saisie sans l’afficher. Tapez ollama, puis appuyez sur Entrée. L’endpoint compatible d’Ollama exige la présence de la variable d’authentification, mais le serveur local n’en vérifie pas la valeur. ANTHROPIC_BASE_URL envoie les requêtes au endpoint local, tandis que --model qwen3.5 rend le modèle de test explicite et évite qu’un ancien ANTHROPIC_MODEL ou une valeur enregistrée rende le résultat ambigu.

Étape 3 : valider lecture, modification et commande sur un seul fichier

N’utilisez pas un dépôt de production pour le premier test. Créez un répertoire isolé où chaque résultat se voit dans le fichier, le code de sortie et le diff.

mkdir -p claude-ollama-smoke
cd claude-ollama-smoke
git init
cat > total.py <<'PY'
def total(values):
    return sum(values)

if __name__ == "__main__":
    assert total([2, 3]) == 5
PY
git add total.py
python3 total.py

python3 total.py doit se terminer avec le code 0 sans rien afficher. Lancez Claude Code local depuis ce répertoire et envoyez cette tâche :

Modifie uniquement total.py.
Si un élément de values n’est ni un int ni un float, fais lever à total un TypeError avec le message exact numbers only.
Dans __main__, ajoute une vérification pour [2, "3"] qui confirme le même TypeError et le même message.
Exécute python3 total.py.
Ne modifie aucun autre fichier. Affiche le diff à la fin.

Cette tâche est volontairement petite, mais elle couvre la boucle essentielle de l’agent : lire le fichier, planifier une modification, appeler l’outil d’édition, demander une commande Bash, observer le résultat et présenter le changement final. Gardez les demandes d’autorisation de Claude Code activées. Un modèle local ne rend pas sûr un shell sans restrictions.

Après la tâche, exécutez vous-même :

python3 total.py
git status --short
git diff -- total.py
ollama ps

Critères d’acceptation :

1. python3 total.py se termine avec le code 0.
2. git status --short ne mentionne que total.py, et git diff -- total.py ne contient que la vérification de type et l’assertion demandées.
3. La conversation Claude Code montre des appels aux outils de fichiers et Bash, ou des demandes d’autorisation, et pas seulement une suggestion de code en texte.
4. Pendant l’exécution, ollama ps liste qwen3.5, CONTEXT vaut au moins 64000 et PROCESSOR indique si le modèle est entièrement sur GPU, partiellement déchargé ou surtout sur CPU.

Si un seul de ces points échoue, n’élargissez pas encore le périmètre à un vrai dépôt. Diagnostiquez d’abord, puis choisissez entre changer de modèle, réduire la tâche ou passer au cloud.

Étape 4 : vérifier la frontière d’exécution, pas seulement localhost

ANTHROPIC_BASE_URL=http://localhost:11434 montre que Claude Code envoie les requêtes du modèle vers un port local, mais ne prouve pas que tout le processus est hors ligne. Une preuve plus solide combine un tag de modèle sans :cloud, la présence du modèle dans ollama ps pendant la tâche et des valeurs locales de PROCESSOR et CONTEXT cohérentes avec les ressources de la machine.

La FAQ Ollama indique qu’Ollama ne voit pas les prompts ni les données lorsqu’un modèle s’exécute localement, alors que les prompts et réponses des modèles hébergés dans le cloud sont traités par ce service. La page actuelle de Qwen3.5 lance Claude Code avec le tag local qwen3.5. Ne déduisez pas le nom d’un modèle cloud en ajoutant un suffixe à un tag local ; pour vérifier cette frontière, utilisez un tag explicitement indiqué dans le catalogue Cloud ou le guide d’intégration officiel actuel, comme gemma4:cloud. Déterminez le lieu d’exécution à partir d’un tag valide, de ollama ps et de l’allocation locale des ressources.

Auditez séparément les autres sorties réseau :

• Une commande appelée via Bash peut accéder au réseau, envoyer des fichiers ou lancer un autre CLI.
• Un serveur MCP possède son propre processus, ses autorisations et son trajet de données.
• Web search, web fetch et les modèles cloud d’Ollama ne sont pas de l’inférence locale.
• Les hooks, scripts de test et gestionnaires de paquets du dépôt peuvent aussi contacter des services externes.

Pour un mode Ollama plus strictement local, fusionnez cette clé dans le fichier existant ~/.ollama/server.json sans supprimer les autres paramètres :

{
  "disable_ollama_cloud": true
}

Redémarrez Ollama et vérifiez que ses logs contiennent Ollama cloud disabled: true. Ollama précise que ce réglage désactive ses modèles cloud et web search. Il n’audite pas les autres accès réseau de Claude Code, des serveurs MCP ou des commandes shell.

Étape 5 : comprendre ce que la couche compatible ne garantit pas

Ollama expose une couche compatible avec Anthropic Messages API, pas une réimplémentation complète d’Anthropic API. La documentation actuelle inclut messages, streaming, system prompts, images, tool calls, tool results et thinking parmi les capacités prises en charge, ce qui suffit pour former la boucle de base de Claude Code.

La compatibilité du protocole n’est pas une parité de comportement. La qualité du choix d’outils, la précision du patch, la stabilité d’une longue tâche et le respect des instructions dépendent du modèle, de la quantification, du contexte alloué et du matériel. Réussir le test sur un fichier démontre que le chemin minimal fonctionne dans votre environnement ; cela ne prouve pas qu’un modèle local égalera un modèle Claude sur un grand dépôt.

Ollama classe actuellement comme non pris en charge /v1/messages/count_tokens, prompt caching, Batches API, citations, les blocs PDF document et les erreurs server-sent pendant le streaming. Les nombres de tokens sont également décrits comme des approximations basées sur le tokenizer du modèle. Si votre processus dépend de l’une de ces fonctions, gardez un chemin cloud prêt avant de rencontrer le blocage au milieu d’une tâche.

Étape 6 : revenir explicitement au cloud

Si les variables locales existent seulement dans la session Bash actuelle, quittez Claude Code et exécutez :

unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY ANTHROPIC_MODEL ANTHROPIC_DEFAULT_HAIKU_MODEL ANTHROPIC_DEFAULT_SONNET_MODEL ANTHROPIC_DEFAULT_OPUS_MODEL
claude

Le nouveau processus peut alors suivre votre connexion habituelle ou la configuration d’un fournisseur cloud. Après le démarrage, consultez /status et posez une petite question en lecture seule. Le simple fait que le client démarre ne prouve pas qu’une requête cloud a abouti.

Si Claude Code contacte encore Ollama, la redirection est probablement stockée dans settings plutôt que dans le shell courant. La référence officielle des variables Claude Code indique qu’une valeur env d’un fichier de settings remplace la même variable héritée du shell. Utilisez /status pour identifier les sources actives, puis supprimez ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY et les overrides de modèle de la couche concernée :

• ~/.claude/settings.json
• .claude/settings.json
• .claude/settings.local.json
• settings gérés par l’organisation

Quittez complètement Claude Code et relancez-le après la modification. Une valeur gérée ne peut pas être annulée par une couche inférieure ; un administrateur doit la modifier.

Si le modèle local ne convient pas mais que vous souhaitez conserver une API cloud compatible Anthropic dans le même Claude Code, suivez le guide Claude Code actuel de BetterToken. Le Base URL actuel est https://bettertoken.ai : sans www et sans /v1. Copiez d’abord le Model ID exact depuis model plaza. La configuration manuelle actuelle utilise ANTHROPIC_MODEL pour le modèle principal et les trois variables ANTHROPIC_DEFAULT_*_MODEL pour les alias Haiku, Sonnet et Opus. Pour un test contrôlé, vous pouvez faire pointer les quatre variables vers le même ID exact. Cette session Bash temporaire évite d’inscrire l’API Key dans l’historique :

read -rsp "BetterToken API Key: " ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN
read -rp $'\nBetterToken Model ID: ' ANTHROPIC_MODEL
export ANTHROPIC_MODEL
export ANTHROPIC_BASE_URL="https://bettertoken.ai"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"
export API_TIMEOUT_MS="3000000"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$ANTHROPIC_MODEL"
claude

Le premier prompt masque la saisie de l’API Key ; au second, collez le Model ID exact copié depuis model plaza. Ce smoke test fait pointer le modèle principal et les trois alias vers le même ID. Si vous utilisez volontairement des modèles différents selon le rôle, attribuez à chaque variable par défaut son ID exact. N’ajoutez pas /v1 au Base URL. Après toute modification de settings persistants, quittez complètement puis redémarrez Claude Code ; pour une session temporaire, fermez aussi l’ancien processus avant d’exécuter ce bloc. Envoyez enfin une courte requête en lecture seule. Le changement n’est validé que si la réponse est normale, sans erreur 401, de connexion ou de modèle, et si /status affiche la source active attendue ; cela n’implique pas une parité complète entre les chemins local et cloud.

Diagnostiquer les échecs les plus fréquents

ConnectionRefused ou aucune réponse de localhost:11434

Confirmez que le processus Ollama tourne et que le endpoint utilise le port attendu. Lancez-le avec ollama serve si nécessaire. Si le port est occupé, retrouvez l’instance existante au lieu d’en créer une autre. Avant de rouvrir Claude Code, vérifiez que curl http://localhost:11434/api/ps renvoie du JSON.

Le chat répond, mais Claude Code ne lit ni ne modifie les fichiers

Appelez de nouveau /api/show et confirmez que le modèle annonce tools. Surveillez ensuite les demandes d’autorisation de Claude Code. Si le modèle écrit seulement « vous pourriez modifier le code ainsi » sans produire d’appel d’outil, choisissez un modèle explicitement compatible avec tools. Le transport d’un champ d’outil ne garantit pas une planification fiable par chaque modèle.

La session est très lente ou perd le contexte sur un travail plus long

Exécutez ollama ps et examinez PROCESSOR et CONTEXT. Un fort offload CPU, un contexte inférieur à 64k ou une pression mémoire répétée justifient de réduire la tâche, choisir un modèle plus petit avec tools ou utiliser le cloud. Ne supprimez pas les autorisations et vérifications uniquement pour donner une impression de vitesse.

Modifier le shell ne change ni le endpoint ni le modèle

Exécutez /status dans Claude Code. Une valeur env de settings peut remplacer celle du shell, tandis que --model et /model prennent le pas sur ANTHROPIC_MODEL. Nettoyez la source réellement prioritaire, redémarrez complètement et refaites une requête en lecture seule.

La règle de décision pratique

Considérez Claude Code local comme un chemin d’exécution qui doit mériter un périmètre plus large, pas comme un simple interrupteur. Confirmez tools, allouez au moins 64k de contexte et utilisez la tâche sur un fichier pour observer les appels d’outils, le code de sortie, le diff et ollama ps. N’élargissez que lorsque ces signaux sont stables.

Lorsque la tâche dépasse la machine, dépend d’une fonction Anthropic non prise en charge ou met régulièrement le modèle local en échec sur du vrai code, retirez le endpoint local et revenez délibérément au cloud. Un chemin de retour fiable vaut mieux que de forcer chaque tâche de développement à rester locale.