Installer OmniRoute & Claude Code

🚀 OmniRoute & Claude Code : le guide ultime pour booster votre workflow IA sur Linux

🐧 Compatible avec la plupart des distributions Linux

Vous utilisez plusieurs modèles d’intelligence artificielle et vous aimeriez les exploiter depuis un seul outil de développement ?

Dans ce tutoriel, nous allons mettre en place OmniRoute + Claude Code afin de créer une passerelle locale capable de centraliser plusieurs fournisseurs d’IA et de les exposer derrière une interface unique.

L’objectif est simple :

Claude Code → OmniRoute → votre Combo → plusieurs modèles IA

Vous pourrez ainsi utiliser Claude Code depuis votre terminal Linux tout en faisant transiter les requêtes par OmniRoute et ses différents fournisseurs.

📋 Sommaire

  1. Introduction
  2. Prérequis
  3. Installer Node.js et npm
  4. Installer et démarrer OmniRoute
  5. Connecter vos fournisseurs d’IA
  6. Créer un Combo
  7. Créer une clé API OmniRoute
  8. Installer Claude Code
  9. Configurer Claude Code avec OmniRoute
  10. Vérifier le fonctionnement
  11. Sécurité : les bonnes pratiques
  12. Dépannage
  13. Pour aller plus loin
  14. Conclusion

1. 🧠 Introduction

Qu’est-ce qu’OmniRoute ?

OmniRoute est une passerelle IA locale qui permet de centraliser plusieurs fournisseurs et modèles derrière un même point d’accès.

Au lieu de configurer séparément chaque outil avec plusieurs clés API, OmniRoute sert d’intermédiaire :

                  ┌─────────────────────┐
                  │     Claude Code     │
                  └──────────┬──────────┘
                             │
                             ▼
                  ┌─────────────────────┐
                  │      OmniRoute      │
                  │   Gateway locale    │
                  └──────────┬──────────┘
                             │
                 ┌───────────┼───────────┐
                 ▼           ▼           ▼
             NVIDIA       Ollama      Free AI
              NIM          Cloud       / autres

OmniRoute peut également gérer des Combos, c’est-à-dire des configurations permettant d’associer plusieurs modèles et de définir une stratégie de routage ou de fallback.

Et Claude Code ?

Claude Code est l’outil CLI d’Anthropic permettant d’utiliser un agent de développement directement depuis le terminal.

Il peut notamment :

  • analyser un projet ;
  • lire et modifier des fichiers ;
  • rechercher du code ;
  • exécuter des commandes ;
  • corriger des erreurs ;
  • travailler avec Git ;
  • automatiser certaines tâches de développement.

Anthropic documente officiellement l’installation de Claude Code via npm et recommande de ne pas utiliser sudo npm install -g.

🎯 Ce que nous allons obtenir

À la fin de ce tutoriel :

Claude Code
     │
     ▼
OmniRoute
     │
     ▼
nawre-combo1
     │
     ├── NVIDIA / Nemotron
     ├── Qwen Coder
     └── autre modèle

L’intérêt est de pouvoir modifier les modèles utilisés par le Combo sans devoir reconfigurer Claude Code à chaque changement.

⏱️ Temps estimé : 15 à 30 minutes
🎯 Niveau : intermédiaire
🐧 Distribution : Debian, Ubuntu, Fedora, Arch, openSUSE et dérivées

2. 🧰 Prérequis

Avant de commencer, vérifiez que vous disposez de :

  • une distribution Linux à jour ;
  • un accès Internet ;
  • un compte utilisateur avec sudo si nécessaire pour installer les paquets système ;
  • Node.js 18 ou supérieur ;
  • npm ;
  • les éventuels comptes ou clés API des fournisseurs que vous souhaitez utiliser.

Claude Code nécessite actuellement Node.js 18+ dans son installation npm.

Vérifiez votre environnement :

node --version
npm --version

Si les deux commandes fonctionnent, vous pouvez passer à l’étape suivante.

3. 📦 Installer Node.js et npm

La méthode dépend de votre distribution.

Debian / Ubuntu

sudo apt update
sudo apt install nodejs npm

Puis :

node --version
npm --version

Fedora / RHEL

sudo dnf install nodejs npm

Arch Linux / Manjaro

sudo pacman -S nodejs npm

