Claude Code Router : routage multi-modèles pour un codage efficace

Lorsque j'ai commencé à utiliser intensément Claude Code, deux choses m'ont sauté aux yeux : la qualité est excellente, et la facture le montre. Chaque requête, qu'il s'agisse d'un docstring de trois lignes ou d'une refonte architecturale complète, passe au même endpoint Anthropic au même tarif. 

Avec le temps, cette dépendance à un seul fournisseur ne génère pas seulement une pression sur les coûts : elle crée aussi du risque. Elle implique également qu'une limite de débit sur un modèle peut bloquer tout votre flux de travail.

Claude Code Router (CCR) répond directement à ces deux problèmes. C'est un proxy open source qui intercepte vos requêtes Claude Code avant qu'elles n'atteignent un fournisseur, puis redirige chaque requête vers le modèle backend le plus adapté à la tâche. 

Dans ce tutoriel, je vous guide pas à pas : installation du routeur, configuration de chemins de routage multi-fournisseurs et durcissement du système pour un usage quotidien en production. Pour suivre, récupérez les clés API des fournisseurs que vous souhaitez utiliser (DeepSeek, Gemini, OpenRouter ou tout autre backend pris en charge) et ouvrez votre terminal. C'est parti.

Pour vous inspirer sur les nouveaux LLM et leurs points forts, consultez nos guides sur les derniers modèles :

• GPT-5.4
• GPT-5.3 Instant
• Gemini 3.1
• Claude Sonnet 4.6
• Claude Opus 4.6
• Qwen3.5
• MiniMax M2.5

Qu'est-ce que Claude Code Router ?

Avant de passer à la configuration, il vaut la peine de comprendre ce qu'est vraiment CCR et pourquoi il fonctionne comme ça. Si vous n'avez pas encore travaillé avec Claude Code, commencez par notre guide pratique Claude Code 2.1.

Claude Code Router est une passerelle proxy locale. Au lancement, il se lie à un port de votre machine (127.0.0.1:3456 par défaut) et se place entre votre client Claude Code et tout fournisseur LLM externe. Du point de vue de Claude Code, il discute simplement avec un endpoint local. Sous le capot, CCR décide en temps réel de la destination réelle de la requête.

Le problème central qu'il résout est la dépendance à un seul fournisseur. Quand tout transite par un acteur unique, vous héritez de toutes ses contraintes : 

• Paliers de tarification
• Limites de débit
• Plafonds de fenêtre de contexte 

CCR élimine cela en vous permettant de définir des règles de routage qui basculent automatiquement de modèle selon le type de tâche, le nombre de tokens ou toute logique personnalisée que vous écrivez. Un scan de fichiers en arrière-plan n'a pas besoin du même modèle qu'une session de raisonnement en Plan Mode, et avec CCR, il n'utilisera pas le même.

Ce qui distingue CCR des APIs directes des fournisseurs ou des agrégateurs cloud, c'est l'endroit où il s'exécute. 

Parce que le proxy tourne en local, vos charges utiles ne transitent jamais par un service d'agrégation tiers avant d'atteindre leur destination. Vous bénéficiez aussi d'un contrôle fin sur la transformation des requêtes : modification d'en-têtes, suppression de champs de cache et plafonnement des tokens, via un système de transformateurs qui opère entièrement sur votre machine. 

Pour moi, c'est ce modèle local qui rend CCR vraiment pratique, bien plus qu'un simple contournement intelligent : au final, la configuration est plus économique, plus résiliente et plus privée que de tout router via un fournisseur cloud unique.

Architecture et prérequis de Claude Code Router

Avec une vision claire de ce que fait CCR, voyons comment il fonctionne sous le capot et ce qu'il faut prévoir avant de l'installer.

Modèle conceptuel clé

Comprendre l'architecture de CCR facilite grandement la configuration, et le schéma proxy devient très clair dès qu'on le voit de bout en bout. 

Quand vous démarrez CCR, il intercepte toutes les requêtes sortantes de votre terminal avant qu'elles n'atteignent l'endpoint Anthropic par défaut. Pour chaque requête, il :

