Guide complet — Claude Code + CCR + Modèles gratuits
mai 2026 · 20 min de lecture
Objectif : utiliser Claude Code (Sonnet/Opus) pour les tâches complexes, et déléguer automatiquement les tâches simples à des modèles 100% gratuits via Claude Code Router. Résultat : ~80-90% d'économies sur les tokens.
Table des matières
- Ce qu'on va construire
- Prérequis
- Installer Claude Code Router
- Créer un compte OpenRouter et récupérer la clé API
- Configurer CCR avec tous les modèles gratuits
- Comment le routage fonctionne — les détails techniques
- Les subagents spécialisés
- Le skill smart-routing
- Installer les subagents et le skill
- Lancer Claude Code via CCR
- Classement des modèles gratuits pour le code
- Exemples d'utilisation concrets
- Dépannage
- Récapitulatif des commandes
1. Ce qu'on va construire
Le problème
Claude Code (Sonnet ou Opus) est puissant mais coûteux. Quand il travaille sur un projet, il lance des sous-agents (subagents) pour des tâches parallèles : explorer des fichiers, écrire des fonctions simples, lancer des commandes bash... Ces tâches ne nécessitent pas un modèle frontier — n'importe quel bon modèle gratuit peut les faire.
La solution
Claude Code Router (CCR) est un proxy qui s'intercale entre Claude Code et l'API Anthropic. Il intercepte chaque requête et peut la rediriger vers n'importe quel modèle — y compris des modèles 100% gratuits sur OpenRouter.
Claude Code (toi)
│
▼
CCR Proxy ──── analyse la requête
│
├── Tâche complexe ? ──► MiniMax M2.5 (gratuit, 80% SWE-Bench)
├── Tâche légère ? ──► GPT-OSS 20B (gratuit, rapide)
├── Raisonnement ? ──► Nemotron Super (gratuit)
└── Long contexte ? ──► Gemma 31B (gratuit, 256K tokens)
Ce qu'on a testé et validé
- ✅ CCR intercepte les requêtes Claude Code
- ✅ Le routage vers MiniMax M2.5 fonctionne (80.2% SWE-Bench vérifié)
- ✅ Le mécanisme de tag
<CCR-SUBAGENT-MODEL>redirige les subagents - ✅
model: haikudans un subagent → route automatiquement vers le modèlebackground - ✅ Config complètement isolable (HOME override) pour tester sans risque
2. Prérequis
Ce dont tu as besoin
- macOS (ce guide est pour Mac, adaptable Linux)
- Node.js v18+ et npm
- Claude Code installé
- Un compte Anthropic avec accès à Claude Code
- Un compte OpenRouter (gratuit)
Vérifier Node.js et npm
node --version # doit afficher v18 ou plus
npm --version # doit afficher 9 ou plus
Si Node n'est pas installé : https://nodejs.org
Vérifier que Claude Code est installé
claude --version
Si ce n'est pas le cas :
npm install -g @anthropic-ai/claude-code
3. Installer Claude Code Router
Une seule commande :
npm install -g @musistudio/claude-code-router
Vérifier l'installation :
ccr --help
Tu dois voir une liste de commandes : start, stop, code, model, etc.
4. Créer un compte OpenRouter et récupérer la clé API
- Va sur https://openrouter.ai
- Crée un compte (gratuit)
- Va dans Settings → API Keys
- Clique sur Create Key
- Copie la clé — elle commence par
sk-or-v1-...
Les modèles gratuits sont disponibles sans avoir besoin de crédits. Tu peux voir la liste complète sur https://openrouter.ai/collections/free-models
5. Configurer CCR avec tous les modèles gratuits
Créer le dossier de configuration
mkdir -p ~/.claude-code-router
Créer le fichier de configuration
nano ~/.claude-code-router/config.json
Colle le contenu suivant (remplace VOTRE_CLE_API par ta clé OpenRouter) :
{
"LOG": true,
"LOG_LEVEL": "info",
"Providers": [
{
"name": "minimax",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["minimax/minimax-m2.5:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "gpt-20b",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["openai/gpt-oss-20b:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "gpt-120b",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["openai/gpt-oss-120b:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "gemma-31b",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["google/gemma-4-31b-it:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "gemma-26b",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["google/gemma-4-26b-a4b-it:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "nemotron-super",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["nvidia/nemotron-3-super-120b-a12b:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "nemotron-nano",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["nvidia/nemotron-3-nano-30b-a3b:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "nemotron-reason",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "nemotron-12b",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["nvidia/nemotron-nano-12b-v2-vl:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "nemotron-9b",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["nvidia/nemotron-nano-9b-v2:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "minimax",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["minimax/minimax-m2.5:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "glm",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["z-ai/glm-4.5-air:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "laguna-m",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["poolside/laguna-m.1:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "laguna-xs",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["poolside/laguna-xs.2:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "ring",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["inclusionai/ring-2.6-1t:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "cobuddy",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["baidu/cobuddy:free"],
"transformer": { "use": ["openrouter"] }
},
{
"name": "owl",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "VOTRE_CLE_API",
"models": ["openrouter/owl-alpha"],
"transformer": { "use": ["openrouter"] }
}
],
"Router": {
"default": "minimax,minimax/minimax-m2.5:free",
"background": "gpt-20b,openai/gpt-oss-20b:free",
"think": "nemotron-super,nvidia/nemotron-3-super-120b-a12b:free",
"longContext": "gemma-31b,google/gemma-4-31b-it:free",
"longContextThreshold": 60000
}
}
Sauvegarde avec Ctrl+O, quitte avec Ctrl+X.
Explication du fichier de config
Providers : liste de tous tes modèles disponibles.
Chaque provider a :
name→ l'alias court que tu utiliseras pour référencer ce modèleapi_base_url→ l'endpoint OpenRouterapi_key→ ta clé OpenRoutermodels→ le vrai identifiant du modèletransformer: openrouter→ adapte le format de requête pour OpenRouter
Router : définit quel modèle utiliser selon le type de tâche :
default→ toutes les requêtes normales (ici : MiniMax M2.5)background→ tâches légères en arrière-plan (ici : GPT-OSS 20B)think→ requêtes avec raisonnement activé (ici : Nemotron Super)longContext→ contextes > 60 000 tokens (ici : Gemma 31B)
6. Comment le routage fonctionne — les détails techniques
Cette section explique les mécanismes sous le capot, vérifiés en lisant le code source de CCR.
Les 4 mécanismes de routage (par ordre de priorité)
Mécanisme 1 : Tag <CCR-SUBAGENT-MODEL> dans system[1]
C'est le mécanisme le plus précis. Quand Claude Code lance un subagent,
il envoie la requête avec un tableau system à deux blocs :
system[0]= le prompt système principal de Claude Codesystem[1]= le corps du fichier.mdde ton subagent
CCR lit le début de system[1]. Si ça commence par <CCR-SUBAGENT-MODEL>,
il extrait le modèle et route vers lui.
En pratique : pour qu'un subagent utilise un modèle spécifique,
mets le tag au tout début du corps de son fichier .md :
---
name: mon-subagent
description: Fait des trucs
model: haiku
---
<CCR-SUBAGENT-MODEL>minimax,minimax/minimax-m2.5:free</CCR-SUBAGENT-MODEL>
Tu es un agent de code...
Mécanisme 2 : model: haiku → route background (le plus simple !)
Si le frontmatter d'un subagent contient model: haiku, Claude Code envoie
la requête avec le modèle claude-haiku-.... CCR détecte le mot haiku dans
le nom du modèle et redirige automatiquement vers ton Router.background.
C'est la méthode la plus simple : pas besoin de tag, juste model: haiku
dans le frontmatter et CCR fait le reste.
Mécanisme 3 : Requête avec thinking → route think
Si la requête contient un champ thinking (mode de réflexion étendu),
CCR route vers Router.think.
Mécanisme 4 : Long contexte → route longContext
Si le nombre de tokens dépasse longContextThreshold (défaut : 60 000),
CCR route vers Router.longContext.
7. Les subagents spécialisés
Les subagents sont des fichiers .md avec un frontmatter YAML.
Ils définissent des assistants spécialisés que Claude délègue automatiquement.
Créer les fichiers
Crée un dossier pour tes subagents personnels :
mkdir -p ~/.claude/agents
Subagent 1 : code-worker (pour le code facile → MiniMax)
nano ~/.claude/agents/code-worker.md
---
name: code-worker
description: >
Agent pour les tâches de code mécaniques : fonctions, tests unitaires,
boilerplate, CRUD, composants UI standards, migrations, config files.
NE PAS utiliser pour : architecture complexe, debugging subtil.
model: haiku
color: green
tools: Read, Write, Edit, Glob, Grep, Bash
---
<CCR-SUBAGENT-MODEL>minimax,minimax/minimax-m2.5:free</CCR-SUBAGENT-MODEL>
Tu es un agent spécialisé dans l'écriture de code de qualité production.
## Processus
1. Lis d'abord les fichiers existants pour comprendre les conventions du projet
2. Écris le code en suivant exactement ces conventions
3. Retourne un résumé court de ce qui a été créé/modifié
## Règles
- Pas de commentaires évidents dans le code
- Respecte le style existant (tabs vs spaces, naming)
- Si une information manque, fais une hypothèse raisonnable et signale-la
Subagent 2 : researcher (pour l'exploration → GPT-OSS 120B)
nano ~/.claude/agents/researcher.md
---
name: researcher
description: >
Agent pour explorer et analyser du code, lire des fichiers, chercher
des patterns, comprendre une architecture. Lecture seule uniquement.
Idéal avant une refacto ou pour répondre à des questions sur un codebase.
model: haiku
color: blue
tools: Read, Glob, Grep, Bash
---
<CCR-SUBAGENT-MODEL>gpt-120b,openai/gpt-oss-120b:free</CCR-SUBAGENT-MODEL>
Tu es un agent de recherche et d'exploration de codebase.
## Mission
Explorer et analyser du code sans jamais le modifier.
Retourner des informations claires, concises et actionnables.
## Format de réponse
- Points clés en bullet points
- Chemins de fichiers exacts avec numéros de ligne si pertinent
- Pas de verbiage inutile
Subagent 3 : thinker (pour le raisonnement → Nemotron Super)
nano ~/.claude/agents/thinker.md
---
name: thinker
description: >
Agent pour le raisonnement logique approfondi : analyser des bugs,
identifier des race conditions, évaluer des edge cases de sécurité,
comparer des approches architecturales, déboguer des erreurs cryptiques.
model: haiku
color: purple
tools: Read, Glob, Grep, Bash
---
<CCR-SUBAGENT-MODEL>nemotron-super,nvidia/nemotron-3-super-120b-a12b:free</CCR-SUBAGENT-MODEL>
Tu es un agent de raisonnement spécialisé dans l'analyse logique.
## Processus
1. Lis et comprends le contexte complet du problème
2. Raisonne étape par étape (ne saute pas aux conclusions)
3. Considère les cas limites et les effets secondaires
## Format de réponse
- Analyse : Problème → Causes possibles → Diagnostic → Solution
- Indique ton niveau de confiance
- Si plusieurs solutions, compare les trade-offs
8. Le skill smart-routing
Un skill est un fichier d'instructions que Claude charge en contexte. Il lui enseigne quand et comment utiliser les différents modèles.
Créer le dossier skills
mkdir -p ~/.claude/skills
Créer le skill
nano ~/.claude/skills/smart-routing.md
---
name: smart-routing
description: >
Utilise ce skill quand tu t'apprêtes à lancer un subagent ou quand tu peux
décomposer une tâche en parties simples et complexes pour économiser des tokens.
---
# Smart Routing via CCR
## Avant chaque tâche, pose-toi cette question
> "Est-ce que cette sous-tâche nécessite vraiment mes capacités complètes,
> ou est-ce qu'un modèle gratuit peut le faire ?"
## Classement des modèles gratuits (mai 2026)
| Alias CCR | Modèle | SWE-Bench | Usage idéal |
|-----------------|-------------------------------------------|-----------|--------------------------|
| `minimax` | `minimax/minimax-m2.5:free` | 80.2% ⭐⭐⭐⭐⭐ | Code, agents, prod |
| `nemotron-super`| `nvidia/nemotron-3-super-120b-a12b:free` | 60.47% ⭐⭐⭐⭐ | Code + raisonnement |
| `gpt-120b` | `openai/gpt-oss-120b:free` | - ⭐⭐⭐ | Usage général, recherche |
| `gpt-20b` | `openai/gpt-oss-20b:free` | - ⭐⭐ | Tâches légères, rapide |
| `gemma-31b` | `google/gemma-4-31b-it:free` | - ⭐⭐⭐ | Long contexte (256K) |
## Quand déléguer à un modèle gratuit
✅ **Déléguer** :
- Lecture/analyse de fichiers (grep, exploration)
- Écriture de fonctions standards, boilerplate
- Tests unitaires
- Refactoring simple, renommage
- Commandes bash et collecte de résultats
- Génération de config, JSON, YAML
❌ **Garder pour toi (Sonnet/Opus)** :
- Architecture complexe ou décisions de design
- Débogage de bugs subtils nécessitant le contexte complet
- Interactions directes avec l'utilisateur
- Raisonnement multi-étapes interdépendants
## Workflow optimisé
1. Reçois la tâche
2. Décompose en sous-tâches
3. Pour chaque sous-tâche :
- Code standard → subagent `code-worker` (MiniMax)
- Exploration → subagent `researcher` (GPT-120B)
- Raisonnement → subagent `thinker` (Nemotron Super)
- Complexe/décision → garde en contexte principal
4. Synthétise les résultats
## Exemple : construire un CRUD complet
Toi (Sonnet) : architecture + synthèse finale
├── code-worker : "Écris le modèle Prisma User avec migrations" ├── code-worker : "Écris les routes Express CRUD /users" ├── code-worker : "Écris les tests Jest pour les routes CRUD" ├── researcher : "Explore le codebase et liste les patterns existants" └── thinker : "Analyse les edge cases de sécurité du système auth"
9. Installer les subagents et le skill
Option A — Installation manuelle (déjà fait ci-dessus)
Tu as créé les fichiers directement dans ~/.claude/agents/ et ~/.claude/skills/.
Option B — Depuis ce dossier
Si tu as cloné ou téléchargé le dossier claude-no-limit :
# Copier les subagents
cp ~/Documents/claude-no-limit/subagents/*.md ~/.claude/agents/
# Copier le skill
cp ~/Documents/claude-no-limit/skill-smart-routing.md ~/.claude/skills/
Vérifier l'installation
# Lister les subagents installés
claude agents | cat
# Lister les skills
ls ~/.claude/skills/
Important : les subagents créés manuellement sur le disque nécessitent un redémarrage de la session Claude Code pour être chargés. Les subagents créés via
/agentsdans l'interface sont disponibles immédiatement.
10. Lancer Claude Code via CCR
Démarrer le serveur CCR
ccr start
Tu dois voir quelque chose comme :
Loaded JSON config from: /Users/ton-nom/.claude-code-router/config.json
Claude Code Router started on port 3456
Vérifier que CCR tourne
ccr status
Lancer Claude Code via CCR
ccr code
C'est tout. Toutes tes requêtes Claude Code passent maintenant par CCR et sont routées vers les modèles gratuits selon les règles de la config.
Commandes utiles
ccr start # Démarrer le proxy
ccr stop # Arrêter le proxy
ccr restart # Redémarrer (après modification de config)
ccr status # Vérifier l'état
ccr code # Lancer Claude Code via CCR
ccr model # Sélectionner un modèle interactivement
ccr ui # Ouvrir l'interface web
Changer de modèle à la volée
ccr model
Interface interactive pour choisir quel modèle utiliser pour chaque route.
11. Classement des modèles gratuits pour le code
Résultats des tests effectués (mai 2026) :
✅ Modèles fiables et rapides
| Rang | Modèle | Alias | SWE-Bench | Vitesse |
|---|---|---|---|---|
| 🥇 1 | MiniMax M2.5 | minimax |
80.2% | Rapide |
| 🥈 2 | Nemotron Super 120B | nemotron-super |
60.47% | Moyen |
| 🥉 3 | GPT-OSS 120B | gpt-120b |
— | Rapide |
| 4 | GPT-OSS 20B | gpt-20b |
— | Très rapide |
⚠️ Modèles avec réserves
| Modèle | Alias | Problème |
|---|---|---|
| Gemma 4 31B | gemma-31b |
Erreurs provider intermittentes sur OpenRouter |
| Nemotron Reasoning | nemotron-reason |
Très lent sur tier gratuit (>90s de latence) |
Recommandation : utilise MiniMax M2.5 comme modèle
default. Avec 80.2% sur SWE-Bench (benchmark de code sur GitHub Issues réels), c'est le meilleur modèle gratuit disponible pour du code en production.
12. Exemples d'utilisation concrets
Exemple 1 : Projet avec subagents automatiques
Lance ccr code et demande quelque chose de complexe. Claude va
automatiquement déléguer les parties simples aux subagents code-worker,
researcher et thinker selon leurs descriptions.
Tu : "Crée une API REST Express avec authentification JWT,
modèle User Prisma, tests Jest, et documentation Swagger"
Claude (Sonnet) va :
- Analyser la demande (lui-même)
- Déléguer à
researcher→ explore le projet existant (GPT-120B) - Déléguer à
code-worker→ génère le modèle Prisma (MiniMax) - Déléguer à
code-worker→ génère les routes Express (MiniMax) - Déléguer à
code-worker→ génère les tests (MiniMax) - Synthétiser et valider (lui-même, Sonnet)
Exemple 2 : Forcer un modèle spécifique via env var
Pour forcer TOUS les subagents à utiliser MiniMax, quel que soit leur config :
export CLAUDE_CODE_SUBAGENT_MODEL="minimax,minimax/minimax-m2.5:free"
ccr code
Pour remettre à la normale :
unset CLAUDE_CODE_SUBAGENT_MODEL
Pour que ça soit permanent, ajoute dans ~/.zshrc ou ~/.bash_profile :
export CLAUDE_CODE_SUBAGENT_MODEL="minimax,minimax/minimax-m2.5:free"
Exemple 3 : Utiliser directement un subagent
Dans une session ccr code :
Tu : "Utilise le subagent code-worker pour écrire les tests unitaires
de la fonction parseUser() dans src/utils.ts"
Claude va directement déléguer au subagent code-worker qui utilisera MiniMax.
Exemple 4 : Changer le modèle par défaut
Si tu veux passer Nemotron Super en default (meilleur raisonnement) :
# Édite la config
nano ~/.claude-code-router/config.json
# Modifie cette ligne :
"default": "nemotron-super,nvidia/nemotron-3-super-120b-a12b:free",
# Redémarre CCR
ccr restart
13. Dépannage
CCR ne démarre pas
# Vérifier les logs
ccr status
# Vérifier la syntaxe JSON de la config
cat ~/.claude-code-router/config.json | python3 -m json.tool
Erreur "Provider returned error" pour un modèle
Les modèles gratuits OpenRouter ont des limites de rate. Attends quelques
secondes et réessaie. Pour une solution permanente, configure un modèle de
fallback ou change le modèle default pour un autre.
Le subagent ne route pas vers le bon modèle
Vérifie que :
- Le tag
<CCR-SUBAGENT-MODEL>est bien au tout début du corps du fichier.md - Le format est
<CCR-SUBAGENT-MODEL>alias,model-id:free</CCR-SUBAGENT-MODEL> - L'alias correspond exactement à un
namedans la sectionProvidersde ta config - CCR est démarré (
ccr status)
Tester que le proxy fonctionne
curl -s -X POST "http://127.0.0.1:3456/v1/messages" \
-H "x-api-key: test" \
-H "Content-Type: application/json" \
-d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"Say OK"}]}' \
| python3 -c "import sys,json; d=json.load(sys.stdin); print('Modèle:', d.get('model')); print('Réponse:', d.get('content',[{}])[0].get('text'))"
Si ça répond avec un modèle MiniMax ou GPT-OSS, le routage fonctionne.
Voir quel modèle est utilisé en temps réel
Active les logs détaillés dans la config :
"LOG_LEVEL": "debug"
Puis ccr restart. Les logs apparaissent dans le terminal où tu as lancé ccr start.
14. Récapitulatif des commandes
Installation (une seule fois)
# 1. Installer CCR
npm install -g @musistudio/claude-code-router
# 2. Créer la config (avec ta clé OpenRouter)
mkdir -p ~/.claude-code-router
nano ~/.claude-code-router/config.json # colle la config de la section 5
# 3. Installer les subagents
mkdir -p ~/.claude/agents
# colle les 3 fichiers code-worker.md, researcher.md, thinker.md
# 4. Installer le skill
mkdir -p ~/.claude/skills
# colle le fichier smart-routing.md
Usage quotidien
# Démarrer
ccr start
# Coder
ccr code
# Arrêter
ccr stop
Modifier la config
nano ~/.claude-code-router/config.json
ccr restart
Sources et ressources
- Claude Code Router : https://github.com/musistudio/claude-code-router
- OpenRouter free models : https://openrouter.ai/collections/free-models
- Claude Code subagents : https://code.claude.com/docs/en/sub-agents
- MiniMax M2.5 benchmarks : https://www.minimax.io/models/text
- OpenRouter rankings : https://openrouter.ai/rankings
Guide créé en mai 2026 — testé et validé sur macOS avec Claude Code Sonnet 4.6