openSUSE Tumbleweed / Leap

sudo zypper install nodejs npm

Puis :

node --version
npm --version

⭐ Alternative : nvm

Si votre distribution fournit une version trop ancienne de Node.js, nvm (Node Version Manager) est une excellente alternative.

Il permet d’installer et de changer facilement de version de Node.js sans modifier les paquets système.

Après installation de nvm, installez la version LTS :

nvm install --lts
nvm use --lts

Vérifiez :

node --version
npm --version

💡 Conseil : pour une machine personnelle Linux, nvm est particulièrement pratique si vous utilisez régulièrement plusieurs outils basés sur Node.js.

4. 🚀 Installer et démarrer OmniRoute

L’installation d’OmniRoute via npm est très simple.

npm install -g omniroute

Vérifiez l’installation :

omniroute --version

Puis démarrez OmniRoute :

omniroute

OmniRoute démarre normalement sur le port 20128 et fournit son interface Web locale ainsi que son API.

Ouvrez ensuite votre navigateur sur :

http://localhost:20128

🔐 Sécurité : le service est utilisé localement dans ce tutoriel. Ne rendez pas inutilement le port OmniRoute accessible depuis Internet.

5. 🔌 Connecter vos fournisseurs d’IA

Une fois le tableau de bord ouvert :

Dashboard → Providers

Ajoutez ensuite les fournisseurs que vous souhaitez utiliser.

Selon votre configuration, vous pouvez par exemple utiliser :

  • NVIDIA NIM ;
  • Ollama / Ollama Cloud ;
  • OpenAI ;
  • Mistral ;
  • Groq ;
  • différents fournisseurs gratuits ;
  • d’autres fournisseurs compatibles avec OmniRoute.

La méthode dépend du fournisseur :

Fournisseur
     ↓
Authentification
     ↓
Clé API / OAuth
     ↓
Modèle disponible
     ↓
OmniRoute

⚠️ Ne publiez jamais vos clés API.

Évitez notamment :

  • les captures d’écran montrant une clé ;
  • les dépôts Git publics ;
  • les fichiers .env envoyés sur GitHub ;
  • les copier-coller sur les forums ;
  • les scripts contenant directement vos clés.

Une clé API doit être considérée comme un secret, au même titre qu’un mot de passe.

6. 🧩 Créer un Combo puissant

Le Combo est l’une des fonctionnalités intéressantes d’OmniRoute.

L’idée est de définir une configuration permettant d’utiliser plusieurs modèles selon votre stratégie.

Dans le Dashboard :

Combos → Create Combo

Créez par exemple :

Nom : nawre-combo1

Vous pouvez ensuite construire une configuration de ce type :

Modèle Utilisation
NVIDIA Nemotron Raisonnement / analyse
Qwen Coder Programmation
Gemma Rapidité / synthèse

Exemple de stratégie

                    nawre-combo1
                         │
              ┌──────────┼──────────┐
              ▼          ▼          ▼
          Nemotron    Qwen Coder   Gemma
          Raisonnement   Code       Synthèse

Les modèles réellement disponibles dépendent évidemment de vos fournisseurs et de votre configuration OmniRoute.

💡 Conseil : ne cherchez pas forcément à mettre le plus grand nombre de modèles possible dans un Combo.

Un bon Combo doit surtout avoir une stratégie cohérente :

  • qualité ;
  • spécialisation ;
  • rapidité ;
  • coût ;
  • disponibilité ;
  • fallback.

7. 🔑 Créer une clé API OmniRoute

Une fois vos fournisseurs configurés, vous devez créer une clé permettant à vos outils de communiquer avec OmniRoute.

Dans le Dashboard, rendez-vous dans la section :

Endpoints / API Keys

⚠️ Le nom exact de la section peut varier selon la version d’OmniRoute.

Créez une nouvelle clé.

Vous obtiendrez une clé ressemblant à :

sk-xxxxxxxxxxxxxxxxxxxxxxxx

ou à un autre format selon la version d’OmniRoute.

Important

Cette clé est votre clé OmniRoute.

Ce n’est :

  • ni votre clé NVIDIA ;
  • ni votre clé OpenAI ;
  • ni votre clé Anthropic ;
  • ni votre mot de passe.