1. Inspecte la requête.
2. Applique vos règles de routage.
3. Transforme la charge utile au format attendu par le fournisseur cible.
4. La transfère. 

La réponse revient de la même manière, retransformée au format attendu par Claude Code, si bien que le client ne voit aucun changement.

Le mécanisme clé de cette interception est le routage par type de tâche. CCR classe les requêtes entrantes par type et les associe au modèle approprié. Voici comment les principales catégories se comportent en pratique :

Chaque type de tâche reçoit l'outil adéquat, sans intervention manuelle une fois la configuration en place. D'expérience, la route background offre le retour immédiat le plus visible : ces requêtes silencieuses de scan de fichiers se produisent en continu pendant une session de codage, et avant CCR, j'ignorais à quel point elles s'additionnaient discrètement.

Prérequis essentiels

Avant d'installer CCR, assurez-vous d'avoir :

• Node.js v18 ou supérieur comme environnement d'exécution

• npm comme gestionnaire de paquets

• Claude Code installé globalement (npm install -g @anthropic-ai/claude-code)

• Au moins un backend de modèle, soit une clé API d'un fournisseur externe pris en charge (DeepSeek, Gemini, OpenRouter, Groq, Volcengine, SiliconFlow, etc.), soit une instance Ollama locale avec un modèle déjà téléchargé, si vous préférez éviter totalement les fournisseurs externes

Vous n'avez pas besoin de compte chez tous les fournisseurs dès le départ. Un seul backend fonctionnel suffit pour réaliser ce tutoriel ; vous pourrez en ajouter d'autres ensuite.

Pour comparer Claude Code à l'une de ses alternatives les plus populaires, nous vous recommandons de lire notre article OpenClaw vs Claude Code.

Tutoriel pas à pas : mettre en place Claude Code Router

Maintenant que les concepts et prérequis sont clairs, construisons la configuration étape par étape.

Installer et démarrer le routeur

Avec les prérequis en place, vous pouvez installer CCR globalement avec npm. Sous Linux, toutefois, vous pouvez rencontrer une erreur de permissions lors de l'installation globale car npm tente d'écrire dans /usr/lib/node_modules, appartenant à root. La solution recommandée consiste à rediriger le répertoire global de npm vers un dossier dont votre utilisateur est propriétaire, plutôt que d'exécuter la commande avec sudo :

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Pour rendre ce changement de PATH permanent, ajoutez la ligne export à votre ~/.bashrc ou ~/.zshrc puis rechargez votre shell. Installez ensuite CCR :

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

Cela rend la CLI ccr disponible globalement dans votre shell. Démarrez ensuite le service routeur :

ccr start

Par défaut, CCR se lie à http://127.0.0.1:3456. Dès que vous voyez dans la sortie de démarrage que le service est lié au port, le proxy est prêt à accepter des requêtes.

Configurer un fournisseur de base

Toute la configuration de CCR se trouve dans ~/.claude-code-router/config.json. Avant de brancher plusieurs fournisseurs, je recommande de commencer par un seul fournisseur fiable pour éliminer les variables et vérifier que la base fonctionne.

OpenRouter est un excellent point de départ, et c'est celui que j'utilise en premier à chaque nouvelle installation de CCR. Il donne accès à des dizaines de modèles, dont plusieurs gratuits, via une seule clé API : idéal pour valider la couche de routage avant de s'engager sur des fournisseurs précis. Inscrivez-vous et récupérez une clé sur OpenRouter.

Voici une configuration minimale avec OpenRouter :

{
  "Providers": [
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "YOUR_OPENROUTER_API_KEY",
      "models": ["openai/gpt-oss-120b:free"],
      "transformer": {
        "use": ["openrouter"]
      }
    }
  ],
  "Router": {
    "default": "openrouter,openai/gpt-oss-120b:free"
  }
}

Quelques points importants :

• api_base_url doit cibler l'endpoint complet de chat completions du fournisseur, pas seulement le domaine de base.

