Configuration OmniRoute pour Cursor en 2026

Le symptôme : la même URL http://localhost:20128/v1 fonctionne dans un client, mais Claude Code renvoie une erreur d’authentification ou contourne le réseau.

La solution la plus rapide : utilisez la même instance OmniRoute, mais configurez Claude Code avec l’adresse racine sans /v1 et choisissez séparément l’entrée compatible pour Cursor Desktop ou Cursor CLI. Vérifiez ensuite le catalogue de modèles et simulez un basculement avant de considérer l’installation fiable.

Dernière mise à jour : 12 août 2026. Les commandes et conventions d’endpoint ont été vérifiées à partir de la documentation OmniRoute disponible, de la documentation officielle d’Anthropic et des documents officiels de Cursor.

Cet article s’adresse aux développeurs qui utilisent Cursor et Claude Code en parallèle, aux ingénieurs qui maintiennent un environnement d’AI Gateway sur Mac, ainsi qu’aux responsables techniques qui veulent centraliser les clés, les règles de routage et la reprise après quota.

Le même serveur, mais pas la même adresse cliente

Le piège vient d’une confusion entre deux notions :

• une instance OmniRoute commune peut servir plusieurs outils ;
• chaque client peut exiger une forme d’URL différente selon le protocole qu’il utilise.

OmniRoute écoute généralement sur http://localhost:20128 dans un déploiement local. Son interface compatible OpenAI expose notamment des chemins sous /v1, tandis que Claude Code dialogue avec une interface Anthropic Messages. La documentation OmniRoute indique donc à Claude Code d’utiliser l’adresse racine, car le client ajoute lui-même le chemin de requête. (documentation OmniRoute pour Claude Code)

Le chemin logique ressemble à ceci :

Cursor Desktop ─┐
                ├─> OmniRoute ──> Fournisseur A
Cursor CLI ─────┤              ├─> Fournisseur B
                │              └─> Fournisseur C
Claude Code ────┘

Le schéma ne signifie pas que les trois entrées acceptent le même endpoint. Cursor Desktop, Cursor CLI et MCP ne constituent pas une seule intégration interchangeable.

La documentation officielle de Cursor précise que les clés personnalisées s’appliquent aux modèles de conversation standard. Des fonctions spécialisées, comme la complétion d’onglets, peuvent continuer à utiliser les modèles intégrés de Cursor. (documentation officielle de Cursor sur les clés API)

Décision rapide

• Si vous utilisez Claude Code principalement : configurez-le directement sur l’adresse racine OmniRoute.
• Si vous utilisez Cursor CLI : testez l’option --endpoint, puis confirmez l’adresse réellement affichée par cursor-agent status. (documentation officielle de Cursor CLI)
• Si vous utilisez Cursor Desktop : ne promettez pas que toutes les fonctions passeront par OmniRoute. Validez d’abord la fonction de conversation standard.
• Si votre besoin concerne MCP : configurez le serveur MCP séparément. Ne remplacez pas son transport par une URL de modèle sans vérifier le protocole attendu.

Les premiers échecs de service

Avant de modifier Cursor ou Claude Code, vous devez prouver qu’OmniRoute fonctionne seul. Sinon, vous risquez d’attribuer au client une panne qui vient du service, de la clé ou du catalogue de modèles.

Le minimum opérationnel est le suivant :

• OmniRoute installé et lancé ;
• clé d’accès créée pour l’API d’inférence ;
• adresse de service joignable ;
• réponse de santé ;
• catalogue de modèles accessible ;
• requête de conversation minimale réussie.

La procédure doit rester courte. Évitez d’ajouter une base de données, un tunnel ou un reverse proxy avant d’avoir établi cette chaîne.

Mise en service minimale

1. Lancez OmniRoute avec la méthode recommandée par la documentation de la version utilisée. Le port local documenté dans les guides est 20128. (matrice CLI et intégrations OmniRoute)

2. Créez une clé d’inférence dans l’interface d’administration. Utilisez un espace réservé dans vos commandes et ne copiez jamais une clé réelle dans un script partagé.

3. Testez la santé du service depuis la même machine :