Elle permet à votre client, ici Claude Code, de s’authentifier auprès de votre instance OmniRoute.

8. 🤖 Installer Claude Code

Anthropic recommande actuellement l’installation via npm :

npm install -g @anthropic-ai/claude-code

⚠️ N’utilisez pas sudo npm install -g.

Vérifiez ensuite :

claude --version

Vous pouvez également lancer :

claude doctor

Cette commande permet de vérifier l’installation et l’environnement Claude Code.

9. ⚙️ Configurer Claude Code avec OmniRoute

Il existe plusieurs méthodes pour connecter Claude Code à OmniRoute.

⭐ Méthode recommandée : configuration OmniRoute

Les versions récentes d’OmniRoute proposent des commandes permettant de préparer automatiquement la configuration Claude Code.

Vous pouvez notamment utiliser :

omniroute setup-claude

Puis lancer un profil avec :

omniroute launch

OmniRoute peut ainsi préparer les profils Claude Code et injecter automatiquement les paramètres nécessaires.

C’est la méthode que je recommande si votre version d’OmniRoute la prend en charge.

🛠️ Méthode manuelle

Pour comprendre réellement ce qui se passe, il est intéressant de connaître la configuration manuelle.

Claude Code utilise notamment :

ANTHROPIC_BASE_URL
ANTHROPIC_AUTH_TOKEN
ANTHROPIC_MODEL

Pour OmniRoute, le point important est le suivant :

ANTHROPIC_BASE_URL=http://localhost:20128

⚠️ Ne pas ajouter /v1

Pour Claude Code, OmniRoute utilise la racine du endpoint Anthropic :

http://localhost:20128

et non :

http://localhost:20128/v1

Le /v1 est utilisé pour les interfaces compatibles OpenAI, alors que Claude Code utilise l’interface Anthropic.

🔐 Créer un fichier de configuration séparé

Pour éviter de mettre directement votre clé dans votre .bashrc, nous allons créer un fichier dédié.

touch ~/.omniroute.env
chmod 600 ~/.omniroute.env

Éditez-le :

nano ~/.omniroute.env

Ajoutez :

# ============================================================
# OmniRoute + Claude Code
# ============================================================

export CLAUDE_CONFIG_DIR="$HOME/.claude-omniroute"

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

export ANTHROPIC_AUTH_TOKEN="VOTRE_CLE_OMNIROUTE_ICI"

export ANTHROPIC_MODEL="nawre-combo1"

export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

Enregistrez puis quittez.

Protégez le fichier :

chmod 600 ~/.omniroute.env

Puis chargez-le :

source ~/.omniroute.env

🔎 À quoi servent ces variables ?

CLAUDE_CONFIG_DIR

CLAUDE_CONFIG_DIR="$HOME/.claude-omniroute"

Permet d’utiliser un dossier de configuration séparé pour cette instance/profil de Claude Code.

C’est particulièrement intéressant si vous utilisez plusieurs configurations.

OmniRoute utilise également ce mécanisme pour ses profils Claude Code.

ANTHROPIC_BASE_URL

ANTHROPIC_BASE_URL="http://localhost:20128"

Indique à Claude Code de communiquer avec OmniRoute au lieu de l’API Anthropic directement.

ANTHROPIC_AUTH_TOKEN

ANTHROPIC_AUTH_TOKEN="VOTRE_CLE_OMNIROUTE"

Il s’agit de la clé permettant à Claude Code de s’authentifier auprès d’OmniRoute.

OmniRoute recommande cette variable pour Claude Code ; ANTHROPIC_API_KEY reste également supportée comme méthode alternative.

ANTHROPIC_MODEL

ANTHROPIC_MODEL="nawre-combo1"

Indique le modèle ou Combo à utiliser.

Remplacez nawre-combo1 par le nom réellement utilisé dans votre installation.

CLAUDE_CODE_MAX_OUTPUT_TOKENS

CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

Définit une limite maximale de tokens générés par réponse.

💡 Cette valeur dépend de la capacité réelle du modèle et du gateway. Si un modèle ne supporte pas cette taille de sortie, utilisez une valeur plus faible.

🔄 Charger automatiquement la configuration

Pour charger le fichier automatiquement avec Bash :

echo '[ -f ~/.omniroute.env ] && source ~/.omniroute.env' >> ~/.bashrc