• transformer indique quel adaptateur de charge utile intégré CCR doit utiliser, car chaque fournisseur attend un format différent. Le transformateur gère cette traduction en toute transparence.

• Router.default définit le modèle de secours pour toute requête qui ne correspond pas à une règle plus spécifique, avec la syntaxe provider,model.

Par mesure de sécurité, évitez de coder les clés en dur dans le fichier. CCR prend en charge l'interpolation de variables d'environnement : remplacez YOUR_OPENROUTER_API_KEY par $OPENROUTER_API_KEY et exportez la variable dans votre shell. L'interpolation fonctionne de manière récursive dans toute la config, ce qui passe à l'échelle lorsque vous ajoutez des fournisseurs.

Connecter Claude Code au proxy

Avec la config en place, lancer Claude Code via le routeur tient en une seule commande :

ccr code

C'est tout. ccr code démarre le proxy et lance Claude Code simultanément, avec l'environnement préconfiguré automatiquement. Vous n'avez pas besoin d'exécuter ccr start au préalable.

Pour vérifier que le routage est actif, consultez le dossier ~/.claude-code-router/logs/. Un fichier nommé ccr-*.log confirme que le proxy a démarré et reçoit des requêtes. Vous pouvez le suivre en temps réel :

tail -f ~/.claude-code-router/logs/$(ls -t ~/.claude-code-router/logs/ | head -1)

Journaux Claude Code Router

Deux points utiles pour la vérification. L'en-tête Claude Code affiche toujours le modèle Claude par défaut actuel, quel que soit le modèle vers lequel CCR route, car il reflète votre session Anthropic, pas le backend actif. Si vous demandez au modèle « quel modèle êtes-vous ? », il répondra aussi « Claude Sonnet 4.6 », car c'est l'identité fournie par le client Claude Code. Aucun des deux n'est un indicateur fiable.

Session Claude Code Router

Le journal est la seule source de vérité. Repérez le champ \"model\" dans les entrées de réponse. Si vous y voyez le nom du modèle configuré, par exemple \"model\":\"openai/gpt-oss-120b:free\", le routage fonctionne.

Si vous souhaitez rendre CCR persistant pour utiliser directement la commande claude sans ccr code, ajoutez ceci à votre ~/.bashrc ou ~/.zshrc :

eval "$(ccr activate)"

Assurez-vous simplement que ccr start s'exécute d'abord dans ce cas, car activate ne fait que définir des variables d'environnement et ne lance pas le service.

Mettre en place un routage multi-fournisseurs

Maintenant que la base est validée, étendons la config pour router différents types de tâches vers différents fournisseurs. Voici une configuration Router plus complète :

{
  "Router": {
    "default": "deepseek,deepseek-chat",
    "background": "ollama,qwen2.5-coder:latest",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "openrouter,google/gemini-2.5-pro-preview",
    "longContextThreshold": 60000,
    "webSearch": "gemini,gemini-2.5-flash"
  }
}

Chaque clé associe une catégorie de tâches à une paire \"provider,model\" :

• La route background gère l'analyse de fichiers et la collecte de contexte. Elles peuvent aller sans risque vers un modèle Ollama local, donc gratuites : c'est le changement qui a le plus réduit ma facture API mensuelle. 

• La route think capture le Plan Mode et les tâches de raisonnement complexe, où un modèle comme deepseek-reasoner se rentabilise. 

• La route longContext s'active automatiquement dès qu'une requête dépasse longContextThreshold tokens (60 000 par défaut), en redirigeant vers un modèle à grande capacité sans intervention manuelle. 

