Claude Code Router : le guide complet 2026

Claude Code est aujourd'hui l'un des assistants de programmation IA les plus puissants, mais le fait qu'il « ne fonctionne qu'avec les modèles officiels d'Anthropic » est devenu un vrai point de friction pour de plus en plus de développeurs : la tarification de l'API officielle n'est pas donnée, l'accès direct peut être instable selon les régions, le risque de bannissement de compte crée une anxiété permanente, et quand 80 % des tokens de votre flux de travail partent dans des tâches à faible valeur ajoutée comme « lire un fichier, le formater, écrire un commentaire », brûler du Opus à 15 $/M tokens sur ce genre de tâches est tout simplement du gaspillage.

claude-code-router (CCR) est un middleware proxy open source sur GitHub, construit autour d'une idée simple : insérer une couche de routage intelligent entre Claude Code et le modèle en amont, de sorte que différents types de requêtes soient automatiquement dirigés vers le modèle le plus adapté — et le moins cher. Les décisions d'architecture complexes vont à Opus, la complétion de code du quotidien va à DeepSeek, le contexte ultra-long va à Gemini 2.5 Pro — tout est automatique, et l'expérience Claude Code reste inchangée de votre côté.

Ceci est le guide CCR le plus complet disponible, couvrant : pourquoi l'utiliser, comment il fonctionne, comment l'installer, comment le configurer, l'intégration via des relais, la conception de la stratégie de routage, et les pièges courants. Il fait environ 4 600 mots — à mettre en favoris et à lire par sections.

1. Pourquoi avez-vous besoin de Claude Code Router

1.1 À quel point le problème de coût de Claude Code est-il grave

Claude Code tourne par défaut sur claude-opus-4-6. Pour les utilisateurs intensifs, la facture API mensuelle atteint facilement 100 à 300 $. Le problème, c'est que ces tokens ont une « densité de valeur » extrêmement inégale :

• Environ 40 % partent dans du travail mécanique : lecture de fichiers, parcours de répertoires, formatage de code
• Environ 25 % est de la génération de code répétitif et le remplissage de cas de test — des tâches à faible complexité
• Environ 20 % est de la simple édition mono-fichier et des commentaires
• Seuls environ 15 % nécessitent réellement un raisonnement de niveau Opus — conception d'architecture multi-fichiers, débogage de bugs coriaces, rédaction de propositions techniques

Autrement dit, environ 85 % de ce que vous payez à Opus n'a en réalité pas besoin d'Opus. DeepSeek V3 (environ 0,27 $/M en entrée) traite ces tâches avec une différence à peine perceptible, pour un coût plus de 50 fois inférieur.

1.2 Difficultés supplémentaires pour les développeurs hors des États-Unis