curl -i http://localhost:20128/health

Si votre version expose un autre chemin de santé, utilisez celui indiqué par le guide de version installé. L’objectif est d’obtenir une réponse HTTP, pas seulement de voir l’interface s’ouvrir dans un navigateur.

1. Lisez le catalogue de modèles :

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

1. Envoyez une conversation minimale avec un identifiant de modèle réellement présent dans la réponse précédente :

curl -i \
  -H "Authorization: Bearer <VOTRE_CLE_OMNIROUTE>" \
  -H "Content-Type: application/json" \
  http://localhost:20128/v1/chat/completions \
  -d '{
    "model": "<MODELE_PRESENT_DANS_LE_CATALOGUE>",
    "messages": [
      {"role": "user", "content": "Répondez uniquement par : test réussi"}
    ]
  }'

1. Conservez les trois preuves : santé, catalogue, conversation. Une page d’administration accessible ne prouve pas que l’API d’inférence accepte vos requêtes.

Une adresse localhost ne fonctionne que lorsque le client et OmniRoute se trouvent sur la même machine. Pour un Mac distant, remplacez-la par une adresse privée ou un nom résolu dans votre réseau contrôlé. N’exposez pas directement le port à Internet sans filtrage, authentification et restriction d’origine.

Pour suivre les paramètres d’accès de votre environnement MacHTML, vous pouvez consulter la documentation d’aide sur les connexions distantes avant de déplacer le service sur une autre machine.

Claude Code : l’adresse racine est la différence critique

Pour Claude Code, le point de configuration principal est ANTHROPIC_BASE_URL. Il doit viser la racine de la passerelle :

export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="<VOTRE_CLE_OMNIROUTE>"
export ANTHROPIC_MODEL="<MODELE_PRESENT_DANS_LE_CATALOGUE>"

claude

Ne renseignez pas :

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

Avec cette forme, Claude Code peut construire un chemin incorrect, par exemple une requête vers /v1/v1/messages, ou ne pas atteindre l’interface Anthropic attendue. La documentation d’Anthropic recommande également un endpoint unifié pour les passerelles, sans ajouter mécaniquement le chemin d’une API OpenAI compatible. (documentation Anthropic sur les passerelles LLM)

Les variables d’authentification ne sont pas équivalentes :

• ANTHROPIC_AUTH_TOKEN est envoyé comme jeton porteur ;
• ANTHROPIC_API_KEY constitue une autre méthode d’authentification ;
• si les deux sont définies, la priorité documentée par OmniRoute revient à ANTHROPIC_AUTH_TOKEN. (documentation OmniRoute sur Claude Code)

Après toute modification, fermez puis relancez Claude Code. Les variables sont lues au démarrage du processus. Modifier votre fichier de shell pendant qu’une session reste ouverte ne suffit donc pas.

Configuration guidée ou fichier manuel

La voie principale la plus sûre consiste à laisser OmniRoute préparer l’environnement :

omniroute launch --api-key "<VOTRE_CLE_OMNIROUTE>"

Pour cibler un modèle précis après lecture du catalogue :

omniroute setup-claude --only "<MOTIF_MODELE>"
omniroute launch --profile "<NOM_DU_PROFIL>"

La commande setup-claude génère des profils dans le répertoire de configuration de Claude Code, tandis que omniroute launch injecte les variables nécessaires au lancement. La clé n’est pas écrite dans le profil selon la documentation du projet.

L’alternative manuelle consiste à placer les variables dans settings.json :

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "<VOTRE_CLE_OMNIROUTE>",
    "ANTHROPIC_MODEL": "<ID_MODELE>"
  }
}

Utilisez une seule méthode au départ. Mélanger un profil généré, des variables de shell et une autre configuration locale complique le diagnostic de priorité.

La découverte des modèles possède aussi une limite importante. OmniRoute indique que le sélecteur natif peut ne montrer que les identifiants correspondant à certains préfixes Claude ou Anthropic, selon la version de Claude Code et la variable de découverte activée. Pour un modèle tiers, définissez explicitement ANTHROPIC_MODEL avec l’identifiant renvoyé par /v1/models.

