Cursor mit OpenRouter verbinden: Einrichtung, Funktionsgrenzen und Fehlerbehebung
Anleitung zur Cursor-OpenRouter-Konfiguration mit Activity-Nachweis, getrennten Tests für Chat, Agent, Tab und Tools sowie Diagnose von Endpunkt, Modell, Guthaben und Limits.
Inhalt
Die wichtigste Aussage lautet: Eine Antwort in Cursor beweist nicht, dass jede Cursor-Funktion OpenRouter verwendet. Am 4. Oktober 2026 kennzeichnet OpenRouter die Cursor-Integration weiterhin als Beta und verlangt die dedizierte Base URL https://openrouter.ai/api/v1/cursor. Modellanfragen in Chat und Agent können darüber laufen, wenn ein OpenRouter-Modell manuell ausgewählt ist. Tab Completion verwendet nicht den eigenen API Key, und Tool-Aufrufe funktionieren nur mit dem richtigen Endpunkt und einem Modell, das tools unterstützt.
Ein sauberer Abnahmetest ist daher eine Beweiskette: korrekte Felder → Modell manuell gewählt → minimale Anfrage → passender Eintrag in OpenRouter Activity → getrennte Agent- und Tool-Tests. Diese Anleitung basiert auf aktueller offizieller Dokumentation und behauptet nicht, ein bestimmtes Konto, einen Key oder einen Cursor-Build vollständig getestet zu haben.
Welche Funktionen verwenden den eigenen Key?
| Cursor-Funktion | Erwartetes Routing | Wichtige Grenze | Beste Prüfung |
|---|---|---|---|
| Manuell gewähltes Modell in Chat oder Ask | Üblicherweise OpenRouter | Das Modell muss über den OpenAI-kompatiblen Pfad verfügbar sein | Minimalen Prompt senden und Zeit sowie Modell in Activity abgleichen |
| Manuell gewähltes Modell in Agent | Der Modellaufruf läuft meist darüber; nicht jede interne Aktion ist bewiesen | Die Anleitung deckt die Modellauswahl ab, nicht jeden Hilfsaufruf | Activity-Eintrag und sichtbare Tool-Aktionen in Cursor beobachten |
| Tab Completion | Nein | Tab nutzt weiterhin Cursors eingebaute Modelle | Tab-Vorschläge nie als OpenRouter-Nachweis verwenden |
| Tools in Agent | Bedingt | Erfordert /cursor und ein Modell mit tools | Erst Chat prüfen, dann eine Read-only-Aufgabe ausführen |
| Automatische Modellauswahl | Schlechter Abnahmenachweis | Der Client kann einen anderen Pfad wählen | Auto deaktivieren und das hinzugefügte Modell explizit wählen |
Unterschieden werden muss zwischen Modellanfrage und Tool-Ausführung. Die OpenRouter-Dokumentation zu Tool Calling erklärt, dass das Modell einen Tool-Aufruf vorschlägt und der Client das Tool ausführt. Ein Activity-Eintrag belegt die Modellanfrage über OpenRouter, aber nicht, dass ein Dateizugriff oder lokaler Befehl auf OpenRouter ausgeführt wurde.
Voraussetzungen
- Eine aktuelle Cursor-Version mit
Cursor Settings→Models→API Keys. - Ein eigener OpenRouter API Key. Niemals in Chat, Repository, Screenshot oder Support-Nachricht einfügen.
- Die exakte Model ID aus dem aktuellen OpenRouter-Katalog.
- Für Agent-Tools ein Modell aus dem Filter für toolfähige Modelle.
Schaltflächen können je nach Version Aktivieren, Speichern, Bestätigen oder Prüfen heißen. Entscheidend bleibt die Zuordnung: Key in OpenAI API Key, Endpunkt in Override OpenAI Base URL, Modell als vollständige OpenRouter-ID.
Cursor in der richtigen Reihenfolge konfigurieren
1. API-Key-Einstellungen öffnen
Öffne Cursor Settings → Models, erweitere API Keys und suche OpenAI API Key sowie Override OpenAI Base URL.
2. OpenRouter-Key eintragen
Füge den in OpenRouter erzeugten Key in OpenAI API Key ein. Verwende nur die Einstellungsoberfläche und schließe den von deiner Version angebotenen Speichern-, Aktivieren- oder Prüfschritt ab.
3. Den dedizierten Cursor-Endpunkt verwenden
Aktiviere Override OpenAI Base URL und trage ein:
https://openrouter.ai/api/v1/cursor
Nicht den generischen Endpunkt https://openrouter.ai/api/v1 verwenden und nicht /chat/completions anhängen. Der /cursor-Endpunkt normalisiert Cursors Format; beim generischen Endpunkt können Tools und weitere Anfrageformen scheitern.
4. Exakte Model ID hinzufügen
Wähle unter Models + Add model und kopiere die vollständige ID von der aktuellen Modellseite. Auch Router-Aliase müssen exakt übernommen werden. Keine Marketingbezeichnung, Abkürzung oder alte Tutorial-ID verwenden.
5. Modell manuell auswählen
Wechsle zu Chat oder Agent und wähle das neue Modell ausdrücklich. Die automatische Auswahl ist für den ersten Test ungeeignet, weil eine Antwort den tatsächlichen Pfad nicht verrät.
So weist du die aktive Route nach
Sende in Chat eine minimale Anfrage ohne Code oder Geheimnisse, etwa die Bitte um eine feste kurze Antwort. Öffne sofort OpenRouter Activity und prüfe:
- Zeitstempel passt zum Test;
- aufgezeichnetes Modell entspricht der in Cursor gewählten Model ID;
- Anfrage war erfolgreich und enthält Nutzungsdaten;
- interne Dokumentation enthält weder Key noch vollständigen Prompt oder sensiblen Code.
Eine Cursor-Antwort ist ein schwacher Nachweis; ein passender Activity-Eintrag ist ein stärkerer Routing-Nachweis. Gibt es eine Antwort ohne Eintrag, gilt die Route als nicht bestätigt.
Für Teams reichen Zeit, Modell, Status, notwendige Request-ID, Cursor-Version und Testmodus. Damit lässt sich bei Änderungen des Beta-Verhaltens gezielt erneut prüfen.
Chat, Agent, Tab und Tools getrennt testen
Chat: zuerst die Basis schaffen
Modell manuell wählen und einen kurzen deterministischen Prompt senden. Chat gilt erst mit passendem Activity-Eintrag als bestanden. Bei einem Fehler noch nicht zu Agent wechseln, da dort Kontext, Rechte und Tools hinzukommen.
Agent: Modellrouting und Orchestrierung trennen
Nutze ein Wegwerf-Repository oder eine leicht rücksetzbare Umgebung. Bitte Agent zunächst nur, eine README zu lesen und Verbesserungen vorzuschlagen, ohne Schreibzugriff oder destruktive Befehle. Prüfe zwei getrennte Signale:
- Activity enthält die Modellanfrage.
- Cursor zeigt den erwarteten Dateizugriff oder eine andere Tool-Aktion.
Das erste belegt das Modellrouting, das zweite die Agent-Orchestrierung. Die offiziellen Unterlagen beweisen nicht, dass jeder Hintergrundaufruf von Agent denselben eigenen Key verwendet. Ein einzelner Erfolg darf daher nicht auf den gesamten internen Traffic übertragen werden.
Tab: Kein Activity-Eintrag ist erwartet
Ein Tab-Vorschlag testet nur Tab Completion. Eigene Keys gelten für Chat-Modelle, während Tab Cursors eingebaute Modelle nutzt. „Chat erscheint in Activity, Tab nicht“ ist erwartetes Verhalten.
Tools: Endpunkt und Modellfähigkeit gemeinsam prüfen
Nach erfolgreichem Chat ein Modell mit tools wählen. In einem Test-Repository eine Read-only-Aufgabe stellen, etwa Dateien auflisten oder eine kleine Datei lesen. Funktioniert Chat, aber das Tool nicht, prüfe:
- Base URL exakt
https://openrouter.ai/api/v1/cursor; - explizite Unterstützung von
tools; - keine automatische Modellumschaltung;
- Tool-Berechtigung in Cursor;
- Reproduktion mit einem zweiten bestätigten Tool-Modell.
Fehlerbehebung nach Symptom
| Symptom | Wahrscheinliche Ursache | Erste günstige Prüfung | Erneuter Test |
|---|---|---|---|
| Key abgelehnt | Ungültig, widerrufen, Leerzeichen oder Provider/Endpunkt gemischt | Aktiven Key neu kopieren und Provider-Zuordnung prüfen | Sitzung neu starten, Minimal-Chat senden, Activity prüfen |
| Model not found / 404 | Falsche ID, unvollständiger Alias oder Modell nicht kompatibel verfügbar | Vollständige aktuelle ID aus dem Katalog kopieren | Manuell auswählen und denselben Prompt wiederholen |
| Chat funktioniert, Agent-Tools nicht | Generischer /api/v1-Endpunkt oder Modell ohne Tools | /cursor und supported_parameters=tools prüfen | Read-only-Aufgabe ausführen und Activity ansehen |
| Chat funktioniert, Tab fehlt | Tab nutzt keinen eigenen Key | Key und Endpunkt nicht ändern | Chat und Tab getrennt abnehmen |
| Antwort 402 | Guthaben, Key-Limit oder In-flight-Budget reicht nicht | Key-/Credit-Seite und Error-Metadata prüfen | Warten, Anfrage verkleinern oder Guthaben erhöhen |
| Antwort 429 | OpenRouter- oder Upstream-Limit | Retry-After und Rate-Limit-Header prüfen; nicht sofort senden | Mit exponential backoff warten oder andere Route wählen |
| Cursor antwortet, Activity bleibt leer | Eingebautes Modell, Auto oder Einstellungen nicht aktiv | Hinzugefügtes Modell manuell wählen und Felder prüfen | Sitzung neu starten und Minimalanfrage wiederholen |
| Felder fehlen | Cursor-Version, Plan oder UI geändert | Cursor aktualisieren und aktuelle BYOK-Doku öffnen | Gleiche Feldbeziehung im aktuellen UI herstellen |
Bei 429 dem OpenRouter-Limit-Leitfaden folgen, Retry-After beachten und exponential backoff verwenden. Mehr Keys umgehen global verwaltete Kapazität nicht zuverlässig. Bei Tool-Fehlern zuerst Endpunkt und Modellfähigkeit korrigieren.
BYOK ist keine direkte Verbindung zu OpenRouter
Laut Cursor-BYOK-Dokumentation laufen Anfragen weiterhin über Cursors Backend zur finalen Prompt-Zusammenstellung. Teams mit sensiblem Code müssen deshalb die Datenpraxis von Cursor und Provider prüfen. Keine echten Keys, Kundendaten oder privaten Quelltexte in Diagnose-Screenshots aufnehmen; besser eine bereinigte Minimalreproduktion nutzen.
Pläne, Abrechnung und UI können sich ändern. Vor einem Produktionseinsatz die offiziellen Seiten erneut öffnen und das aktuelle Verhalten bestätigen.
BetterToken ist ein separater Konfigurationspfad
Wer einen anderen OpenAI-kompatiblen Gateway statt OpenRouter benötigt, findet bei BetterToken eine eigene Cursor-Anleitung. Deren Base URL lautet https://www.bettertoken.ai/v1 und gehört zu einem BetterToken API Key sowie einer BetterToken Model ID.
Keinen OpenRouter-Key mit dem BetterToken-Endpunkt und keinen BetterToken-Key mit https://openrouter.ai/api/v1/cursor kombinieren. Nach einem Provider-Wechsel den Minimal-Chat erneut durchführen und die Nutzung im passenden Dashboard prüfen.
Abschließende Abnahmereihenfolge
Die stabile Reihenfolge lautet: ein Modell konfigurieren → manuell wählen → Minimal-Chat senden → Activity-Eintrag finden → Agent und Tools testen → Tab separat als eingebaute Funktion abnehmen. So lässt sich jeder Fehler einer klaren Schicht zuordnen: Endpunkt, Key, Modell, Tools, Guthaben oder Rate Limit.
