Connecter Cursor à OpenRouter : configuration, limites fonctionnelles et dépannage
Guide de configuration de Cursor avec OpenRouter, preuve du routage via Activity, tests séparés de Chat, Agent, Tab et tools, et diagnostic des endpoints, modèles, crédits et limites.
Sommaire
Le point essentiel est le suivant : une réponse dans Cursor ne prouve pas que toutes les fonctions utilisent OpenRouter. Au 4 octobre 2026, OpenRouter indique toujours que l’intégration Cursor est en Beta et impose le Base URL dédié https://openrouter.ai/api/v1/cursor. Les requêtes de modèle dans Chat et Agent peuvent emprunter cette route si vous choisissez manuellement un modèle OpenRouter. Tab Completion n’utilise pas la clé personnalisée, et les tools exigent à la fois le bon endpoint et un modèle compatible avec tools.
Le bon test d’acceptation est une chaîne de preuves : paramètres corrects → modèle sélectionné manuellement → requête minimale → entrée correspondante dans OpenRouter Activity → tests séparés d’Agent et des tools. Ce guide s’appuie sur la documentation officielle actuelle et ne prétend pas avoir testé un compte, une clé ou une version précise de Cursor de bout en bout.
Quelles fonctions utilisent réellement la clé personnalisée ?
| Fonction Cursor | Routage attendu | Limite importante | Vérification recommandée |
|---|---|---|---|
| Modèle choisi manuellement dans Chat ou Ask | Généralement OpenRouter | Le modèle doit être disponible via l’endpoint OpenAI-compatible | Envoyer un prompt minimal et comparer l’heure et le modèle dans Activity |
| Modèle choisi manuellement dans Agent | L’appel du modèle passe généralement ; chaque action interne n’est pas démontrée | La documentation couvre le sélecteur Agent, pas toutes les requêtes auxiliaires | Observer l’entrée Activity et les actions de tools visibles dans Cursor |
| Tab Completion | Non | Tab continue d’utiliser les modèles intégrés de Cursor | Ne pas utiliser une suggestion Tab comme preuve d’OpenRouter |
| Tools dans Agent | Conditionnel | Il faut /cursor et un modèle prenant en charge tools | Valider Chat, puis exécuter une tâche en lecture seule |
| Sélection automatique | Mauvaise preuve d’acceptation | Le client peut choisir une autre route | Désactiver Auto et sélectionner explicitement le modèle ajouté |
Il faut distinguer la requête au modèle de l’exécution de l’outil. La documentation tool calling d’OpenRouter précise que le modèle propose l’appel et que le client exécute l’outil. Une entrée Activity prouve le passage de la requête modèle par OpenRouter, mais pas que la lecture d’un fichier ou une commande locale a été exécutée sur OpenRouter.
Préparer la configuration
- Une version récente de Cursor avec
Cursor Settings→Models→API Keys. - Votre propre API Key OpenRouter, jamais copiée dans un chat, dépôt, screenshot ou message de support.
- Le Model ID exact copié depuis le catalogue OpenRouter actuel.
- Pour les tools d’Agent, un modèle confirmé dans le filtre des modèles compatibles.
Les libellés peuvent varier selon la version : activer, enregistrer, confirmer ou vérifier. La relation reste la même : clé dans OpenAI API Key, endpoint dans Override OpenAI Base URL, modèle avec l’ID OpenRouter complet.
Configurer Cursor dans le bon ordre
1. Ouvrir les paramètres API Keys
Allez dans Cursor Settings → Models, développez API Keys et repérez OpenAI API Key ainsi que Override OpenAI Base URL.
2. Saisir la clé OpenRouter
Collez la clé créée dans votre compte OpenRouter dans OpenAI API Key. Utilisez uniquement l’interface de réglages et terminez l’action d’enregistrement, d’activation ou de validation proposée.
3. Utiliser l’endpoint dédié à Cursor
Activez Override OpenAI Base URL et saisissez :
https://openrouter.ai/api/v1/cursor
N’utilisez pas le générique https://openrouter.ai/api/v1 et n’ajoutez pas /chat/completions. L’endpoint /cursor normalise le format Cursor ; le générique peut provoquer des échecs de tools et d’autres formats.
4. Ajouter le Model ID exact
Dans Models, choisissez + Add model et copiez l’ID complet depuis la page actuelle du modèle. Pour un router alias, copiez la syntaxe complète. Évitez les noms commerciaux, abréviations ou anciens tutoriels.
5. Choisir le modèle manuellement
Revenez dans Chat ou Agent et sélectionnez explicitement le modèle ajouté. Pour le premier test, n’utilisez pas la sélection automatique : une réponse ne révélerait pas la route utilisée.
Prouver que la configuration est active
Envoyez dans Chat une requête minimale sans code ni secret, par exemple une phrase fixe. Ouvrez immédiatement OpenRouter Activity et vérifiez :
- l’heure correspond au test ;
- le modèle enregistré correspond au Model ID choisi ;
- la requête a réussi et comporte des données d’usage ;
- la preuve interne ne contient ni clé, ni prompt complet, ni code sensible.
La réponse dans Cursor est une preuve faible ; une entrée Activity correspondante est une preuve de routage plus forte. Si Cursor répond sans entrée correspondante, considérez le routage comme non confirmé.
Pour une équipe, conservez uniquement l’heure, le modèle, le statut, l’identifiant nécessaire, la version de Cursor et le mode de test. Cela facilite un nouveau contrôle si le comportement Beta change.
Tester Chat, Agent, Tab et tools séparément
Chat : établir une base
Choisissez le modèle manuellement et envoyez un prompt court et déterministe. Chat n’est validé qu’après l’apparition de l’entrée Activity. En cas d’échec, ne passez pas encore à Agent, qui ajoute contexte, autorisations et outils.
Agent : séparer le modèle de l’orchestration
Utilisez un dépôt jetable ou facilement réversible. Demandez une tâche à faible risque, comme lire le README et suggérer des améliorations, sans autoriser l’écriture ni des commandes destructrices. Contrôlez deux signaux :
- Activity contient la requête du modèle.
- Cursor affiche la lecture de fichier ou l’action attendue.
Le premier confirme le routage du modèle ; le second confirme l’orchestration d’Agent. Les documents officiels ne prouvent pas que chaque requête auxiliaire d’Agent utilise toujours la même clé. Ne généralisez donc pas un seul succès à tout le trafic interne.
Tab : son absence dans Activity est normale
Une suggestion Tab teste uniquement Tab Completion. Les clés personnalisées concernent les modèles de chat, tandis que Tab reste sur les modèles intégrés. « Chat apparaît dans Activity, Tab non » est le comportement attendu.
Tools : valider endpoint et capacité du modèle
Après avoir validé Chat, choisissez un modèle indiquant tools. Dans un dépôt de test, demandez une action en lecture seule, comme lister les fichiers ou lire un petit fichier. Si Chat fonctionne mais pas les tools, vérifiez :
- Base URL exactement
https://openrouter.ai/api/v1/cursor; - prise en charge explicite de
tools; - absence de changement automatique de modèle ;
- autorisation de l’outil dans Cursor ;
- reproduction avec un second modèle compatible.
Dépannage par symptôme
| Symptôme | Cause probable | Premier contrôle | Nouveau test |
|---|---|---|---|
| Clé rejetée | Clé invalide, révoquée, avec espaces ou associée au mauvais endpoint | Recopier la clé active et confirmer le fournisseur | Redémarrer la session, envoyer le Chat minimal et vérifier Activity |
| Model not found / 404 | ID erroné, alias incomplet ou modèle indisponible sur la route compatible | Copier l’ID complet du catalogue | Le sélectionner manuellement et répéter le prompt |
| Chat fonctionne, tools Agent échouent | Endpoint générique /api/v1 ou modèle sans tools | Vérifier /cursor et supported_parameters=tools | Exécuter une tâche en lecture seule et inspecter Activity |
| Chat fonctionne, Tab absent | Tab n’utilise pas la clé personnalisée | Ne modifier ni clé ni endpoint | Valider Chat et Tab séparément |
| Réponse 402 | Crédits, plafond de clé ou budget in-flight insuffisant | Examiner les crédits/la clé et les metadata de l’erreur | Attendre, réduire la requête ou ajouter des crédits |
| Réponse 429 | Limite OpenRouter ou throttling du fournisseur upstream | Lire Retry-After et les headers, sans renvoi immédiat | Attendre avec exponential backoff ou choisir une autre route |
| Réponse Cursor sans entrée Activity | Modèle intégré, Auto ou réglage non appliqué | Sélectionner le modèle ajouté et revoir les champs | Redémarrer la session et répéter la requête minimale |
| Champs absents des réglages | Version, offre ou UI de Cursor modifiée | Mettre Cursor à jour et ouvrir la documentation BYOK actuelle | Recréer la même relation de champs et retester |
Pour une erreur 429, suivez le guide des limites OpenRouter, respectez Retry-After et utilisez exponential backoff. Multiplier les clés ne garantit pas le contournement d’une capacité globale. Pour les tools, corrigez d’abord l’endpoint et la capacité du modèle.
BYOK n’est pas une connexion directe à OpenRouter
La documentation BYOK de Cursor indique que les requêtes passent toujours par le backend Cursor pour l’assemblage final du prompt. Les équipes manipulant du code sensible doivent examiner les pratiques de Cursor et du fournisseur. N’incluez pas de clés réelles, données client ou code privé dans les captures de dépannage ; utilisez une reproduction minimale et assainie.
Les offres, règles de facturation et interfaces peuvent changer. Avant la production, rouvrez les pages officielles et confirmez le comportement du jour.
BetterToken est une configuration distincte
Pour un autre gateway OpenAI-compatible, et non OpenRouter spécifiquement, BetterToken publie une configuration Cursor séparée. Son Base URL est https://www.bettertoken.ai/v1 et doit être associé à une API Key et un Model ID BetterToken.
Ne combinez pas une clé OpenRouter avec l’endpoint BetterToken, ni une clé BetterToken avec https://openrouter.ai/api/v1/cursor. Après un changement de fournisseur, répétez le Chat minimal et vérifiez l’usage dans le tableau de bord correspondant.
Ordre final d’acceptation
Suivez cette séquence : configurer un modèle → le choisir manuellement → envoyer un Chat minimal → trouver l’entrée Activity → tester Agent et tools → accepter Tab comme fonction intégrée distincte. Chaque panne se rattache alors à une couche précise : endpoint, clé, modèle, tools, crédits ou rate limit.