Cursor Desktop, Cursor CLI et MCP : trois chemins différents

L’expression « configuration OmniRoute pour Cursor » est trop vague pour conduire un dépannage fiable. Vous devez d’abord identifier le produit utilisé.

Cursor Desktop

Dans Cursor Desktop, les clés personnalisées sont configurées dans les réglages de modèles. La documentation officielle indique qu’elles servent aux modèles de conversation standard. Les fonctions spécialisées peuvent continuer à utiliser les modèles internes du produit.

Cela crée deux attentes différentes :

• objectif réaliste : faire passer une conversation standard par une clé ou une entrée compatible ;
• objectif non garanti : faire passer toutes les fonctions de l’éditeur, de la complétion et de l’agent par OmniRoute.

OmniRoute propose une commande de préparation pour Cursor, mais son propre guide précise qu’elle affiche les étapes à suivre dans l’application au lieu d’écrire directement une configuration classique.

omniroute setup-cursor

Suivez ensuite les instructions affichées par la version installée. Si l’application refuse une URL personnalisée ou échoue à la validation, ne forcez pas une modification interne de sa base de configuration. Passez à Cursor CLI pour tester explicitement le chemin réseau.

Cursor CLI

Cursor CLI possède une authentification par navigateur ou par clé API. Sa documentation mentionne également l’option --endpoint pour un endpoint personnalisé.

Exemple de contrôle :

export CURSOR_API_KEY="<VOTRE_CLE_CURSOR_OU_PASSERELLE>"

cursor-agent status

cursor-agent \
  --endpoint "http://localhost:20128" \
  "Répondez uniquement par : connexion validée"

La syntaxe exacte du chemin dépend de la version de Cursor CLI et de l’entrée attendue par OmniRoute. Utilisez cursor-agent --help et la sortie de omniroute setup-cursor comme référence locale. L’erreur à éviter consiste à déduire que le suffixe /v1 utilisé par une requête OpenAI doit être copié tel quel dans chaque option Cursor.

MCP

MCP est une voie distincte. Il sert à relier un client à des outils ou à des serveurs de contexte. Il ne transforme pas automatiquement Cursor Desktop en client compatible avec l’API de modèles OmniRoute.

Si vous mélangez ces trois chemins dans un même ticket d’incident, vous perdez la cause réelle. Notez le client, son processus, son endpoint et sa méthode d’authentification avant chaque test.

Le fallback multi-modèle ne se vérifie pas avec une seule clé

Un modèle qui répond ne prouve pas que le routage automatique fonctionne. Il prouve seulement que la chaîne client → OmniRoute → fournisseur sélectionné accepte une requête.

Il faut distinguer :

• connexion directe : un modèle et un fournisseur sont choisis ;
• routage automatique : OmniRoute sélectionne une cible selon ses règles ;
• fallback multi-modèle : une cible secondaire est appelée après une erreur ou une indisponibilité de la cible principale.

Pour observer un basculement, vous devez disposer d’au moins deux cibles réellement utilisables. Les identifiants, clés et règles doivent être configurés avant le test.

Scénario de panne reproductible

1. Choisissez un modèle principal et un modèle secondaire.
2. Vérifiez que les deux apparaissent dans /v1/models ou dans la configuration de routage.
3. Envoyez une requête avec le modèle principal explicitement sélectionné.
4. Désactivez temporairement sa clé, son fournisseur ou sa route, selon le mécanisme prévu par OmniRoute.
5. Renvoyez exactement la même requête.
6. Vérifiez les journaux, la décision de routage et l’identifiant du modèle final.
7. Réactivez la cible principale et confirmez le retour à l’état normal.

OmniRoute annonce dans sa documentation une couverture étendue de fournisseurs et des fonctions de routage et de reprise. Ces chiffres et bénéfices restent des déclarations du projet, pas une mesure indépendante. Ne les utilisez pas comme garantie de disponibilité ou de qualité pour votre équipe. (fonctionnalités annoncées par OmniRoute)

Expérience de dépannage : quand le fallback « ne se déclenche pas », commencez par vérifier l’erreur exacte. Une réponse lente, une limite de contexte et un quota épuisé ne sont pas nécessairement traités par la même règle de routage.