Puis :

source ~/.bashrc

Si vous utilisez Zsh :

echo '[ -f ~/.omniroute.env ] && source ~/.omniroute.env' >> ~/.zshrc

💡 Si vous utilisez Fish, la gestion des variables d’environnement est différente. Dans ce cas, préférez la configuration native de Claude Code/OmniRoute plutôt que de recopier cette méthode Bash.

10. 🧪 Vérification finale

Nous allons maintenant vérifier chaque élément séparément.

Étape 1 — OmniRoute

Vérifiez que le processus fonctionne :

pgrep -af omniroute

Vous pouvez également tester son API :

curl http://localhost:20128/v1/models

Si une clé est nécessaire sur votre configuration :

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer VOTRE_CLE_OMNIROUTE"

Vous devriez obtenir la liste des modèles disponibles.

OmniRoute documente l’endpoint /v1/models comme méthode de vérification de l’API.

Étape 2 — Vérifier les variables

echo "$ANTHROPIC_BASE_URL"

Vous devez obtenir :

http://localhost:20128

Puis :

echo "$ANTHROPIC_MODEL"

Vous devez obtenir :

nawre-combo1

Pour vérifier que la clé est définie sans l’afficher :

if [ -n "$ANTHROPIC_AUTH_TOKEN" ]; then
    echo "Clé OmniRoute chargée"
else
    echo "Clé OmniRoute absente"
fi

Étape 3 — Tester Claude Code

Placez-vous dans un dossier de test :

mkdir -p ~/claude-test
cd ~/claude-test

Puis :

claude "Dis-moi bonjour en une phrase."

Si tout fonctionne :

Claude Code
     ↓
OmniRoute
     ↓
nawre-combo1
     ↓
Fournisseur / modèle
     ↓
Réponse

🎉 Votre chaîne IA est opérationnelle.

11. 🔐 Sécurité : les bonnes pratiques

Comme nous manipulons plusieurs clés API, quelques règles sont importantes.

Ne mettez jamais votre clé directement dans Git

Ajoutez votre fichier de configuration aux exclusions :

echo ".omniroute.env" >> ~/.gitignore

Si votre fichier se trouve dans un projet Git, ajoutez également :

echo ".omniroute.env" >> .gitignore

Vérifiez les permissions

ls -l ~/.omniroute.env

Vous devriez obtenir quelque chose ressemblant à :

-rw------- 1 utilisateur utilisateur ...

Cela correspond à :

600

Le propriétaire peut :

  • lire ;
  • écrire.

Les autres utilisateurs ne peuvent rien faire.

Ne partagez jamais votre clé

Même si quelqu’un vous demande simplement :

« Envoie-moi ta clé pour vérifier que ça fonctionne. »

Ne le faites pas.

Pour demander de l’aide, remplacez toujours la clé par :

sk-***************

🔥 Ne publiez pas OmniRoute inutilement

Si OmniRoute tourne uniquement sur votre machine, utilisez :

localhost

plutôt qu’une adresse réseau accessible depuis d’autres machines.

Si vous exposez OmniRoute sur un réseau ou un serveur distant, vous devez alors considérer :

  • authentification ;
  • TLS/HTTPS ;
  • pare-feu ;
  • contrôle d’accès ;
  • rotation des clés ;
  • logs ;
  • limitation du débit.

12. 🛠️ Dépannage

omniroute: command not found

Vérifiez :

which omniroute

Puis :

npm prefix -g

Si votre installation utilise ~/.local, vérifiez :

echo "$PATH"

Vous pouvez également rechercher le binaire :

find ~/.local -name omniroute 2>/dev/null

Rechargez ensuite votre shell :

source ~/.bashrc

claude: command not found

Vérifiez :

which claude

Puis :

npm prefix -g

Si nécessaire, rechargez votre environnement :

source ~/.bashrc

Puis :

claude --version

Le Dashboard OmniRoute ne s’ouvre pas

Vérifiez qu’OmniRoute est lancé :

pgrep -af omniroute

Vérifiez également le port :

ss -ltnp | grep 20128

Puis essayez :

http://localhost:20128

Claude Code utilise directement Anthropic

Vérifiez :

echo "$ANTHROPIC_BASE_URL"

La valeur doit être :

http://localhost:20128

