Installer OmniRoute : démarrage rapide et Claude Code

OmniRoute est une passerelle d’IA compatible OpenAI. Elle place de nombreux fournisseurs de modèles en amont derrière une seule API locale : Claude Code, Codex CLI, les extensions d’IDE et vos propres scripts n’ont donc besoin d’être configurés qu’une seule fois. Cette page est le chemin le plus court entre l’installation et une première requête réussie ; les guides thématiques complets sont hébergés sur un site dédié.

Retenez ces deux adresses

• Tableau de bord : http://localhost:20128
• URL de base compatible OpenAI : http://localhost:20128/v1

Les clients se configurent avec la seconde, pas avec l’adresse du tableau de bord.

Prérequis

• Node.js >=22.22.2 <23 ou >=24.0.0 <27 ; Node.js 24 LTS est recommandé. En dehors de cette plage, le tableau de bord peut afficher une page blanche ou des erreurs de module natif. Installez Node.js d’abord si nécessaire.
• Le port local 20128 est libre.
• Au moins un compte ou une clé de fournisseur en amont que vous comptez router via OmniRoute.

Installer et démarrer

Choisissez une méthode :

# npm (recommandé)
npm install -g omniroute
omniroute

# Docker
docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest

Vous pouvez aussi télécharger un installateur Desktop pour Windows, macOS ou Linux depuis OmniRoute GitHub Releases. :latest pointe vers la dernière version stable publiée ; fixez une version précise lorsque vous avez besoin de déploiements reproductibles.

Après le démarrage, ouvrez http://localhost:20128. Le mot de passe de connexion est contrôlé par la variable d’environnement INITIAL_PASSWORD ; dans la configuration d’auto-hébergement en amont, il est généré au premier démarrage et affiché dans les journaux, et avec Docker vous pouvez le retrouver avec docker logs omniroute | grep -i password. Définissez votre propre mot de passe robuste avant d’exposer le service à un réseau.

Connecter un fournisseur et créer une clé

1. Dans le tableau de bord, allez dans Providers → Add Provider et connectez votre fournisseur.
2. Sur la page API Keys, créez une nouvelle clé et conservez-la, car elle n’est affichée qu’une seule fois. Cette clé sert aux clients pour accéder à OmniRoute ; ce n’est pas une clé de fournisseur en amont.

La documentation en amont mentionne quelques fournisseurs gratuits qui n’exigent pas de clé. Leur disponibilité et leurs conditions changent : vérifiez les conditions de chaque service avant de vous y fier.

Vérifier le service

export OMNIROUTE_API_KEY="collez la clé créée sur la page API Keys"

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}"

Une liste de modèles signifie que le point de terminaison compatible OpenAI et l’authentification fonctionnent. Envoyez ensuite une requête de chat minimale pour confirmer qu’un modèle peut réellement être routé :

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "Reply with ok." }]
  }'

auto laisse OmniRoute choisir un fournisseur selon la vitesse, le coût et la disponibilité. Vous pouvez aussi utiliser un identifiant de modèle précis renvoyé par /v1/models.

Connecter vos outils

Dans tout outil qui parle le format OpenAI, saisissez :

Base URL: http://localhost:20128/v1
API Key:  la clé OmniRoute que vous avez créée
Model:    auto

OmniRoute fournit aussi des lanceurs en une commande, par exemple omniroute launch-codex --model auto ; la forme générique omniroute run <target> prend en charge claude, codex, aider, goose, opencode, qwen et gemini. Si vous voulez utiliser un Agent CLI dans HagiCode, configurez-le d’abord avec Installation des AI Agent CLI.

Problèmes courants

• Tableau de bord blanc ou avertissement de version de Node.js non prise en charge : passez à Node.js 24 LTS, relancez npm install -g omniroute, puis omniroute.
• better-sqlite3 introuvable avec npm 11 : npm 11 bloque par défaut les scripts d’installation des dépendances optionnelles ; recompilez-le à la main en suivant le guide de dépannage.
• slice is not valid mach-o file sur macOS : exécutez npm rebuild better-sqlite3 dans $(npm root -g)/omniroute/app, puis redémarrez.

Documentation complète

Ouvrir la documentation d'OmniRoute en français

• Démarrage rapide : OmniRoute en 3 minutes
• Configurer OmniRoute pour Claude Code
• Déployer OmniRoute avec Docker
• Configurer OmniRoute pour Codex CLI
• Dépannage