Claude Code Router 3.1.1 : installation, routage et dépannage

Vous voulez utiliser DeepSeek, OpenRouter, Gemini, Kimi, Z.AI/GLM ou un autre endpoint compatible dans Claude Code, mais le tutoriel consulté parle encore de config.json et de ccr code. Ou bien l’interface s’ouvre, tandis que la passerelle sur 127.0.0.1:3456 ne démarre jamais. Ce guide suit le fonctionnement actuel de la version 3.1.1, de l’installation à un profil Claude Code vérifié, avec une procédure claire pour chaque panne courante.

Commencez par la version : 3.1.1 ne repose plus sur un config.json écrit à la main

Configurez les fournisseurs, les routes et les Agent Profiles dans la Web UI au lieu de copier un ancien bloc JSON. Au 26 septembre 2026, le tag latest de npm pointe vers la version 3.1.1. Le paquet actuel conserve sa configuration principale dans config.sqlite et génère gateway.config.json pour la passerelle en cours d’exécution, d’après les métadonnées du registre npm et le README actuel du projet.

Cette différence de version explique deux impasses fréquentes. La référence CLI actuelle lance un agent avec ccr <profile-name-or-id> et ne répertorie pas ccr code. De plus, gateway.config.json est un fichier généré, pas une source à maintenir manuellement. Si un tutoriel impose config.json ou ccr code, vérifiez d’abord la génération de CCR visée avant de conclure à un problème d’installation.

Préparez Node.js, un fournisseur upstream et Claude Code

Il vous faut Node.js 22 ou plus récent, un accès à un service de modèles et Claude Code installé localement. CCR route les requêtes ; il n’installe pas Claude Code et un accès API n’est pas une souscription Claude.ai ou Claude Max.

Vérifiez d’abord Node.js :

node --version

Mettez Node.js à jour si la version majeure est inférieure à 22. L’upstream peut être un preset intégré tel qu’OpenRouter, DeepSeek, Gemini, Moonshot/Kimi ou Z.AI, ou un endpoint personnalisé qui expose un protocole OpenAI-compatible ou Anthropic-compatible pris en charge.

Installez la CLI npm et vérifiez la commande avant toute configuration

Lancez immédiatement la commande d’aide après l’installation globale. Vous séparerez ainsi un problème npm ou PATH d’un problème de Provider ou de Routing.

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

Pour mettre à jour ou désinstaller :

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

La désinstallation du paquet npm ne supprime pas la configuration ni les bases locales. Le répertoire de données est ~/.claude-code-router sous macOS/Linux et %APPDATA%\claude-code-router sous Windows.

Configurez dans cet ordre : Provider → Check Connection → Client Key → Routing → Server → Profile → test de bout en bout

Faites d’abord fonctionner une route par défaut avant d’ajouter des conditions ou des modèles fallback. Si vous configurez simultanément plusieurs fournisseurs, rewrites, retries et fallbacks, un 401, un Model ID invalide et une incompatibilité de protocole deviennent difficiles à distinguer.

Ouvrez l’interface d’administration :

ccr ui

La Web UI utilise par défaut http://127.0.0.1:3458, tandis que la passerelle de modèles utilise http://127.0.0.1:3456. Servez-vous de l’URL authentifiée affichée ou ouverte par CCR. Si 3458 est occupé, CCR peut choisir un autre port d’administration et imprimer l’adresse réelle.

1. Ajoutez l’upstream dans Providers

Choisissez un preset lorsqu’il existe ; n’utilisez un custom endpoint que si nécessaire. Dans Providers → Add Provider, sélectionnez le service, saisissez sa propre API Key, choisissez le bon protocole et ajoutez des Model ID réellement disponibles pour votre compte.

Ne déduisez pas le protocole du nom commercial du modèle. Anthropic Messages, OpenAI Chat/Responses et Gemini utilisent des formats différents. Base URL, protocole et Model ID doivent correspondre à la documentation actuelle du service upstream.

Après avoir enregistré le Provider, lancez Check Connection. Cette vérification ne couvre que l’upstream ; elle ne valide pas toute la chaîne Claude Code → CCR gateway → Routing → Provider.

2. Créez une CCR client key dans API Keys

Une CCR client key n’est pas le management token. Le management token protège la Web UI et la RPC API ; la client key authentifie les requêtes de modèle envoyées par Claude Code à la passerelle. Considérez toute URL contenant ccr_web_token comme un mot de passe et ne la collez pas dans des logs, tickets ou discussions.

3. Commencez par une route par défaut

Associez la route par défaut à un seul Provider ayant réussi Check Connection et à un modèle de ce Provider. Enregistrez la route, mais n’envoyez pas encore de requête depuis Claude Code : démarrez d’abord la passerelle et créez l’Agent Profile.

Après la réussite de la requête de bout en bout de l’étape 6, ajoutez des conditions, retries, request rewrites ou fallbacks ordonnés dans Routing. Ajoutez un comportement à la fois et recommencez la vérification. Un modèle fallback doit aussi accepter les outils, le contexte et le protocole exigés par la tâche ; deux modèles ne sont pas interchangeables simplement parce qu’ils savent dialoguer.

4. Démarrez et vérifiez la passerelle dans Server

Une UI ouverte ne prouve pas que la passerelle sur 3456 est utilisable. Dans Server, démarrez le gateway et notez l’URL côté client affichée. La valeur par défaut est http://127.0.0.1:3456 ; utilisez l’URL réelle indiquée par CCR. En cas d’échec, exécutez CCR au premier plan pour voir l’erreur :

ccr serve

La sortie au premier plan permet de distinguer un conflit de port d’un Provider incomplet, d’un modèle absent ou d’un problème de droits sur les fichiers locaux.

5. Créez et activez un Agent Profile Claude Code

La CLI actuelle lance Claude Code au moyen d’un Agent Profile activé. Dans Agent Profiles, créez un profil Claude Code, choisissez le modèle utilisé par la route par défaut du Provider ayant réussi Check Connection, enregistrez-le et activez-le. En mode CCR, Claude Code se connecte au CCR gateway affiché dans Server (par défaut http://127.0.0.1:3456), pas à l’URL du Provider upstream. Le nom est libre, par exemple Claude - Review.

Lancez-le par nom ou ID :

ccr "Claude - Review"

Placez les arguments propres à Claude Code après -- afin que CCR ne les interprète pas comme ses propres options :

ccr "Claude - Review" cli -- --model sonnet

Remplacez Claude - Review par le nom ou l’ID réel de votre profil.

6. Envoyez une requête depuis Claude Code, puis consultez Logs

C’est seulement maintenant que vous effectuez le vrai test de bout en bout. Depuis le Profile lancé, envoyez une requête simple dans Claude Code, puis vérifiez dans Logs que le Provider et le modèle attendus ont été choisis et que le statut est réussi.

Le Check Connection du Provider ne couvre que la connexion upstream. La requête réelle valide aussi la CCR client key, la passerelle, Routing, l’Agent Profile et l’appel du modèle.

Sachez distinguer ccr start, ui, serve et stop

Utilisez ccr ui ou ccr start au quotidien et ccr serve pour diagnostiquer.

Commande	Meilleur usage	Comportement
ccr start	Service persistant en arrière-plan	Démarre le service d’administration detached et la passerelle, puis affiche une URL authentifiée
ccr ui	Configuration interactive locale	Réutilise ou démarre le service en arrière-plan et ouvre la UI
ccr serve	Diagnostic ou process supervisor	Reste au premier plan et affiche les erreurs de démarrage et de requête ; ccr web est un alias
ccr stop	Recréer les options du service	Arrête le service detached lancé par start ou ui

start, ui et serve acceptent --host, --port, --open/--no-open et --gateway/--no-gateway. Leur option --port désigne le port d’administration préféré, pas automatiquement le port 3456 de la passerelle de modèles.

Corrigez « ccr: command not found » en vérifiant Node et le bin global npm

Contrôlez le runtime et le préfixe global avant de réinstaller plusieurs fois. Exécutez :

node --version
npm prefix -g

Vérifiez que Node.js est au moins en version 22 et que le répertoire global des exécutables npm figure dans le PATH du shell courant. Ouvrez un nouveau terminal après l’installation, car certains shells mettent les emplacements de commandes en cache.

Si l’application desktop est aussi installée, retenez qu’elle fournit la commande apparentée ccr-app. Le paquet npm documenté ici installe ccr ; la présence de ccr-app ne prouve pas que la CLI npm se trouve dans le PATH.

Corrigez une passerelle qui n’écoute pas sur 127.0.0.1:3456

Déterminez d’abord si le gateway n’a pas démarré ou si un autre processus possède déjà le port. Une UI saine sur 3458 ne dit rien sur 3456.

Sous macOS/Linux :

lsof -nP -iTCP:3456 -sTCP:LISTEN

Sous Windows :

netstat -ano | findstr :3456

Si un ancien processus CCR ou un autre programme occupe le port, identifiez son PID avant de l’arrêter. Lancez ensuite ccr serve, revenez dans Server et confirmez qu’un Provider, un modèle et une client key existent avant de redémarrer la passerelle.

Corrigez les erreurs 401, model not found et de protocole avec trois contrôles

Vérifiez dans l’ordre les identifiants, le protocole et le Model ID. Parmi les erreurs classiques : utiliser le management token comme client key, mettre une CCR client key dans le Provider upstream, ou appeler un endpoint Anthropic-compatible avec une route OpenAI-compatible.

Procédez ainsi :

1. Claude Code s’authentifie auprès de CCR avec une CCR client key, pas avec ccr_web_token.
2. L’entrée Provider contient l’API Key propre au service upstream.
3. Le protocole sélectionné correspond à l’endpoint.
4. Le Model ID routé existe pour ce fournisseur et ce compte.
5. Logs résout le Provider et le modèle attendus.

Ne vous fiez pas uniquement au dernier message d’erreur de Claude Code. CCR Logs peut montrer si l’échec se situe dans l’authentification client, la résolution de route, l’authentification upstream ou la requête au modèle.

Corrigez les profils introuvables et les services qui gardent d’anciennes options

Seuls les Agent Profiles activés peuvent être lancés. La correspondance des noms ignore la casse et accepte les noms normalisés, mais un nom ambigu exige l’ID. Réenregistrez le profil si son launcher généré manque.

Un processus d’arrière-plan réutilisé n’adopte pas de nouveaux réglages host, port ou gateway. Arrêtez-le puis recréez-le :

ccr stop
ccr start --host 127.0.0.1 --port 3458

C’est pourquoi une commande peut réussir alors que le service continue d’utiliser les paramètres précédents.

Utilisez ANTHROPIC_BASE_URL directement si vous n’avez qu’un endpoint

La connexion directe est généralement plus simple avec un seul endpoint Anthropic-compatible, un modèle principal et aucun besoin de route conditionnelle, fallback, logs partagés ou profils multiples. Suivez la documentation Claude Code du fournisseur pour définir ANTHROPIC_BASE_URL, sa variable d’authentification et le mapping du modèle, sans ajouter de passerelle locale.

CCR devient préférable lorsque :

• vous alternez entre DeepSeek, OpenRouter, Gemini, Kimi, Z.AI ou des endpoints personnalisés ;
• des tâches ou profils différents doivent utiliser des modèles différents ;
• vous avez besoin de retries, de conditions, de rewrites ou d’un fallback ordonné ;
• vous voulez voir les routes résolues, le statut, les tokens, la latence et les erreurs au même endroit ;
• plusieurs clients doivent partager une passerelle locale.

Situation	À privilégier
Un endpoint Anthropic-compatible stable	ANTHROPIC_BASE_URL direct
Plusieurs fournisseurs, modèles ou profils	CCR
Visibilité nécessaire sur la route de chaque requête	CCR
Chemin le plus court vers un seul service	Commencer en direct, puis migrer vers CCR si le workflow grandit

Exemple d’endpoint compatible : ajouter BetterToken dans CCR

BetterToken est un exemple possible de Provider Anthropic-compatible personnalisé, pas la seule option. Dans Providers de CCR, saisissez https://bettertoken.ai dans le champ upstream API endpoint/Base URL — et non dans la Base URL de Claude Code — sans ajouter /v1. Choisissez explicitement Anthropic Messages, ajoutez votre propre BetterToken API Key et un Model ID disponible, enregistrez le Provider, puis lancez Check Connection.

Avec CCR, Claude Code se connecte au CCR gateway affiché dans Server, généralement http://127.0.0.1:3456. Lancez l’Agent Profile, envoyez une requête et confirmez dans Logs qu’elle est routée vers le modèle BetterToken prévu. Dans ce mode, ne pointez pas Claude Code directement vers https://bettertoken.ai, sinon CCR sera contourné.

Ce n’est que si vous choisissez de contourner CCR et de vous connecter directement à cet unique endpoint que vous devez suivre la documentation BetterToken pour Claude Code et définir la Base URL sous macOS/Linux :

export ANTHROPIC_BASE_URL="https://bettertoken.ai"

Sous PowerShell :

$env:ANTHROPIC_BASE_URL="https://bettertoken.ai"

Dans ce mode direct, la variable d’authentification et le mapping de modèle restent ceux de la documentation actuelle. Ne réutilisez pas pour Claude Code la Base URL OpenAI-compatible https://www.bettertoken.ai/v1.

Protégez les secrets locaux et sauvegardez sans corrompre la base

Conservez le listener d’administration sur 127.0.0.1 sauf si l’accès distant est volontaire. Pour un accès distant, utilisez un firewall ou un réseau privé et TLS sur un reverse proxy de confiance. N’exposez pas la passerelle à l’extérieur sans CCR client keys.

Les identifiants upstream, les logs et les bases runtime se trouvent dans le répertoire local de CCR. Ne modifiez ni ne copiez config.sqlite pendant que CCR y écrit. Utilisez l’export de la UI ou arrêtez CCR avant une sauvegarde par le système de fichiers.

Vérifiez toute la chaîne, pas seulement l’interface

La réussite signifie qu’une requête Claude Code a suivi la route prévue et obtenu une réponse normale. Contrôlez :

• node --version affiche 22 ou plus récent ;
• ccr --help s’exécute ;
• Providers contient au moins un upstream ayant réussi Check Connection ;
• API Keys contient une CCR client key ;
• Server montre une passerelle active et son URL côté client (par défaut http://127.0.0.1:3456) ;
• l’Agent Profile est enregistré et activé ;
• ccr <profile-name-or-id> lance Claude Code ;
• une requête réelle a été envoyée depuis Claude Code et Logs montre le Provider, le modèle et un statut réussi ;
• chaque nouvelle route ou fallback a été retesté.

Cet ordre garde l’installation, l’authentification, le Routing et le lancement de l’agent comme des couches séparées. En cas de panne, vous corrigez la couche responsable au lieu de réinstaller CCR ou de modifier au hasard un config.json obsolète.