Vérifiez également :

echo "$ANTHROPIC_MODEL"

Si vous venez de modifier les variables d’environnement, redémarrez Claude Code. Les variables sont lues au démarrage de Claude Code.

Erreur d’authentification

Vérifiez que :

echo "$ANTHROPIC_AUTH_TOKEN"

contient bien la clé OmniRoute.

Ne mettez pas ici :

  • votre clé Anthropic ;
  • votre clé NVIDIA ;
  • votre clé OpenAI ;
  • votre mot de passe.

Le modèle n’est pas trouvé

Listez les modèles exposés par OmniRoute :

curl http://localhost:20128/v1/models

Vérifiez ensuite le nom utilisé dans :

echo "$ANTHROPIC_MODEL"

Le nom doit correspondre à un modèle ou à un Combo réellement disponible dans votre instance OmniRoute.

13. 🚀 Pour aller plus loin

Maintenant que la base fonctionne, vous pouvez aller beaucoup plus loin.

Créer plusieurs Combos

Par exemple :

nawre-code
    ↓
Modèles spécialisés programmation

nawre-research
    ↓
Modèles spécialisés analyse / raisonnement

nawre-fast
    ↓
Modèles rapides et économiques

Cela permet d’adapter votre environnement IA à votre tâche.

Utiliser les profils Claude Code

OmniRoute permet de créer des profils Claude Code séparés avec :

omniroute setup-claude

Puis de lancer un profil spécifique :

omniroute launch --profile NOM_DU_PROFIL

Cette approche est particulièrement intéressante si vous utilisez plusieurs modèles ou plusieurs configurations.

Exploiter le fallback

L’un des intérêts d’une gateway est de pouvoir prévoir un modèle de secours.

Par exemple :

Modèle principal
      ↓
indisponible
      ↓
Modèle secondaire
      ↓
indisponible
      ↓
Modèle de secours

Cela permet de limiter les interruptions lorsqu’un fournisseur rencontre une panne, une limite de quota ou une saturation.

Surveiller les coûts

Même si OmniRoute est installé localement, les fournisseurs utilisés derrière OmniRoute peuvent être payants.

Pensez donc à surveiller :

  • les tokens ;
  • les quotas ;
  • les limites API ;
  • les coûts ;
  • les modèles réellement utilisés.

Un Combo intelligent n’est pas forcément celui qui utilise systématiquement le modèle le plus puissant.

14. 🧭 Conclusion

Avec OmniRoute + Claude Code, vous disposez d’une architecture particulièrement intéressante pour un poste Linux :

                    🐧 Linux
                       │
                       ▼
                 Claude Code
                       │
                       ▼
                  OmniRoute
                       │
              ┌────────┼────────┐
              ▼        ▼        ▼
           NVIDIA    Qwen     Ollama
              │        │        │
              └────────┼────────┘
                       ▼
                    Réponse

L’intérêt principal n’est pas simplement d’avoir « plusieurs IA ».

C’est surtout de centraliser leur utilisation et de pouvoir modifier votre stratégie de routage sans reconfigurer chaque outil individuellement.

Pour un utilisateur Linux qui aime maîtriser son environnement, cette architecture est particulièrement intéressante :

  • 🐧 Linux en environnement local ;
  • 🔐 clés API maîtrisées ;
  • 🧩 plusieurs fournisseurs ;
  • 🚀 routage centralisé ;
  • 🔄 possibilité de fallback ;
  • 🤖 Claude Code depuis le terminal ;
  • 🛠️ configuration adaptée à vos besoins.

Et surtout, vous pouvez faire évoluer votre architecture progressivement.

Commencez avec un fournisseur + un modèle, puis ajoutez progressivement d’autres modèles et créez vos propres Combos.

📚 Ressources officielles

OmniRoute : documentation et dépôt du projet.

Claude Code : documentation officielle Anthropic.

Conseil : OmniRoute évoluant rapidement, vérifiez toujours la documentation correspondant à votre version avant de reprendre une commande ou une variable de configuration.

🐧 Guide créé pour la communauté Linux & Open Source

Article réalisé sous Linux — avec une attention particulière portée à la sécurité, au contrôle des clés API et aux bonnes pratiques du terminal.

Propulsé par OmniRoute & Claude Code.

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *