2026 OmniRoute Cursor-Konfiguration: ein Gateway

Das schnelle Urteil

Symptom: Sie tragen http://localhost:20128/v1 in Cursor und Claude Code ein, aber mindestens ein Client liefert Authentifizierungsfehler oder erreicht das Gateway nicht.

Schnellste Lösung: Verwenden Sie eine OmniRoute-Instanz, aber nicht zwingend dieselbe URL. Claude Code erhält die Gateway-Adresse ohne /v1. Bei Cursor müssen Sie zuerst zwischen Desktop-App, Cursor CLI und MCP unterscheiden. Der offizielle OmniRoute-CLI-Überblick behandelt diese Integrationen getrennt; Cursor CLI unterstützt einen eigenen Endpoint-Schalter, während die Desktop-App ihre API-Key-Einstellungen anders verarbeitet. (OmniRoute-CLI-Integrationen)

Diese Anleitung richtet sich an Sie, wenn Sie Cursor und Claude Code parallel nutzen und nur eine gemeinsame Modell- und Provider-Schicht verwalten möchten. Sie ist außerdem für Entwickler relevant, die ein AI Gateway dauerhaft auf einem Remote Mac betreiben oder für ein kleines Team kontrolliert bereitstellen wollen.

Letzte Aktualisierung: 12.08.2026. Die Angaben wurden anhand des OmniRoute-Standardzweigs, der aktuellen CLI-Dokumentation sowie der offiziellen Cursor- und Anthropic-Dokumentation geprüft.

Ein Gateway, aber drei verschiedene Zugangswege

Ein häufiger Fehler entsteht nicht, weil OmniRoute nur einen Client unterstützt. Der Fehler entsteht, weil „gemeinsamer Gateway-Dienst“ mit „identischer Client-Konfiguration“ verwechselt wird.

Der korrekte Datenfluss sieht so aus:

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

Die zentrale Idee lautet:

• OmniRoute bündelt Provider, API-Schlüssel, Modellnamen und Routingregeln.
• Jeder Client entscheidet selbst, welches Protokoll und welchen Endpoint er erwartet.
• Der Pfad /v1 gehört typischerweise zur OpenAI-kompatiblen API.
• Claude Code verwendet die Anthropic-Messages-Schnittstelle und ergänzt den Pfad selbst.
• MCP ist kein alternativer Chat-Endpoint. MCP stellt Werkzeuge und Kontext bereit; es ersetzt nicht automatisch die Modellverbindung.

OmniRoute dokumentiert als lokalen Standardzugang http://localhost:20128 für die Oberfläche und http://localhost:20128/v1 für die API. Der Port 20128 ist damit ein konkreter Bestandteil der Standardinstallation, aber kein unveränderlicher Wert. (OmniRoute-Repository)

Kann OmniRoute gleichzeitig für Cursor und Claude Code verwendet werden?
Ja. Beide Clients können dieselbe laufende OmniRoute-Instanz verwenden. Sie sollten aber eigene Zugangsdaten oder zumindest getrennte Zugriffsumfänge erhalten, wenn mehrere Personen oder Automatisierungsprozesse beteiligt sind. Die gemeinsame Stelle ist das Gateway. Die lokale Konfiguration bleibt clientabhängig.

Die minimale OmniRoute-Basis

Bevor Sie einen Client konfigurieren, müssen Sie nachweisen, dass OmniRoute selbst funktioniert. Eine geöffnete Weboberfläche reicht nicht aus. Sie beweist nur, dass ein HTTP-Dienst antwortet, nicht dass Provider, Modellkatalog und Inferenzpfad bereit sind.

Führen Sie die Einrichtung in dieser Reihenfolge aus:

1. OmniRoute installieren und starten

bash npm install -g omniroute omniroute

Für den ersten Mac-Test ist eine direkte lokale Installation meist leichter zu prüfen, weil der Prozess unmittelbar im Terminal sichtbar bleibt. Die konkrete Installationsform ist weniger wichtig als ein reproduzierbarer Startbefehl und ein eindeutig bekanntes Datenverzeichnis.

1. Diagnose ausführen

bash omniroute doctor omniroute health

doctor prüft unter anderem Laufzeit, Datenverzeichnis, Datenbank, Port und Provider-Konfiguration. health liefert zusätzliche Laufzeitinformationen. Die offiziellen CLI-Werkzeuge von OmniRoute beschreiben Diagnose, Provider-Tests und Modellabfragen als getrennte Prüfungen. (OmniRoute-CLI-Werkzeuge)

1. Mindestens einen Provider verbinden

Öffnen Sie die Provider-Verwaltung, verbinden Sie einen Provider per OAuth oder API-Schlüssel und testen Sie die Verbindung. Für einen echten Fallback-Test reicht ein einzelner Provider nicht aus. Dafür benötigen Sie mindestens zwei tatsächlich erreichbare Ziele.

1. Inference-API-Key erzeugen

Erstellen Sie in der Endpoint- oder Schlüsselverwaltung einen separaten Schlüssel:

text OMNIROUTE_API_KEY=<IHR_OMNIROUTE_SCHLÜSSEL>

Verwenden Sie niemals den Administratorkennsatz als Client-Schlüssel. Für ein Team sollten Cursor, Claude Code und CI-Prozesse nicht alle denselben unbeschränkten Schlüssel teilen.

1. Modellkatalog lesen

bash omniroute models --json

Je nach Version kann auch die Modellansicht im Dashboard oder der dokumentierte /v1/models-Zugang verwendet werden. Entscheidend ist die Antwort selbst: Sie muss mindestens ein Modell mit einer gültigen Modell-ID enthalten.

1. Eine minimale Anfrage senden

Für einen OpenAI-kompatiblen Zugang prüfen Sie den Endpoint mit einem kurzen Test:

bash curl http://localhost:20128/v1/chat/completions \ -H "Authorization: Bearer <IHR_OMNIROUTE_SCHLÜSSEL>" \ -H "Content-Type: application/json" \ -d '{ "model": "<PROVIDER_ODER_MODELL>", "messages": [ {"role": "user", "content": "Antworten Sie mit OK."} ] }'

Erst wenn dieser Test eine Modellantwort liefert, lohnt sich die Fehlersuche in Cursor oder Claude Code. Prüfen Sie dabei nicht nur den HTTP-Status, sondern auch Modell-ID, Antworttext und Gateway-Log.

Claude Code: Root-URL statt /v1

Bei Claude Code ist die Endpoint-Frage eindeutig: ANTHROPIC_BASE_URL zeigt auf die Gateway-Wurzel. Sie tragen also beispielsweise Folgendes ein:

export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="<IHR_OMNIROUTE_SCHLÜSSEL>"
export ANTHROPIC_MODEL="<PROVIDER_ODER_MODELL>"

Nicht korrekt wäre:

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

Der Grund ist der erwartete Protokollpfad. Claude Code ergänzt bei der Anthropic-Messages-Kommunikation den passenden Pfad selbst. Die Anthropic-Dokumentation beschreibt für Gateway-Betrieb ebenfalls eine einheitliche Basisadresse ohne angehängten OpenAI-kompatiblen /v1-Pfad. (Anthropic-Dokumentation zu LLM-Gateways)

Muss /v1 bei der Claude-Code-Konfiguration mit OmniRoute ergänzt werden?
Nein, nicht bei ANTHROPIC_BASE_URL. Lassen Sie den Suffix weg. Wenn Sie dagegen einen OpenAI-kompatiblen Client konfigurieren, gehört /v1 in der Regel zum Base URL.

Die Authentifizierung kann über ANTHROPIC_AUTH_TOKEN oder alternativ über ANTHROPIC_API_KEY erfolgen. Wenn beide Variablen gesetzt sind, hat der Token Vorrang. Prüfen Sie diese Variablen im selben Terminal, aus dem Sie Claude Code starten. (OmniRoute-Konfiguration für Claude Code)

Hauptweg: OmniRoute-Launcher

Für eine kontrollierte Konfiguration ist der Launcher der kürzere Weg:

omniroute launch --api-key <IHR_OMNIROUTE_SCHLÜSSEL>

Für ein festes Modellprofil:

omniroute setup-claude --only <MODELLMUSTER>
omniroute launch --profile <PROFILNAME>

Der Launcher setzt die relevanten Umgebungsvariablen, prüft den Server und startet anschließend Claude Code. Das reduziert das Risiko, dass eine alte Shell-Konfiguration oder ein falsch gesetzter /v1-Suffix aktiv bleibt.

Alternative: settings.json

Wenn Sie Profile selbst verwalten möchten, kann die Konfiguration in einem Claude-Code-Profil liegen:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "<IHR_OMNIROUTE_SCHLÜSSEL>",
    "ANTHROPIC_MODEL": "<PROVIDER_ODER_MODELL>"
  }
}

Nach jeder Änderung müssen Sie Claude Code vollständig beenden und neu starten. Die Umgebungsvariablen werden beim Prozessstart eingelesen. Ein offenes Terminalfenster übernimmt neue Werte nicht automatisch.

Ein weiterer Stolperstein betrifft die Modellauswahl. Der native Modellwähler zeigt nicht zwangsläufig jede fremde Modell-ID aus dem OmniRoute-Katalog. Andere Modelle müssen Sie über ANTHROPIC_MODEL oder ein erzeugtes Profil ausdrücklich setzen. Eine leere Auswahl bedeutet daher nicht automatisch, dass der Gateway-Dienst defekt ist.

Cursor: Desktop, CLI und MCP getrennt prüfen

Welche Unterschiede bestehen zwischen Cursor Desktop und Cursor CLI bei OmniRoute?
Die Desktop-App, Cursor CLI und MCP sind drei verschiedene Integrationswege. Sie sollten sie nicht durch eine einzige allgemeine „Cursor-Konfiguration“ ersetzen.

Cursor Desktop

Cursor Desktop verwaltet eigene API-Key-Einstellungen. Die offizielle Dokumentation weist darauf hin, dass benutzerdefinierte API-Schlüssel nur für Standard-Chatmodelle gelten. Spezialfunktionen, beispielsweise bestimmte Tab-Vervollständigungsmodelle, können weiterhin die integrierten Cursor-Modelle verwenden. (Cursor-Dokumentation zu API-Schlüsseln)

Das bedeutet für OmniRoute:

• Sie können die kompatible Provider-Konfiguration in Cursor testen.
• Eine erfolgreiche Prüfung bedeutet nicht, dass jede Cursor-Funktion durch OmniRoute läuft.
• Wenn Cursor ein Modell akzeptiert, aber Tab Completion unverändert arbeitet, ist das nicht automatisch ein Gateway-Fehler.
• Modellnamen müssen exakt der OmniRoute-Modellliste entsprechen.

Nutzen Sie bei der Desktop-App zuerst die Modell- und API-Key-Einstellungen. Die OmniRoute-CLI kann mit omniroute setup-cursor die notwendigen In-App-Schritte ausgeben, schreibt aber keine vollständige Cursor-Konfigurationsdatei. (OmniRoute-CLI-Integrationen)

Cursor CLI

Cursor CLI besitzt einen eigenen Endpoint-Schalter. Ein minimales Muster lautet:

export CURSOR_API_KEY="<IHR_OMNIROUTE_SCHLÜSSEL>"

cursor-agent \
  --endpoint http://localhost:20128/v1 \
  --model <PROVIDER_ODER_MODELL> \
  "Prüfen Sie die Verbindung und antworten Sie mit OK."

Die offizielle Cursor-CLI-Dokumentation nennt --endpoint für benutzerdefinierte API-Endpunkte sowie CURSOR_API_KEY und --api-key für die Authentifizierung. (Cursor-CLI-Authentifizierung)

Hier ist /v1 also der erwartete Ausgangspunkt für den OpenAI-kompatiblen Weg. Genau deshalb dürfen Sie die Claude-Code-URL nicht einfach kopieren.

MCP

MCP ist eine dritte Ebene. Ein MCP-Server stellt Werkzeuge, Ressourcen oder Kontext für einen Client bereit. Er ist nicht automatisch der Modell-Endpoint. OmniRoute kann laut eigener CLI-Dokumentation als MCP-Server über Standard-Ein- und -Ausgabe gestartet werden:

omniroute --mcp

Das ist für Werkzeugzugriff relevant, löst aber weder die Claude-Code-Authentifizierung noch die Cursor-Desktop-API-Key-Prüfung. Wenn Sie MCP testen, protokollieren Sie den Werkzeugaufruf separat vom Modellaufruf.

Die wichtigsten Fehlerbilder

Dienst nicht erreichbar oder Modellliste leer

Prüfen Sie zuerst die lokale Erreichbarkeit:

curl -i http://localhost:20128
omniroute doctor --json
omniroute models --json

Drei Ursachen treten besonders häufig auf:

• OmniRoute läuft auf einem anderen Port.
• Der Client läuft nicht auf derselben Maschine wie das Gateway.
• Der Provider ist zwar gespeichert, aber nicht authentifiziert oder nicht erreichbar.

localhost funktioniert nur, wenn Client und Gateway auf demselben Rechner laufen. Bei einem Remote Mac muss die Adresse aus Sicht des Clients erreichbar sein. Verwenden Sie daher beispielsweise eine private Netzwerkadresse oder einen kontrollierten Tunnel, nicht einfach eine offen ins Internet gestellte Verwaltungsoberfläche.

Für Remote-Betrieb dokumentiert OmniRoute die Verbindung über einen aktiven Remote-Kontext beziehungsweise über --remote und --api-key. Dadurch kann die CLI auf dem lokalen Rechner Konfigurationen erzeugen, während der Gateway-Dienst auf einem anderen System läuft.

Claude Code umgeht OmniRoute

Wenn Claude Code direkt beim Provider landet, prüfen Sie:

1. echo $ANTHROPIC_BASE_URL
2. Fehlt der Suffix /v1?
3. Ist ANTHROPIC_AUTH_TOKEN im selben Prozess gesetzt?
4. Wurde Claude Code nach der Änderung neu gestartet?
5. Gibt omniroute logs eine eingehende Anfrage aus?

Bleibt das Log leer, liegt der Fehler vor OmniRoute. Erscheint die Anfrage, aber mit Status 401, prüfen Sie Schlüssel und Zugriffsumfang. Erscheint die Anfrage mit einem Modellfehler, prüfen Sie die Modell-ID.

Cursor bestätigt den Schlüssel, nutzt aber nicht alles

Das Verhalten ist bei Cursor erwartbar, wenn Sie nur Standard-Chatmodelle über einen eigenen Schlüssel anbinden. Prüfen Sie deshalb getrennt:

• Chat-Anfrage im Editor.
• Modellwechsel.
• Tab-Vervollständigung.
• Agent-Aktion.
• MCP-Werkzeugaufruf.

Dokumentieren Sie pro Funktion, ob sie im OmniRoute-Log erscheint. Ohne diese Zuordnung sollten Sie nicht behaupten, Cursor sei vollständig über das Gateway geroutet.

Fallback: Routing statt Wunschdenken

Warum wechselt OmniRoute nach erschöpfter Modellquote nicht automatisch?
Weil ein einzelnes festes Modell und eine Fallback-Kette zwei unterschiedliche Betriebsarten sind. Wenn Sie provider-a/modell-x erzwingen und nur dieser Provider angeschlossen ist, existiert kein alternatives Ziel. Auch ein vorhandener zweiter Provider wird nicht automatisch genutzt, wenn keine passende Combo oder Routingregel dafür eingerichtet ist.

Für einen überprüfbaren Multi-Modell-Fallback brauchen Sie:

• mindestens zwei aktive Provider;
• zwei gültige Modellziele;
• eine definierte Prioritäts- oder Fallback-Kette;
• einen Client, der die Anfrage an OmniRoute sendet;
• Logs, anhand derer der Wechsel sichtbar wird.

Führen Sie den Test reproduzierbar aus:

1. Legen Sie Provider A als bevorzugtes Ziel fest.
2. Legen Sie Provider B als Fallback fest.
3. Verwenden Sie eine feste Modell-ID oder eine dokumentierte automatische Route.
4. Sperren Sie Provider A kontrolliert, etwa durch Deaktivieren der Verbindung oder einen bewusst ungültigen Provider-Schlüssel.
5. Senden Sie dieselbe kurze Anfrage erneut.
6. Prüfen Sie Gateway-Log, Fehlerstatus, Routingentscheidung und tatsächlich verwendete Modell-ID.
7. Aktivieren Sie Provider A wieder und testen Sie, ob die Priorität zurückkehrt.

