Claude Code Router — acheminer Claude Code vers n’importe quel modèle, ou se passer entièrement du routeur

La plupart des personnes qui recherchent Claude Code Router veulent l’une de deux choses différentes : router Claude Code entre plusieurs fournisseurs de modèles, ou simplement exécuter Claude Code à un coût inférieur au tarif catalogue d’Anthropic. Seul le premier cas nécessite le routeur. Claude Code lit nativement ANTHROPIC_BASE_URL, donc le second se résume à trois variables d’environnement et aucun logiciel supplémentaire.

Ce guide couvre les deux voies, avec les noms exacts des variables, le piège d’identifiants qui produit un 401 silencieux et une liste honnête de ce qui cesse de fonctionner derrière toute passerelle. Si vous avez récemment lu un autre article sur CCR, passez d’abord à Option B : le config.json que ces articles vous demandent de modifier n’est plus la configuration lue par le routeur.

De laquelle avez-vous réellement besoin ?

Le routeur est un service local : un processus supplémentaire à exécuter, configurer et maintenir à jour — et, depuis 2026, une application de bureau dotée de sa propre interface plutôt qu’un fichier à modifier. Il justifie ce coût lorsque vous avez réellement besoin d’un routage multi-fournisseurs, d’une comptabilisation par requête ou d’une sélection de modèle au niveau des sous-agents. Il ne le justifie pas lorsqu’une URL de base aurait suffi.

Option A — remplacement de l’URL de base (aucune installation)

Kunavo fournit l’API native Anthropic Messages à /v1/messages, qui est l’endpoint appelé par Claude Code. Faites-le pointer vers celle-ci :

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...              # create at kunavo.com/app/keys
export ANTHROPIC_MODEL=claude-sonnet-5             # exact slug — see the table below
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5     # the opus alias and plan mode (v2.1.280+)
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5   # the sonnet alias; Sonnet 5.5 is not on Kunavo
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5   # background tasks

ANTHROPIC_BASE_URL désigne uniquement l’origine — Claude Code ajoute lui-même /v1/messages, n’incluez donc aucun chemin. Conservez les lignes de modèle : le modèle par défaut intégré à Claude Code et son alias opus aboutissent tous deux au dernier modèle Opus ; si Kunavo ne propose pas encore ce modèle, la première requête renvoie une erreur 404. L’alias sonnet demande Sonnet 5.5, que Kunavo ne propose pas ; sans la ligne ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, la phase d’exécution de opusplan et tout sous-agent configuré sur model: sonnet renvoient une erreur 404. L’alias opus est verrouillé sur Opus 5.5 (claude-opus-5-5), ce qui nécessite Claude Code v2.1.280 ou une version ultérieure — exécutez claude update si votre version est plus ancienne. Obtenez la clé dans le tableau de bord après votre inscription et l’ajout de $10 de crédit ; elle ne s’affiche qu’une seule fois.

Quelle variable d’identifiants — et pourquoi cela compte

Claude Code envoie les deux variables d’identifiants dans des en-têtes HTTP différents, et une clé placée dans l’en-tête que le serveur ne lit pas échoue avec 401 :

Préférez ANTHROPIC_AUTH_TOKEN pour une raison précise : ANTHROPIC_API_KEY nécessite une approbation unique dans une session interactive, et une clé refusée une fois est ensuite ignorée sans nouvelle invite — un échec déroutant où la variable est clairement définie mais manifestement inutilisée. La découverte des modèles ne fait pas de distinction sur Kunavo. La découverte des modèles de la passerelle de Claude Code envoie uniquement le token bearer lorsque ANTHROPIC_AUTH_TOKEN est défini et utilise x-api-key sinon ; l’endpoint /v1/models de Kunavo lit la clé depuis l’un ou l’autre en-tête.

Rendez la configuration persistante

Les exports du shell ne s’appliquent qu’à ce terminal et à tout ce qui est lancé depuis celui-ci — un éditeur ouvert depuis le dock ne les verra pas, pas plus que les agents d’arrière-plan. Placez les valeurs dans un fichier de paramètres pour couvrir tous les cas :

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Utilisez ~/.claude/settings.json pour tous les projets. Ne placez jamais une clé dans le .claude/settings.json d’un projet — ce fichier est versionné.

Vérifiez avant de lui faire confiance

Testez d’abord l’endpoint directement, afin qu’un échec pointe vers la configuration plutôt que vers Claude Code :

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

# A response starting with {"id":"msg_ means the URL and key both work.
# 401 -> the key is in the wrong header; see "Which credential variable" below.

Lancez ensuite claude depuis le même shell et exécutez /status. Une ligne Anthropic base URL affichant api.kunavo.com et une ligne Auth token mentionnant votre variable confirment que les deux parties sont actives.

Définir un modèle personnalisé — choisir explicitement le slug

Kunavo résout les slugs de modèles par correspondance exacte et ne crée pas d’alias pour les noms suffixés d’une date ; claude-sonnet-4-5-20250929 renvoie donc 404 tandis que claude-sonnet-5 réussit. Définissez toujours ANTHROPIC_MODEL plutôt que de vous fier à la valeur par défaut intégrée :

Les variables d’alias vous permettent d’acheminer chaque tâche sans aucun routeur : ANTHROPIC_DEFAULT_OPUS_MODEL alimente l’alias opus et le mode plan, ANTHROPIC_DEFAULT_SONNET_MODEL alimente sonnet et la phase d’exécution de opusplan, et ANTHROPIC_DEFAULT_HAIKU_MODEL alimente haiku ainsi que le travail en arrière-plan de Claude Code — les résumés et les titres qui accumulent discrètement des coûts. La définir sur claude-haiku-4-5 est la ligne la plus rentable de toute la configuration. (ANTHROPIC_SMALL_FAST_MODEL est l’ancienne écriture obsolète du même paramètre.)

Facultatif : afficher tous les modèles dans le sélecteur

Définissez CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 (Claude Code v2.1.129+) et Claude Code interroge GET /v1/models au démarrage, en ajoutant ce qu’il trouve au sélecteur /model libellé From gateway. Kunavo fournit cet endpoint, donc chaque modèle Claude activé apparaît et /model devient un menu dynamique au lieu d’une liste maintenue manuellement. L’une ou l’autre variable d’identifiants fonctionne pour cela — voir ci-dessus.

Option B — claude-code-router, tel qu’il fonctionne réellement aujourd’hui

Commencez ici, car presque tout ce qui a été écrit sur CCR décrit une version qui n’existe plus. Le routeur était autrefois un fichier JSON et une commande ccr code. Il s’agit désormais d’un plan de contrôle local doté d’une application de bureau, d’une interface de gestion, de journaux de requêtes et d’une passerelle de modèles — et le config.json que montre chaque tutoriel ne le configure plus.

CCR conserve sa configuration d’exécution dans ~/.claude-code-router/config.sqlite (%APPDATA%\claude-code-router\config.sqlite sous Windows). Un config.json ancien est lu une seule fois, comme source de migration, lorsqu’aucune configuration SQLite n’existe encore. Après ce premier lancement, sa modification n’affecte pas la configuration active — sans erreur ni avertissement. Votre bloc Providers soigneusement collé n’est tout simplement pas la configuration.

Cela inclut cette page avant le 2026-09-06 : l’extrait JSON qui se trouvait ici était erroné, et d’une manière qui peut coûter un après-midi, car rien ne vous indique qu’il a été ignoré. La configuration s’effectue désormais dans l’interface (ou, en sauvegarde, Settings → Export data — ne copiez pas les fichiers SQLite actifs pendant l’exécution de CCR).

Installer et lancer

CCR est disponible sous deux formes : une application de bureau disponible dans GitHub Releases (barre d’état, mises à jour automatiques, intégrations de bureau) et une interface CLI npm pour les déploiements sans interface graphique ou supervisés. Elles partagent le même répertoire de configuration.

# CCR ships as a desktop app (GitHub Releases) or an npm CLI. Both read the
# same ~/.claude-code-router directory. The CLI needs Node.js 22+.
npm install -g @musistudio/claude-code-router
ccr ui        # management UI on :3458, model gateway on :3456