L'accès direct à l'API Anthropic depuis la Chine continentale nécessite généralement un proxy, avec une latence élevée et une stabilité médiocre — un simple accroc réseau peut interrompre une tâche en plein milieu. Un grand nombre de relais (SiliconFlow, PoloAPI, et d'autres) proposent des points d'accès en connexion directe depuis la Chine, avec une latence bien plus faible. CCR permet de router facilement les requêtes vers ces relais, contournant entièrement l'instabilité réseau.

1.3 Risque de bannissement et stratégie multi-comptes

En 2026, Anthropic a renforcé la détection des usages non conformes, et certains utilisateurs intensifs ont vu leur compte banni. CCR permet de configurer plusieurs Providers (différents relais, différentes clés API) comme un pool en rotation, de sorte que si un compte est banni, le basculement se fait automatiquement sans casser votre flux de travail.

1.4 La valeur réelle de la diversité des modèles

Gemini 2.5 Pro offre une fenêtre de contexte allant jusqu'à 1 million de tokens, ce qui écrase Opus sur les bases de code massives ; DeepSeek R1 a un avantage net sur le raisonnement mathématique et les problèmes algorithmiques ; les modèles Ollama locaux sont irremplaçables dans les scénarios d'entreprise sensibles à la confidentialité. CCR permet à tous ces modèles de s'intégrer sans couture dans un seul flux de travail, sans que vous ayez à changer manuellement de variables d'environnement ou à redémarrer des processus.

2. Comment fonctionne CCR

L'architecture de CCR peut se résumer en une phrase : il lance un proxy local sur localhost, compatible avec l'API Anthropic ; Claude Code envoie chaque requête à ce proxy ; le proxy décide, sur la base des règles de routage, vers quel modèle en amont transférer la requête ; et la réponse est renvoyée à Claude Code par le même chemin qu'à l'aller.

Claude Code → http://localhost:3456 (proxy CCR)
                           ↓ décision de routage
        ┌──────────────────┼──────────────────┐
        ↓                  ↓                  ↓
  tâche en arrière-plan  raisonnement    contexte ultra-long
  DeepSeek Chat     DeepSeek R1      Gemini 2.5 Pro
  (0,27 $/M)        (0,55 $/M)        (1,25 $/M)
        └──────────────────┼──────────────────┘
                           ↓
                    réponse renvoyée à Claude Code

CCR comporte plusieurs composants internes clés :

• Gateway Service : écoute un port local (3456 par défaut) et reçoit les requêtes au format Anthropic Messages envoyées par Claude Code
• Router Engine : utilise les règles de routage de config.json pour déterminer à quel « scénario » appartient la requête en cours (background / think / longContext / webSearch / default)
• Protocol Adapter : convertit les requêtes au format Anthropic vers le format attendu par le Provider cible (OpenAI Chat Completions / Gemini Generate Content / etc.), et reconvertit la réponse en retour
• Fallback Handler : quand le Provider principal échoue, tente les Providers de secours dans l'ordre

Du point de vue de Claude Code, tout le processus est transparent — il ne voit qu'« un point d'accès Anthropic local » et n'a aucune idée de qui traite réellement la requête en coulisses. Il suffit de définir une seule variable d'environnement :

export ANTHROPIC_BASE_URL="http://localhost:3456"

3. Installer CCR

3.1 Prérequis

• Node.js 18 ou version ultérieure (vérifiez avec node -v)
• Claude Code déjà installé (npm install -g @anthropic-ai/claude-code)
• Au moins une clé API IA utilisable (Anthropic, DeepSeek, SiliconFlow — n'importe laquelle convient)

3.2 Installation via npm (recommandé)

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

Une fois l'installation terminée, la commande ccr devient disponible. Vérifiez l'installation :

ccr --version

3.3 Installation depuis les sources GitHub

git clone https://github.com/musistudio/claude-code-router
cd claude-code-router
npm install
npm run build
npm link   # Lie la commande ccr globalement

3.4 Version Desktop (interface graphique)

Si vous préférez une interface graphique, téléchargez l'installateur pour votre plateforme depuis GitHub Releases :

• macOS (Apple Silicon / Intel) : .dmg ou .zip
• Windows : installateur .exe
• Linux : .AppImage

La version Desktop intègre une gestion visuelle des Providers, un éditeur de règles de routage, un panneau de logs des requêtes et des statistiques d'utilisation — pratique pour qui n'est pas à l'aise avec l'édition de JSON brut. Ce guide se concentre sur la version en ligne de commande, plus adaptée à un serveur ou à un environnement CI.

4. Configuration de base : config.json en détail

Le fichier de configuration de CCR se trouve par défaut à ~/.claude-code-router/config.json. Le répertoire est créé automatiquement au premier lancement, mais vous devez créer ce fichier vous-même.

4.1 La configuration la plus simple (un seul Provider)

Si vous voulez simplement transférer toutes les requêtes de Claude Code vers un seul Provider, voici la configuration la plus minimaliste possible :

{
  "Providers": [
    {
      "name": "anthropic",
      "api_key": "sk-ant-api03-votre-cle",
      "api_base_url": "https://api.anthropic.com",
      "models": ["claude-opus-4-6", "claude-sonnet-4-6"]
    }
  ],
  "Router": {
    "default": "anthropic,claude-sonnet-4-6"
  }
}

4.2 Décomposition de la structure de configuration

config.json comporte deux champs de premier niveau :

Référence des champs Provider :

4.3 Les clés de routage de Router expliquées

L'objet Router prend en charge les clés de scénario de routage suivantes :

Les valeurs de route utilisent le format "provider_name,model_name" (séparées par une virgule, sans espace).

5. Pour les développeurs utilisant des relais : guide d'intégration

Pour les développeurs en dehors des États-Unis, les appels directs aux API officielles d'Anthropic, OpenAI et autres peuvent être instables côté réseau. CCR s'associe parfaitement à des relais d'API — il suffit de pointer api_base_url vers le point d'accès du relais.

5.1 Intégration de SiliconFlow

SiliconFlow est l'une des plateformes de relais couvrant le plus largement les modèles open source, avec DeepSeek, Qwen, GLM et d'autres, une connexion directe et un crédit gratuit pour les nouveaux utilisateurs.

{
  "Providers": [
    {
      "name": "siliconflow",
      "api_key": "sk-votre-cle-siliconflow",
      "api_base_url": "https://api.siliconflow.cn/v1",
      "protocol": "openai",
      "models": [
        "deepseek-ai/DeepSeek-V3",
        "deepseek-ai/DeepSeek-R1",
        "Qwen/Qwen2.5-Coder-32B-Instruct"
      ]
    }
  ],
  "Router": {
    "default": "siliconflow,deepseek-ai/DeepSeek-V3",
    "background": "siliconflow,Qwen/Qwen2.5-Coder-32B-Instruct",
    "think": "siliconflow,deepseek-ai/DeepSeek-R1"
  }
}

5.2 Configuration hybride : relais + officiel (la configuration recommandée)

La configuration de production la plus recommandée : les tâches quotidiennes passent par SiliconFlow (coût faible, connexion directe), les tâches complexes et le contexte ultra-long passent par OpenRouter (couverture de modèles la plus large), et seules les tâches nécessitant réellement une qualité de premier plan vont vers Anthropic officiel.

{
  "Providers": [
    {
      "name": "siliconflow",
      "api_key": "sk-votre-cle-siliconflow",
      "api_base_url": "https://api.siliconflow.cn/v1",
      "protocol": "openai"
    },
    {
      "name": "openrouter",
      "api_key": "sk-or-votre-cle-openrouter",
      "api_base_url": "https://openrouter.ai/api/v1",
      "protocol": "openai"
    },
    {
      "name": "anthropic",
      "api_key": "sk-ant-cle-officielle-ou-relais",
      "api_base_url": "https://api.anthropic.com",
      "protocol": "anthropic"
    }
  ],
  "Router": {
    "default": "siliconflow,deepseek-ai/DeepSeek-V3",
    "background": "siliconflow,Qwen/Qwen2.5-Coder-32B-Instruct",
    "think": "siliconflow,deepseek-ai/DeepSeek-R1",
    "longContext": "openrouter,google/gemini-2.5-pro-preview"
  }
}

5.3 Autres exemples de configuration de relais

{
  "name": "poloapi",
  "api_key": "sk-votre-cle-poloapi",
  "api_base_url": "https://poloapi.top/v1",
  "protocol": "openai"
}

{
  "name": "openrouter",
  "api_key": "sk-or-votre-cle-openrouter",
  "api_base_url": "https://openrouter.ai/api/v1",
  "protocol": "openai",
  "models": [
    "google/gemini-2.5-pro-preview",
    "anthropic/claude-opus-4-6",
    "deepseek/deepseek-chat"
  ]
}

{
  "name": "ollama",
  "api_key": "ollama",
  "api_base_url": "http://localhost:11434/v1",
  "protocol": "openai",
  "models": ["qwen2.5-coder:32b", "deepseek-coder-v2:16b"]
}

6. Analyse approfondie de la stratégie de routage

6.1 Démarrer CCR

Une fois config.json prêt, lancez :

# Démarre le service proxy CCR (écoute sur localhost:3456 par défaut)
ccr start

# Dans un autre terminal, lancez Claude Code en le pointant vers CCR
export ANTHROPIC_BASE_URL="http://localhost:3456"
claude

Ou utilisez la commande raccourcie de CCR, qui définit la variable d'environnement et lance Claude Code automatiquement :

ccr code

6.2 La route background : la clé pour maximiser les économies

background est la clé de routage qui a le plus d'impact sur le coût dans CCR. Claude Code marque automatiquement les requêtes comme mode background lors des opérations suivantes :

• Lecture d'un grand volume de contenu de fichiers (outil Read)
• Parcours de répertoires et recherche de fichiers (outils Glob/Grep)
• Tâches de résumé et de formatage de code
• Génération automatique de cas de test

Ces tâches consomment souvent énormément de tokens mais requièrent très peu d'intelligence du modèle. Router background vers Qwen/Qwen2.5-Coder-32B-Instruct (partiellement gratuit sur SiliconFlow) ou vers une instance Ollama locale fait chuter cette part de votre coût à zéro ou presque.

6.3 La route think : accélérer les tâches à forte intensité de raisonnement

Quand Claude Code entre en mode extended thinking (généralement parce que vous avez posé une question d'architecture complexe ou un problème algorithmique), CCR peut router ces requêtes vers un modèle comme DeepSeek R1, spécifiquement optimisé pour le raisonnement. DeepSeek R1 est au niveau d'Opus 4.6 sur les tâches de raisonnement mathématique et de code, pour un prix bien plus bas.

"Router": {
  "think": "siliconflow,deepseek-ai/DeepSeek-R1"
}

6.4 La route longContext : traiter des bases de code massives

Quand les tokens d'entrée d'une seule requête dépassent 60 000 (le seuil par défaut), CCR bascule automatiquement sur la route longContext. Claude Opus 4.6 plafonne à une fenêtre de contexte de 200K, tandis que Gemini 2.5 Pro offre jusqu'à 1 million de tokens — extrêmement précieux pour analyser de gros projets.

"Router": {
  "longContext": "openrouter,google/gemini-2.5-pro-preview"
}

Vous pouvez personnaliser le seuil (en tokens) :

"Router": {
  "longContextThreshold": 80000,
  "longContext": "openrouter,google/gemini-2.5-pro-preview"
}

6.5 La stratégie complète à quatre niveaux

Voici une configuration « routage à quatre niveaux » éprouvée, adaptée à la plupart des développeurs indépendants :

{
  "Providers": [
    {
      "name": "siliconflow",
      "api_key": "sk-votre-cle-siliconflow",
      "api_base_url": "https://api.siliconflow.cn/v1",
      "protocol": "openai"
    },
    {
      "name": "openrouter",
      "api_key": "sk-or-votre-cle-openrouter",
      "api_base_url": "https://openrouter.ai/api/v1",
      "protocol": "openai"
    }
  ],
  "Router": {
    "default": "siliconflow,deepseek-ai/DeepSeek-V3",
    "background": "siliconflow,Qwen/Qwen2.5-Coder-32B-Instruct",
    "think": "siliconflow,deepseek-ai/DeepSeek-R1",
    "longContext": "openrouter,google/gemini-2.5-pro-preview",
    "longContextThreshold": 60000
  }
}

La logique de cette configuration :

• Par défaut → DeepSeek V3 (connexion directe, le meilleur rapport qualité-prix pour la génération de code)
• Tâches en arrière-plan → Qwen2.5-Coder-32B (partiellement gratuit sur SiliconFlow, rapide)
• Raisonnement approfondi → DeepSeek R1 (puissance de raisonnement proche d'Opus, 10 fois moins cher)
• Contexte ultra-long → Gemini 2.5 Pro (fenêtre à un million de tokens, gère des projets massifs)

7. Configuration avancée : Fallback et modèles Fusion

7.1 Basculement automatique (Fallback)

Quand le Provider principal renvoie une erreur ou expire, le mécanisme de fallback essaie automatiquement un Provider de secours, pour que votre flux de travail ne soit pas interrompu. Utilisez un tableau :

{
  "Router": {
    "default": ["siliconflow,deepseek-ai/DeepSeek-V3", "openrouter,deepseek/deepseek-chat"],
    "background": ["siliconflow,Qwen/Qwen2.5-Coder-32B-Instruct", "ollama,qwen2.5-coder:32b"]
  }
}

CCR essaie les entrées dans l'ordre du tableau — si la première échoue, il passe à la deuxième, et ainsi de suite. Très utile quand la disponibilité d'un relais est instable.

7.2 Rotation des clés API (protection contre le bannissement d'un seul compte)

Plusieurs clés API pour un même Provider peuvent être configurées comme un pool en rotation, et CCR équilibrera automatiquement la charge entre elles :

{
  "Providers": [
    {
      "name": "siliconflow",
      "api_key": ["sk-cle1", "sk-cle2", "sk-cle3"],
      "api_base_url": "https://api.siliconflow.cn/v1",
      "protocol": "openai"
    }
  ]
}

7.3 Modèles composites Fusion

Les modèles Fusion sont une fonctionnalité propre à la version Desktop de CCR : ils combinent un modèle de base avec des capacités spécifiques (vision, recherche web, outils MCP) en un seul « modèle virtuel » utilisé comme une seule entrée dans vos règles de routage.

Par exemple, vous pourriez configurer un « DeepSeek doté de vision » : quand vous envoyez une capture d'écran à Claude Code, le traitement visuel passe par Gemini Flash (bon marché et rapide) tandis que la génération de texte reste sur DeepSeek V3.

7.4 Fonctions de routage personnalisées (avancé)

CCR permet de définir une logique de routage personnalisée en JavaScript, pour les scénarios nécessitant un contrôle fin :

{
  "Router": {
    "customRouter": "function route(ctx) { if (ctx.tokenCount > 100000) return 'openrouter,google/gemini-2.5-pro-preview'; if (ctx.scenario === 'background') return 'ollama,qwen2.5-coder:32b'; return 'siliconflow,deepseek-ai/DeepSeek-V3'; }"
  }
}

L'objet ctx comprend des champs comme scenario (le scénario de routage), tokenCount (le nombre de tokens en entrée) et model (le nom du modèle dans la requête) — vous pouvez implémenter n'importe quelle logique de routage à partir de ces informations.

8. Comparatifs de coûts réels

8.1 Comparatif de factures mensuelles

Supposons que vous soyez un utilisateur intensif de Claude Code, avec environ 100M de tokens d'usage API par mois (entrée + sortie) :

8.2 Attentes réalistes

Réductions de coûts rapportées par de vrais utilisateurs de la communauté :

• Tout router vers DeepSeek : le coût tombe à 5–10 % de l'original, mais la qualité sur les tâches d'architecture complexes décline nettement
• Routage hybride à quatre niveaux (recommandé) : le coût tombe à 20–40 % de l'original, avec une différence de qualité presque imperceptible
• Router uniquement les tâches background vers un modèle bon marché : le coût tombe à 50–60 % de l'original, la stratégie de départ la plus prudente

Les chiffres de « réduction de 80–99 % » qui circulent en ligne reposent généralement sur le fait de router une grande partie des tâches vers Ollama en local ou vers des modèles gratuits — les résultats réels dépendent fortement de votre charge de travail spécifique. Il vaut mieux d'abord faire tourner vos logs de requêtes pendant une semaine, puis ajuster votre stratégie de routage en fonction de la distribution réelle des tokens.

9. FAQ et pièges courants

❌ Problème 1 : Claude Code affiche Connection Refused après le démarrage de CCR

Cause : le port dans ANTHROPIC_BASE_URL est erroné, ou CCR n'a pas démarré correctement.
Solution : exécutez ccr start, vérifiez le port d'écoute affiché dans la sortie, puis réglez la variable d'environnement en conséquence. La version en ligne de commande utilise 3456 par défaut, la version Desktop utilise 8080 par défaut.

# Version en ligne de commande
export ANTHROPIC_BASE_URL="http://localhost:3456"

# Version Desktop
export ANTHROPIC_BASE_URL="http://localhost:8080"

❌ Problème 2 : l'édition de fichiers cesse de fonctionner après routage vers un modèle moins cher

Cause : certains modèles ne prennent pas en charge le tool calling, dont dépendent les outils Write/Edit/Bash de Claude Code.
Solution : vérifiez que le modèle choisi prend en charge le function calling / tool use. Les modèles suivants sont validés par la communauté :

• DeepSeek V3 ✓
• DeepSeek R1 ✓ (certaines versions nécessitent de passer par OpenRouter)
• Qwen2.5-Coder-32B-Instruct ✓
• Gemini 2.5 Pro / Flash ✓
• Modèles Ollama locaux : vérifiez si la version spécifique que vous utilisez le prend en charge

❌ Problème 3 : sortie corrompue ou réponses interrompues

Cause : certains relais ont des bugs dans leur gestion des réponses en streaming, ou le modèle lui-même a des problèmes avec un encodage de caractères particulier.
Solution : essayez d'ajouter "stream": false à la configuration de ce Provider pour passer en réponse non-streaming, ou changez de relais/modèle.

❌ Problème 4 : les tâches background ne sont pas routées vers le modèle bon marché défini

Cause : la route background dépend du fait que Claude Code joigne un tag de scénario à la requête, et ce comportement peut varier d'une version à l'autre de Claude Code.
Solution : mettez à jour vers la dernière version de Claude Code (npm update -g @anthropic-ai/claude-code), et vérifiez dans les logs de CCR que la décision de routage est correctement prise.

❌ Problème 5 : les modifications de config.json ne prennent pas effet

Cause : CCR met la configuration en cache pendant son exécution et ne la recharge pas automatiquement après une modification du fichier.
Solution : exécutez ccr stop pour arrêter le service, puis ccr start pour le redémarrer.

Sécurité et confidentialité

10. Conclusion

claude-code-router est, au fond, un outil qui « vous rend le contrôle du modèle qui alimente réellement Claude Code ». Sa barrière technique est basse — il s'agit essentiellement d'un fichier de configuration JSON et de deux variables d'environnement — mais les économies et la flexibilité qu'il apporte sont substantielles.

Pour les développeurs hors des États-Unis, CCR associé à un relais résout d'un coup les deux problèmes les plus centraux : la stabilité réseau (connexion directe) et le contrôle des coûts (router chaque type de tâche vers le modèle le plus rentable). À plus long terme, à mesure que la concurrence entre outils de programmation IA s'intensifie, ce type d'architecture « découplée de tout fournisseur unique » ne fera que gagner en valeur.

Si vous rencontrez des difficultés pendant la configuration, cherchez ou ouvrez un ticket sur GitHub Issues. La communauté est active, et la plupart des problèmes courants ont déjà une solution documentée.