OmniRoute beschreibt automatische Auswahl und Fallback als Routingfunktionen. Die vom Projekt genannten Providerzahlen, kostenlosen Kontingente und Token-Einsparungen sind jedoch Projektangaben, keine unabhängigen Messwerte. Behandeln Sie sie entsprechend als Hersteller- beziehungsweise Projekt-Selbstauskunft.

Entscheidungsregeln für Ihre Konfiguration

Verwenden Sie diese Bedingungen, bevor Sie weitere Variablen ändern:

• Wenn Sie Claude Code verwenden, wählen Sie die Gateway-Wurzel ohne /v1.
• Wenn Sie Cursor CLI verwenden, wählen Sie den dokumentierten benutzerdefinierten Endpoint mit /v1.
• Wenn Sie Cursor Desktop verwenden, konfigurieren Sie den kompatiblen API-Key in der Oberfläche und prüfen Sie die unterstützten Funktionen einzeln.
• Wenn nur die Modellliste leer ist, prüfen Sie Discovery, Modell-ID und Client-Version, nicht zuerst das Netzwerk.
• Wenn nur ein Provider verbunden ist, erwarten Sie keinen belastbaren Fallback.
• Wenn das Gateway auf einem Remote Mac läuft, ersetzen Sie localhost durch eine aus dem Clientnetz erreichbare Adresse.
• Wenn mehrere Personen zugreifen, verwenden Sie getrennte Schlüssel und begrenzen Sie deren Rechte.
• Wenn MCP-Werkzeuge funktionieren, aber Chat nicht, behandeln Sie das als zwei getrennte Pfade.

Konfiguration und Betrieb im direkten Vergleich

Wenn Sie die Verwaltung lieber über eine Oberfläche durchführen, können Sie die MacHTML-Konsole für laufende Umgebungen als Ausgangspunkt für Ihre Remote-Betriebsplanung verwenden. Für Zugang, Berechtigungen und Verbindungsfragen ist zusätzlich die MacHTML-Hilfe relevant.

Abnahme für den Remote-Mac-Betrieb

Ein Remote Mac ist erst dann als Entwicklungsumgebung abgenommen, wenn nicht nur der Browser erreichbar ist. Prüfen Sie die komplette Kette:

Für einen kurzen persönlichen Test ist ein lokaler Prozess meist die vernünftigere Wahl. Wenn Sie jedoch von mehreren Geräten zugreifen, einen Agenten über längere Zeit laufen lassen oder eine gemeinsame Entwicklungsumgebung benötigen, wird ein kontrollierter Remote Mac interessanter. Achten Sie dabei besonders auf Netzwerkerreichbarkeit, Schlafmodus, Schlüsselrotation und die Trennung von Verwaltungs- und Inference-Zugang.

Die MacHTML-Preisübersicht für Ihre Region sollten Sie erst nach dieser technischen Abnahme heranziehen. Die richtige Entscheidung hängt nicht nur von Rechenleistung ab, sondern davon, wie lange Gateway und Coding-Agent tatsächlich ohne Unterbrechung laufen müssen.

Für die meisten persönlichen Kurztests genügt die lokale OmniRoute-Installation. Sobald Ihr Gerät regelmäßig schläft, sich das Netzwerk ändert oder Cursor und Claude Code von mehreren Arbeitsplätzen aus zugreifen sollen, ist ein dauerhaft erreichbarer Remote Mac die robustere Betriebsform. Gegenüber einer lokalen Einrichtung vermeiden Sie dann drei konkrete Schwachstellen: den unzuverlässigen Hintergrundbetrieb, wechselnde lokale Netzwerkadressen und die gemeinsame Ablage sensibler Provider-Schlüssel auf mehreren Entwicklerrechnern. MacHTML eignet sich in diesem Fall als Mietumgebung, wenn Sie die Laufzeit flexibel halten und nicht sofort eigene Hardware dauerhaft bereitstellen möchten.

Beginnen Sie mit dem lokalen Doppeltest, protokollieren Sie Endpoint, Modell-ID, Fallback und Neustartverhalten und wechseln Sie erst danach auf eine dauerhaft laufende Umgebung.

Weiterführende Links: Cursor, Copilot und Claude Code: Rechenbedarf und Einsatzszenarien im Vergleich Modell-Failover und Anbieter-Routing für stabile Gateway-Verbindungen