# Configure the provider and an Agent Config profile in that UI, then launch
# Claude Code through the profile by name:
ccr "Claude Code - Kunavo"        # npm CLI
ccr-app "Claude Code - Kunavo"    # the desktop app's own launcher

# There is no 'ccr code' in the current command reference. The service commands
# are start / ui / stop / serve / web; everything else is a profile name.

Ajouter Kunavo consiste en une entrée de fournisseur — Providers → Add provider, préréglage Other / custom API endpoint, endpoint https://api.kunavo.com, votre clé sk-kn- — et un profil Agent Config → Add profile → Claude Code. La version détaillée champ par champ, notamment Check Connection et la découverte des modèles, se trouve sur la page d’intégration de Claude Code Router. Le reste de cette section couvre ce que cette page n’aborde pas : les identifiants, les coûts et les modes de défaillance.

Trois identifiants, et celui concerné par une erreur 401

C’est la cause la plus fréquente d’une configuration fonctionnelle qui semble défaillante. CCR utilise trois secrets distincts, qui authentifient trois étapes différentes :

L’association des ports prend également au dépourvu : la gestion utilise par défaut 127.0.0.1:3458 et la passerelle de modèles 127.0.0.1:3456. Une URL de base pointant vers 3458 atteint l’interface, pas la passerelle. (Docker regroupe délibérément les deux derrière un seul endpoint Nginx, d’où la différence des instructions Docker.) Une interface accessible ne garantit pas une passerelle fonctionnelle : vérifiez /health à l’adresse de la passerelle et confirmez que Server affiche Running.

La correspondance par niveau est essentielle

Claude Code ne demande pas un modèle, mais un niveau — la boucle principale utilise Sonnet ou Opus, tandis que les tâches en arrière-plan (sous-agents, recherche, résumés, titres de conversation) utilisent le modèle rapide et léger. Un profil Claude Code dans Agent Config expose ces éléments dans des champs distincts : un Model par défaut, ainsi que des remplacements facultatifs pour Fable, Opus, Sonnet et Haiku, chacun acceptant une valeur Provider/model. Laissez un niveau vide et Claude Code le sélectionnera.

Lisez ce tableau avant de reprendre la répartition des niveaux de quelqu’un d’autre, car la séparation évidente est le premier levier : claude-sonnet-5 coûte 50 % moins cher que claude-opus-5-5 sur Kunavo ($1.40 / $7.00 contre $2.80 / ). Le deuxième levier est le niveau Haiku : à $0.70 / $3.50, il est 2× moins cher que Sonnet 5, et il prend en charge un volume que vous ne voyez jamais — chaque sous-agent, chaque passage de tri des fichiers et chaque titre généré. claude-sonnet-4-6 n’est plus le Sonnet économique : à $2.10 / $10.50, il coûte 50 % de plus que Sonnet 5, raison pour laquelle les extraits ci-dessus définissent ANTHROPIC_MODEL=claude-sonnet-5.

Routage des sous-agents — ce que la correspondance de niveaux ne peut pas faire

Les remplacements de niveaux assignent tous les sous-agents à un seul modèle. CCR peut aller plus loin : lorsqu’une requête Claude Code correspond à la route intégrée, il injecte la liste des modèles disponibles dans la description de l’outil Agent / Task, et Claude Code préfixe l’invite de chaque agent créé d’une balise indiquant le modèle souhaité :

<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>

CCR retire la balise et route cette requête en conséquence : un sous-agent de recherche peut donc utiliser Haiku tandis qu’un sous-agent de révision utilise Opus, selon la tâche plutôt que par affectation fixe. Le commutateur est facile à manquer : le mécanisme reste désactivé tant qu’au moins un modèle n’a pas de Description sur la page Models. Sans description, CCR n’injecte rien et chaque sous-agent revient discrètement au modèle par défaut du profil. Rédigez les descriptions selon l’adéquation à la tâche — « recherche de code, tri de fichiers, sous-agents parallèles économiques » pour Haiku, « analyse d’architecture, révision à haut risque » pour Opus. Lorsqu’il fonctionne, les journaux de requêtes affichent builtin:claude-code-subagent comme motif de routage.