Le déploiement distant sur Mac

Pour un test individuel, laissez OmniRoute et les clients sur le même Mac. Cette approche réduit les variables : pas de DNS interne, pas de pare-feu inter-machine et pas de tunnel à maintenir.

Le déploiement distant devient pertinent lorsque vous avez besoin :

• d’un service disponible même lorsque votre portable est fermé ;
• d’un point d’accès partagé entre plusieurs outils ;
• d’une adresse stable pour des tâches longues ;
• d’une séparation entre les clés de fournisseurs et les postes utilisateurs.

La migration suit une logique simple :

1. Installez OmniRoute sur le Mac qui restera allumé.
2. Écoutez uniquement sur l’interface réseau nécessaire.
3. Créez une clé distincte pour chaque utilisateur ou environnement.
4. Autorisez uniquement les adresses ou le réseau privé requis.
5. Testez /health, /v1/models et une conversation depuis le Mac client.
6. Configurez Claude Code avec l’adresse racine distante, sans /v1.
7. Configurez Cursor CLI avec son option d’endpoint et vérifiez son statut.
8. Redémarrez OmniRoute et répétez la séquence de validation.
9. Testez une coupure du fournisseur principal avant d’autoriser les tâches longues.

Pour un environnement distant, documentez séparément le chemin du client et celui de la passerelle. Une erreur de réseau peut produire le même message qu’une erreur de clé, alors que le correctif n’est pas le même.

Vous pouvez consulter la console MacHTML pour organiser l’accès à un environnement distant, puis comparer les scénarios d’usage disponibles avant de déplacer un service permanent.

La réception avant les tâches longues

Ne validez pas l’installation avec une seule réponse courte. Une passerelle peut réussir une conversation simple et échouer ensuite sur la durée, le changement de modèle ou le redémarrage.

Utilisez cette liste de décision :

• Si Claude Code répond avec l’adresse racine et la clé dédiée, gardez cette voie comme intégration principale.
• Si Cursor Desktop valide seulement les conversations standard, limitez votre promesse à ce périmètre.
• Si Cursor CLI accepte l’endpoint et retourne le modèle attendu, utilisez-le pour les automatisations et les tests reproductibles.
• Si le catalogue est vide, revenez à la santé du service, à la validation des fournisseurs et aux permissions.
• Si le fallback ne change pas de modèle pendant l’incident, ne lancez pas de tâche longue ; corrigez la route et répétez l’exercice.
• Si le Mac local dort ou change souvent de réseau, déplacez OmniRoute vers un Mac distant contrôlé.
• Si vous avez besoin d’interfaces physiques, de performances locales constantes ou d’un traitement lourd permanent, étudiez plutôt un Mac dédié que la location temporaire.

Le point essentiel est de conserver la différence entre disponibilité et compatibilité. Un service accessible n’implique pas que chaque fonction de Cursor utilise ce service. De même, un modèle visible dans un catalogue ne signifie pas que Claude Code l’affichera dans son sélecteur natif.

Votre solution actuelle — appels directs depuis Cursor et Claude Code — reste simple, mais elle duplique les clés, les règles de sélection et les procédures de récupération. Elle devient aussi plus difficile à auditer lorsque les deux outils utilisent des chemins différents et que les quotas sont gérés séparément. Un OmniRoute local corrige cette centralisation, mais vous restez dépendant de la disponibilité de votre Mac et de votre réseau. Pour un test court, c’est souvent le meilleur choix. Pour un usage continu, multi-appareils ou partagé par une petite équipe, un environnement Mac distant et toujours accessible offre une exploitation plus prévisible.

Une fois le test local terminé, comparez votre besoin d’accès ponctuel avec celui d’un environnement qui doit rester actif pendant vos tâches de développement, d’audio, de vidéo ou de design. Si votre machine s’endort, si votre réseau change régulièrement ou si plusieurs développeurs doivent utiliser le même point d’entrée, évaluez alors la location d’un Mac distant plutôt que de maintenir un poste personnel allumé en permanence.