• Pour webSearch, le modèle doit prendre en charge la recherche web nativement. Si vous routez via OpenRouter, vous devez aussi ajouter le suffixe :online au nom du modèle (par exemple \"anthropic/claude-3.5-sonnet:online\").

Pour résister aux limites de débit, la fonction de routeur personnalisé de CCR permet de définir une logique de repli en JavaScript. Créez un fichier au chemin de votre choix, référencez-le dans la config avec \"CUSTOM_ROUTER_PATH\": \"/path/to/custom-router.js\", puis exportez une fonction async qui renvoie une chaîne \"provider,model\" ou null pour revenir aux règles par défaut :

module.exports = async function router(req, config) {
  // Logique principale ici. Retournez null pour revenir aux règles de config.
  return null;
};

C'est l'endroit idéal pour implémenter une relance en cas de rate limit : en détectant une réponse 429 et en reroutant automatiquement vers un fournisseur secondaire. Après toute modification de config, pensez à redémarrer le service pour l'appliquer :

ccr restart

Exploitation et dépannage de Claude Code Router

Une fois le routage en place, l'enjeu est de garder le système observable, sûr et simple à déboguer en cas d'incident.

Surveiller l'usage et maîtriser les budgets

CCR fournit deux systèmes de journalisation distincts à connaître :

• Journaux serveur : requêtes HTTP, appels API et événements serveur. Écrits dans ~/.claude-code-router/logs/ sous la forme de fichiers ccr-*.log. C'est le journal que vous utiliserez le plus.

• Journaux applicatifs : décisions de routage, écrits dans ~/.claude-code-router/claude-code-router.log, bien que ce fichier puisse être absent selon votre configuration et le niveau de logs.

L'examen régulier du journal serveur vous donne une vision claire des routes déclenchées, des modèles appelés et d'éventuelles erreurs côté fournisseur. 

Pour une visibilité temps réel, CCR inclut aussi une statusline (disponible à partir de la v1.0.40) activable via ccr ui. Une fois active, elle affiche l'état de routage directement dans votre terminal pendant l'exécution de Claude Code, indiquant d'un coup d'œil quel modèle traite chaque requête.

Côté budget, le meilleur garde-fou est votre configuration de routage elle-même. En orientant les routes background et default vers des modèles moins chers ou locaux, vous évitez d'invoquer des modèles premium pour des tâches à faible valeur. Réservez think et longContext aux modèles qui justifient leur coût, et maintenez le seuil de longContext aussi élevé que votre flux de travail le permet. 

D'après mon expérience, cette discipline au niveau de la configuration est plus fiable qu'un suivi réactif : elle empêche les dépenses déréglées au lieu de les détecter après coup.

Sécuriser les identifiants et les accès

La gestion des secrets mérite une attention particulière, surtout quand la liste des fournisseurs s'allonge. Mes règles sont simples :

• Ne jamais valider de clés API en clair dans config.json si ce fichier est versionné. Utilisez toujours l'interpolation de variables d'environnement avec la syntaxe \"$PROVIDER_API_KEY\", et exportez les clés depuis votre profil shell ou un gestionnaire de secrets.

• Laissez le proxy en localhost pour les postes individuels. Si vous ne définissez pas d'APIKEY dans la config, CCR force automatiquement l'attache à 127.0.0.1, évitant tout accès externe sur des machines ou réseaux partagés.

• Définissez une APIKEY pour les déploiements équipe si vous devez ouvrir l'hôte sur 0.0.0.0. Chaque client se connectant au routeur doit inclure cette clé dans l'en-tête Authorization: Bearer ou x-api-key.

• Désactivez ou réduisez les logs si vous routez du code sensible. La journalisation est activée par défaut (\"LOG\": true). Définissez \"LOG\": false pour ne plus écrire les charges utiles sur disque, ou \"LOG_LEVEL\": \"warn\" pour supprimer les sorties de debug verbeuses.

Une approche pratique consiste à conserver toutes vos clés API dans votre profil shell et à les référencer via la syntaxe $VAR_NAME dans config.json. Ainsi, le fichier de config ne contient aucun secret et peut être partagé ou versionné sans risque.

En cas de doute sur une fuite potentielle d'une clé dans les logs, vérifiez d'abord votre niveau de logs. Passer à \"LOG_LEVEL\": \"warn\" est le moyen le plus rapide de limiter ce qui est écrit sur disque sans désactiver totalement la journalisation.

Dépanner les pannes de routage courantes

Quand ça casse, une séquence de diagnostic par couches fait gagner beaucoup de temps. Mieux vaut partir de la couche la plus externe et progresser vers l'interne.

Étape 1 : vérifiez que le proxy tourne 

Lancez ccr code et cherchez la confirmation de démarrage du service. Si le port est occupé ou si le service a échoué, vous verrez des erreurs de connexion refusée dans Claude Code. 

Consultez les journaux serveur dans ~/.claude-code-router/logs/ pour le détail. La plupart des échecs au démarrage tiennent à un conflit de port ou à un fichier config.json mal formé.

Étape 2 : vérifiez les noms de modèles

L'erreur de config la plus fréquente est une discordance entre le nom du modèle dans Providers et celui dans Router. Ils doivent être strictement identiques. 

S'ils diffèrent, CCR envoie une requête sans champ model et vous verrez une erreur Missing model in request body. Après correction, exécutez toujours ccr restart pour recharger la config.

Étape 3 : vérifiez les réglages côté fournisseur

Si le nom du modèle est correct mais que les requêtes échouent encore en 404, vérifiez vos paramètres de compte chez le fournisseur. OpenRouter, par exemple, a une politique de confidentialité par défaut qui bloque l'envoi de données vers des fournisseurs tiers pour les modèles gratuits. Vous verrez une erreur du type No endpoints found matching your data policy. 

La solution consiste à activer l'utilisation des modèles gratuits dans vos paramètres de confidentialité OpenRouter. D'autres fournisseurs peuvent avoir des interrupteurs similaires à vérifier en cas de 4xx inattendus.

Étape 4 : vérifiez la configuration du transformateur

Si les requêtes atteignent le fournisseur mais que les réponses sont mal formées ou que les appels d'outils échouent, le problème vient généralement d'un transformateur manquant ou incorrect. Recoupez votre fournisseur avec la liste des transformateurs intégrés et assurez-vous d'utiliser le bon dans le tableau \"use\".

Dans la plupart des cas, suivre ces quatre étapes dans l'ordre permet d'isoler rapidement le problème. Le journal serveur capture à la fois la requête sortante et la réponse brute du fournisseur, vous donnant tout le contexte nécessaire pour comprendre l'origine de la panne.

Conclusion

Vous disposez désormais d'une infrastructure de routage multi-fournisseurs opérationnelle au-dessus de Claude Code. Les tâches en arrière-plan partent vers des modèles locaux rapides, les travaux de raisonnement vers des modèles spécialisés, et les requêtes à long contexte sont traitées par des fournisseurs à grande capacité — le tout automatiquement selon des règles que vous contrôlez. 

Les bénéfices immédiats : coûts API en baisse, plus de point de défaillance unique lié aux limites de débit, et la flexibilité de changer de fournisseur sans toucher à votre flux de travail.

Pour maintenir l'efficacité dans le temps, consultez périodiquement vos journaux de routage. Le journal serveur montre quelles routes se déclenchent le plus souvent et si des modèles coûteux sont invoqués pour des tâches qu'un modèle moins cher pourrait gérer. Ajuster longContextThreshold et les règles de repli selon l'usage réel est bien plus efficace que de les figer une fois pour toutes.

Enfin, si votre travail implique du code propriétaire, je vous recommande vivement de router ces requêtes vers un LLM local via Ollama. C'est ce que je fais pour tout travail client impliquant du code non publié. L'ajouter comme fournisseur prend moins d'une minute, et vos requêtes les plus sensibles ne quittent jamais votre machine.

Pour celles et ceux qui souhaitent passer au niveau supérieur en développement d'applications d'IA, je recommande vivement de vous inscrire à notre parcours de compétences AI Engineering with LangChain. Les contenus pédagogiques sont nativement conçus pour l'IA, avec un tuteur personnel qui vous enseigne exactement les compétences nécessaires pour devenir un véritable pro de l'ingénierie des workflows d'IA.