Choix du protocole et coût en cache

CCR sonde l’endpoint et sélectionne un protocole filaire. Donnez-lui l’origine nue https://api.kunavo.com et il utilise Anthropic Messages ; donnez-lui https://api.kunavo.com/v1 et il utilise le format OpenAI-compatible. Les deux interfaces sont actives avec la même clé, et vous pouvez remplacer la détection automatique dans les paramètres avancés.

Préférez le format Anthropic Messages. Il conserve cache_control sur le réseau : la mise en cache des invites atteint donc le modèle et les entrées mises en cache sont facturées à 10 % du tarif des entrées (comment cela fonctionne) — pour une boucle d’agent qui renvoie un préfixe stable à chaque étape, c’est la plus grande économie individuelle disponible. La réserve honnête est qu’un routeur placé sur le chemin modifie encore les requêtes : CCR supprime le message système d’en-tête de facturation injecté par Claude Code et ajoute la liste des modèles aux descriptions d’outils lorsque le routage des sous-agents est activé. Les deux éléments se trouvent avant vos points de rupture du cache ; chaque modification de ce contenu entraîne donc un défaut de cache tandis que le nouveau préfixe se réchauffe. Le comportement devient ensuite stable — mais c’est une véritable raison pour laquelle l’Option A offre un cache légèrement meilleur que l’Option B, en plus d’être plus simple à exploiter.

Solution de secours : nouvelle tentative ou basculement

Le paramètre Default on failure de la page Routing mérite d’être défini avant d’en avoir besoin. Retry renvoie la requête au même modèle pour 408, 409, 429 et 5xx, en respectant Retry-After et, à défaut, en appliquant un délai exponentiel de 1 s jusqu’à un plafond de 30 s. Fallback targets parcourt une liste ordonnée de modèles de secours et se déclenche pour toute réponse 4xx ou 5xx, selon l’idée qu’un modèle introuvable ou un rejet du fournisseur peut ne concerner que la cible actuelle. Les règles individuelles peuvent remplacer le paramètre global. Lorsqu’un basculement s’exécute, la réponse contient x-ccr-fallback-attempts et x-ccr-fallback-model, afin que vous puissiez l’identifier a posteriori.

Vérifier qu’il se trouve réellement sur le chemin

Lancez Claude Code depuis le profil, envoyez un message, puis ouvrez Request logs dans CCR. La ligne affiche request model (ce que Claude Code a demandé), resolved provider et resolved model (où la requête a été envoyée) — ce triplet en constitue la preuve. Dans la CLI, /model répertorie les modèles exposés par CCR. Si Claude Code répond mais qu’aucune ligne n’apparaît dans les journaux, vous avez lancé Claude Code vous-même plutôt que par l’intermédiaire de CCR, et la portée du profil est Only opened from CCR.

Coût d’une session de programmation

Claude Code renvoie l’invite système, la conversation et le nouveau contexte de fichiers à chaque étape ; le tarif par token se cumule donc rapidement. Aux tarifs Kunavo pour claude-sonnet-5 :

Cela représente environ 30 % de réduction sur le modèle principal, avant la mise en cache des invites. Les tarifs complets figurent dans le guide des tarifs de l’API Claude, et le calculateur de coûts utilise vos propres nombres de tokens.

Ce qui fonctionne encore — et ce qui ne fonctionne pas

Pointer Claude Code vers une passerelle modifie quelques éléments. La liste est courte et mérite d’être connue avant de vous engager :

Pour cette dernière ligne : le comptage des tokens est le seul endpoint que la spécification de passerelle d’Anthropic marque comme facultatif, et Claude Code estime localement l’utilisation du contexte lorsqu’il est absent. Kunavo ne fournit pas /v1/messages/count_tokens actuellement ; votre valeur /context est donc une estimation et non un décompte exact. Rien ne se dégrade au-delà de ce nombre — la compaction automatique et la session elle-même restent inchangées.

Dépannage

Le chemin de l’URL de base

…et lorsque le routeur se trouve sur le chemin

Les corrections erreur par erreur pour l’API elle-même se trouvent dans les pages de dépannage invalid API key et rate limit.

Questions fréquentes