OmniRoute Remote Mode: Fehler systematisch beheben

„Connected“ wird angezeigt, aber Claude Code nutzt weiterhin die lokale OmniRoute-Instanz oder der Modellkatalog bleibt leer.

Schnellste Lösung: Prüfen Sie zuerst Gesundheitsendpunkt und Remote-Kontext, danach Adresse, Zugriffstoken, Reverse Proxy und Client-Konfiguration. Installieren Sie OmniRoute nicht neu, bevor diese fünf Fehlerklassen mit Logs und Testaufrufen ausgeschlossen sind.

Zeitplan für die Fehlersuche: In den ersten Minuten werden Erreichbarkeit und Prozesszustand geprüft, anschließend Authentifizierung und Client-Ziel, danach Streaming und Neustartverhalten. Die Empfehlung für diese Woche lautet: Legen Sie eine geschützte HTTPS- oder private Netzwerkroute an und dokumentieren Sie eine Abnahme mit Neustart, Token-Widerruf und Langzeitstream.

Diese Anleitung ist für Sie relevant, wenn Sie von einem Notebook auf ein entferntes OmniRoute zugreifen und connect, Modellabfrage oder CLI-Aufrufe fehlschlagen. Sie richtet sich außerdem an Teams, die mehrere AI-Programmierwerkzeuge über ein dauerhaft laufendes Gateway verwenden, sowie an Entwickler, die einen Cloud-Mac als ständig verfügbaren Ausführungsrechner einsetzen.

Das wichtigste Fehlersignal zuerst: Verbindung erfolgreich, Ziel trotzdem falsch

Der gefährlichste Fehler ist nicht der offensichtliche Timeout, sondern ein scheinbar erfolgreicher Connect gegen die falsche Instanz. Der lokale CLI kann einen Remote-Context gespeichert haben, während Claude Code, Cursor oder ein Shell-Skript weiterhin localhost verwendet. In diesem Fall erscheinen lokale Modelle, lokale Konfigurationen und lokale Nutzungslogs, obwohl der Remote-Modus im Terminal korrekt aussieht.

OmniRoute dokumentiert, dass ein aktiver Context von omniroute connect für spätere Befehle verwendet wird. Alternativ können Setup- und Launch-Befehle mit --remote und --api-key ausdrücklich auf eine entfernte Instanz zeigen. Die Konfiguration wird dabei lokal geschrieben, während der Modellkatalog vom Remote-Gateway abgerufen wird. Die offizielle CLI-Integrationsdokumentation beschreibt diese Trennung ausdrücklich.

Prüfen Sie deshalb nicht nur die sichtbare Context-Bezeichnung. Entscheidend sind:

• die tatsächlich verwendete Basisadresse,
• der verwendete Authorization-Header,
• der Inhalt der lokal erzeugten Konfigurationsdatei,
• der Modellkatalog der Remote-Instanz,
• ein Request-Log auf dem entfernten Host.

Erfahrung: Ein sichtbarer Name wie „remote“ ist kein Beweis für einen Remote-Request. Erst ein Logeintrag auf dem Zielhost und ein Modell, das nur dort existiert, belegen den tatsächlichen Pfad.

Erste Entscheidung: Serverfehler oder Netzwerkfehler?

Die Fehlersuche wird schneller, wenn jeder Test einer Fehlerklasse zugeordnet wird. Führen Sie die folgenden Prüfungen vom lokalen Rechner aus und ersetzen Sie die Platzhalter durch eigene Werte:

export REMOTE_HOST="<remote-host>"
export REMOTE_PORT="<remote-port>"
export REMOTE_URL="https://<gateway-domain>"
export OMNI_TOKEN="<omniroute-access-token>"

getent hosts "$REMOTE_HOST" 2>/dev/null || nslookup "$REMOTE_HOST"
nc -vz "$REMOTE_HOST" "$REMOTE_PORT"
curl -i "$REMOTE_URL"
curl -i -H "Authorization: Bearer $OMNI_TOKEN" \
  "$REMOTE_URL/v1/models"

Auf macOS ist nc in der Regel verfügbar; auf anderen Systemen kann der Befehl je nach Distribution abweichen. Die Tests liefern vier unterschiedliche Signale:

• DNS-Fehler: Der Hostname zeigt nicht auf die erwartete Adresse oder ist aus dem lokalen Netzwerk nicht auflösbar.
• TCP-Timeout: Firewall, Tunnel, Routing oder eine falsche Zieladresse verhindert den Verbindungsaufbau.
• HTTP-Antwort ohne gültigen Inhalt: Der Port ist erreichbar, aber Pfad, Proxy-Umschreibung oder Anwendung passen nicht.
• 401 oder 403: Das Netzwerk funktioniert; prüfen Sie Token, Header und Berechtigungsumfang.

Die offizielle API-Dokumentation beschreibt Bearer-Authentifizierung für die OpenAI-kompatiblen Endpunkte und unterscheidet Management-Zugriffe von normalen Modellaufrufen. API-Referenz und Authentifizierungsregeln sollten deshalb vor einer Änderung an der Proxy-Konfiguration geprüft werden.

Schritt 1: Den entfernten Dienst wirklich als „bereit“ nachweisen

Ein laufender Prozess reicht nicht. Ein Node-Prozess kann vorhanden sein, während die Datenbankprüfung fehlschlägt, der API-Port noch nicht lauscht oder das persistente Datenverzeichnis nicht eingehängt wurde.

Führen Sie auf dem Remote-Host zunächst diese Prüfungen aus:

omniroute --version
omniroute status
omniroute doctor --json
omniroute health
ss -ltnp | grep "<remote-port>"

Falls ss nicht vorhanden ist, verwenden Sie das auf dem System verfügbare Werkzeug zur Anzeige offener TCP-Sockets. Die aktuelle Dokumentation führt doctor, status, health und logs als getrennte Diagnosewege auf; doctor kann unter anderem ohne Dashboard ausgeführt werden. CLI-Referenz für Diagnose und Gesundheitsprüfung enthält die jeweils verfügbaren Befehle und Optionen.

Prüfen Sie zusätzlich:

ps aux | grep -i "[o]mniroute"
journalctl --user -u omniroute.service --no-pager -n 100
omniroute logs

Bei einer Container-Installation müssen Sie stattdessen die Container-Logs und den Mount des Datenverzeichnisses kontrollieren. Relevant ist nicht nur, ob der Prozess existiert, sondern ob nach einem Neustart dieselben Konfigurationen, Provider-Verbindungen und Zugriffstoken verfügbar sind.

Die offizielle Setup-Dokumentation nennt für die Standardinstallation den API-Port 20128 und die API-Basis /v1; diese Werte können durch Startparameter oder Umgebungsvariablen verändert werden und dürfen daher nicht blind vorausgesetzt werden. Setup-Anleitung mit Installations- und Laufzeitparametern

Verarbeitungsschluss: Wenn doctor oder health lokal fehlschlägt, liegt kein Remote-Mode-Problem vor. Reparieren Sie zuerst Dienst, Datenverzeichnis oder Prozessmanager. Wenn der Dienst lokal gesund ist, aber von außen nicht antwortet, gehen Sie zur Netzwerkprüfung über.

Schritt 2: Timeout, Firewall und Bind-Adresse auseinanderhalten

Ein Timeout bedeutet nicht automatisch, dass OmniRoute abgestürzt ist. Häufig lauscht der Dienst nur auf 127.0.0.1, während der Reverse Proxy oder Tunnel eine private Netzwerkadresse erwartet. Ebenso kann ein Port lokal offen, aber durch eine Cloud-Firewall oder Sicherheitsgruppe blockiert sein.

Prüfen Sie auf dem Server:

ss -ltnp | grep "<remote-port>"
curl -i http://127.0.0.1:<remote-port>
curl -i http://<private-server-address>:<remote-port>

Interpretieren Sie die Ergebnisse so:

• Antwort auf 127.0.0.1, aber nicht auf der privaten Adresse: Bind-Adresse oder lokales Firewall-Profil prüfen.
• Antwort auf dem Server, aber Timeout vom Notebook: Netzwerkroute, Tunnel, Sicherheitsgruppe oder DNS prüfen.
• TCP-Verbindung möglich, HTTP-Anfrage hängt: Proxy-Pfad, TLS oder Anwendung prüfen.
• Externe HTTPS-Adresse antwortet, aber der CLI-Connect scheitert: Token, URL-Suffix oder Client-Kontext prüfen.

Vermeiden Sie die scheinbar schnelle Lösung, den Dienst ohne Authentifizierung an alle Interfaces zu binden oder sämtliche Ports zu öffnen. Für einen Remote-Server sind eine geschützte HTTPS-Route, ein privates Netzwerk oder ein authentifizierter Tunnel die angemessenen Varianten. Das Dashboard und Management-Endpunkte sollten nicht weiter exponiert werden als der eigentliche Modellzugriff.

Wenn Sie die Grundlagen von HTTPS und Zugriffsschutz für ein Remote-Gateway dokumentieren möchten, können Sie ergänzend den Vuncloud Help Center als internen Einstieg für den Betriebsablauf verwenden.

Entscheidungspfad: Welche Reparatur ist jetzt zulässig?

• Wenn der Dienst nur lokal antwortet: Richten Sie zuerst einen privaten oder per HTTPS geschützten Eingang ein. Öffnen Sie nicht einfach den Management-Port im Internet.
• Wenn TCP nicht hergestellt wird: Prüfen Sie DNS, Firewall, Tunnel und Sicherheitsgruppen. Ändern Sie noch keine Token.
• Wenn HTTP antwortet, aber 401 erscheint: Verwenden Sie ein OmniRoute-Zugriffstoken mit passendem Scope, nicht den Schlüssel eines Modellanbieters.
• Wenn Modelle fehlen, obwohl /v1/models antwortet: Prüfen Sie den Remote-Context, den lokalen Client-Cache und den Modellkatalog auf dem Server.
• Wenn nur lange Anfragen abbrechen: Prüfen Sie Streaming, Proxy-Pufferung und die Timeout-Kette. Eine Neuinstallation behebt diesen Fehler nicht.

Schritt 3: Zugriffstoken, Scope und Header sauber trennen

OmniRoute-Zugriffstoken und Provider-Schlüssel erfüllen unterschiedliche Aufgaben. Der Provider-Schlüssel berechtigt OmniRoute gegenüber einem Modellanbieter; das Zugriffstoken authentifiziert den lokalen CLI oder ein Coding-Werkzeug gegenüber dem OmniRoute-Gateway.

Prüfen Sie daher zunächst, aus welcher Quelle der Token stammt:

omniroute contexts
omniroute tokens list
env | grep -E "OMNIROUTE|ANTHROPIC"

Geben Sie geheime Werte niemals vollständig in Diagnoseberichte oder Team-Chats aus. Für einen reproduzierbaren Test reicht es, den Token lokal über eine Umgebungsvariable einzusetzen:

curl -i \
  -H "Authorization: Bearer $OMNI_TOKEN" \
  "$REMOTE_URL/v1/models"

Ein schreibgeschützter Modellabruf sollte vor jeder Konfigurationsänderung funktionieren. Danach testen Sie die Aufgaben, die der betreffende Benutzer wirklich benötigt:

1. Modellkatalog lesen.
2. Einen CLI-Kontext oder eine Tool-Konfiguration auslesen.
3. Einen Modellaufruf ausführen.
4. Nur falls erforderlich: Konfiguration oder Provider-Zuordnung ändern.

Das Prinzip der geringsten Berechtigung ist hier nicht nur eine Sicherheitsmaßnahme. Es hilft auch bei der Diagnose: Ein Token, das den Modellkatalog lesen darf, aber Konfigurationsänderungen verweigert, liefert ein anderes Fehlerbild als ein ungültiger Token. Die API-Dokumentation weist darauf hin, dass Management-Routen eigene Authentifizierungsanforderungen besitzen können.

Schritt 4: Remote-Context und lokale Konfiguration beweisen

Wenn omniroute connect erfolgreich war, führen Sie bewusst einen Befehl mit expliziten Parametern aus:

omniroute models list \
  --remote "$REMOTE_URL" \
  --api-key "$OMNI_TOKEN"

omniroute setup-claude \
  --remote "$REMOTE_URL" \
  --api-key "$OMNI_TOKEN" \
  --dry-run

Zeigt der explizite Befehl andere Modelle als der Befehl ohne Parameter, ist der gespeicherte Context falsch, abgelaufen oder nicht aktiv. Die offizielle Dokumentation beschreibt, dass --remote den aktiven Context übersteuern kann und dass --dry-run eine Konfiguration ohne Schreiben der Zieldatei ermöglicht. CLI-Integrationen mit Remote-Parametern und Testmodus

Für Claude Code kontrollieren Sie anschließend die erzeugte Profilkonfiguration und die effektiven Umgebungsvariablen:

echo "$ANTHROPIC_BASE_URL"
echo "$ANTHROPIC_AUTH_TOKEN"
echo "$CLAUDE_CONFIG_DIR"

Achten Sie darauf, dass kein altes Profil und kein Shell-Startskript die Remote-Werte überschreibt. Die offizielle Konfigurationsanleitung nennt für Remote-Profile setup-claude --remote und weist darauf hin, dass die Basisadresse sowie das Token beim Start des Clients korrekt injiziert werden müssen. Claude-Code-Konfiguration für OmniRoute

Belegen Sie die Zielinstanz mit zwei unabhängigen Nachweisen:

• ein Request- oder Nutzungslog auf dem Remote-Host,
• ein Modell oder Alias, das ausschließlich auf der Remote-Instanz vorhanden ist.

Eine Anzeige im Modellwähler genügt nicht. Besonders bei Claude Code können nur bestimmte Modellkennungen im Modellwähler erscheinen; ein leerer Wähler bedeutet daher nicht automatisch, dass der Remote-Katalog leer ist.

Schritt 5: Reverse Proxy und Streaming getrennt testen

Ein kurzer Modellaufruf kann funktionieren, während eine lange Streaming-Anfrage nach dem ersten Abschnitt abbricht. Der Grund liegt dann häufig nicht bei OmniRoute selbst, sondern in der Kette aus Client, HTTPS-Proxy, API-Bridge und Upstream.

Testen Sie zunächst ohne Streaming:

curl -sS -D /tmp/headers.txt \
  -H "Authorization: Bearer $OMNI_TOKEN" \
  "$REMOTE_URL/v1/models"

Danach mit einer kleinen Streaming-Anfrage:

curl -N -i \
  -H "Authorization: Bearer $OMNI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"<remote-model>","messages":[{"role":"user","content":"Kurzer Verbindungstest."}],"stream":true}' \
  "$REMOTE_URL/v1/chat/completions"

OmniRoute dokumentiert für die veröffentlichte Konfiguration REQUEST_TIMEOUT_MS mit einem Standardwert von 600000, STREAM_IDLE_TIMEOUT_MS als vom Request-Timeout abgeleiteten Wert sowie einen TCP-Verbindungs-Timeout von 30000 Millisekunden. Diese Werte sind versionsabhängig und sollten vor einer Änderung mit omniroute --help, der installierten Dokumentation und der tatsächlichen Umgebung abgeglichen werden. Setup-Anleitung mit Laufzeit- und Timeout-Parametern

Der Reverse Proxy darf die Verbindung nicht früher schließen:

• Bei nginx beträgt proxy_read_timeout standardmäßig 60s; der Wert beschreibt die maximale Pause zwischen zwei Lesevorgängen, nicht die gesamte Dauer der Antwort. Für SSE ist außerdem die Pufferung relevant. Offizielle nginx-Dokumentation zu proxy_read_timeout und proxy_buffering
• Bei Caddy beeinflussen flush_interval und stream_timeout, wann Daten an den Client weitergeleitet beziehungsweise lange Verbindungen beendet werden. Offizielle Dokumentation zum Reverse Proxy
• Wenn ein CDN-Proxy beteiligt ist, gelten zusätzliche Grenzen. Die offizielle Dokumentation beschreibt für einen verbreiteten Proxy einen standardmäßigen Read-Timeout von 125s und einen festen Idle-Timeout von 900s; ein Fehler 524 bedeutet dort, dass der Ursprung nicht rechtzeitig geantwortet hat. Dokumentation zu Proxy-Timeouts und langen Verbindungen

Setzen Sie keine Timeout-Werte aus allgemeinen Blogbeiträgen ein. Der kleinste Wert in der Kette entscheidet über den Abbruch. Prüfen Sie Proxy-Logs, OmniRoute-Logs und die Zeit zwischen den letzten empfangenen SSE-Daten.

Hinweis: Eine höhere Wartezeit behebt keinen fehlerhaften Pfad, kein falsches Zertifikat und keinen fehlenden Authorization-Header. Erst wenn ein kurzer Request durchläuft und nur die Datenpause zum Abbruch führt, ist eine Streaming-Timeout-Prüfung sinnvoll.

Schritt 6: Remote-Instanz nach Neustart und Token-Widerruf abnehmen

Ein dauerhaft laufendes Gateway ist erst belastbar, wenn der Ausfallfall getestet wurde. Führen Sie die Abnahme nicht nur mit dem Administrator durch, sondern mit dem tatsächlichen Nutzerprofil und dem verwendeten Client.

Verwenden Sie diese Checkliste:

• [ ] Gesundheitsprüfung vor dem Neustart dokumentiert.
• [ ] Aktive externe URL und Remote-Context festgehalten.
• [ ] Modellkatalog über den Remote-Endpunkt gespeichert.
• [ ] Ein schreibgeschützter Token-Test erfolgreich.
• [ ] Ein echter Modellaufruf erfolgreich.
• [ ] Eine Streaming-Anfrage vollständig abgeschlossen.
• [ ] OmniRoute kontrolliert neu gestartet.
• [ ] Prozess, Port und Gesundheitsendpunkt nach dem Neustart geprüft.
• [ ] Modellkatalog nach dem Neustart erneut abgerufen.
• [ ] Claude Code oder das lokale CLI neu gestartet und erneut getestet.
• [ ] Ein Testtoken widerrufen und ein Zugriff danach abgelehnt.
• [ ] Ein Token mit geringerem Scope gegen die erlaubten Aufgaben geprüft.
• [ ] Proxy- und Anwendungslogs für einen späteren Fehlerfall auffindbar.

Für Teams sollte zusätzlich festgehalten werden, wer bei einem Ausfall den Dienst übernimmt, wo die persistente Datenablage liegt und wie ein neuer Token sicher ausgestellt wird. Zugangsdaten gehören nicht in gemeinsam genutzte Shell-History, Projektdateien oder unverschlüsselte Konfigurationsarchive. Für datenschutzkritische Entwicklungsprojekte sollten Sie außerdem prüfen, ob Logs Prompts, Modellnamen oder personenbezogene Inhalte speichern.

FAQ zu OmniRoute Remote Mode

Warum läuft der OmniRoute-Connect-Befehl immer in einen Timeout?

Prüfen Sie zuerst DNS und TCP-Verbindung vom Notebook zum Remote-Host. Danach rufen Sie denselben Host über den Gesundheits- oder API-Endpunkt auf. Ein Timeout ohne HTTP-Antwort weist typischerweise auf Routing, Firewall, Tunnel oder eine falsche Bind-Adresse hin. Antwortet der Server mit 401, ist die Netzwerkstrecke dagegen bereits funktionsfähig.

Was ist zu tun, wenn Remote Mode verbunden ist, aber keine Modelle erscheinen?

Führen Sie den Modellabruf einmal mit explizitem --remote und einmal über den gespeicherten Context aus. Vergleichen Sie die Ergebnisse und prüfen Sie anschließend die Remote-Logs. Wenn nur Claude Code leer bleibt, kontrollieren Sie zusätzlich Modellfilter, Profilpfad und die vom Client unterstützten Modellkennungen. Eine erfolgreiche Context-Verbindung allein beweist keinen korrekten Modellkatalog.

Wie lässt sich ein fehlgeschlagenes OmniRoute-Zugriffstoken reparieren?

Ersetzen Sie zunächst einen möglicherweise vermischten Provider-Schlüssel durch ein für OmniRoute ausgestelltes Zugriffstoken. Prüfen Sie danach den Bearer-Header, die Gültigkeit und den Scope. Testen Sie in dieser Reihenfolge Lesen, Konfigurationszugriff und Modellaufruf. So erkennen Sie, ob der Token ungültig ist oder lediglich nicht genügend Berechtigungen besitzt.

Warum erreicht Claude Code OmniRoute nach einem Reverse Proxy nicht?

Kontrollieren Sie externe URL, Pfadumschreibung und TLS-Zertifikat. Prüfen Sie außerdem, ob der Proxy den Authorization-Header weitergibt und ob die Claude-Code-Umgebungsvariablen beim Prozessstart gesetzt werden. Nach einer Änderung muss der Client neu gestartet werden. Wenn der direkte API-Aufruf funktioniert, der Client aber nicht, liegt der Fehler meist in Profil oder Startumgebung.

Wie stellt man nach einem Neustart des entfernten OmniRoute den Client wieder her?

Warten Sie nicht auf eine sichtbare Dashboard-Seite, sondern prüfen Sie Prozess, Port, Gesundheitsendpunkt, Modellkatalog und einen echten Modellaufruf. Danach starten Sie den lokalen CLI oder Claude Code mit dem gespeicherten Remote-Context neu. Wenn Modelle oder Provider nach jedem Neustart verschwinden, fehlt wahrscheinlich eine persistente Datenablage oder der Dienst startet mit einem anderen Benutzerkonto.

Wann ein dauerhaft laufender Mac die bessere Fehlergrenze ist

Wenn die Ursache bei einem ausgeschalteten Entwicklungsrechner, einer wechselnden Heimnetzadresse oder einem Tunnel liegt, bleibt der aktuelle Aufbau betrieblich fragil. Ein selbst verwalteter Server kann zusätzlich durch Firewall-Regeln, manuelle Neustarts, fehlende persistente Verzeichnisse und unklare Zuständigkeiten ausfallen. Für kurzfristige Tests ist das vertretbar; für ein Team-Gateway mit Claude Code und mehreren lokalen Clients entstehen dadurch jedoch wiederkehrende Unterbrechungen und schwer reproduzierbare Konfigurationsfehler.

Ein dauerhaft verfügbarer Mac kann die Betriebsgrenze vereinfachen, wenn die benötigten Tools, SSH-Zugänge und Projektdateien dort stabil bereitgestellt werden. Das ersetzt keine Authentifizierung und keine Proxy-Prüfung, reduziert aber die Abhängigkeit von einem einzelnen privaten Rechner. Für eine passende Betriebsumgebung können Sie die verfügbaren Mac-Mini-Mietoptionen bei Vuncloud prüfen und vor dem produktiven Einsatz die Kontaktaufnahme mit Vuncloud nutzen, um Neustart- und Zugriffsanforderungen zu klären.

Die Entscheidung sollte trotzdem sachlich bleiben: Für langfristige, gleichmäßige Schwerlast mit eigener Hardwarekontrolle ist ein Kauf oft geeigneter; für physische Schnittstellen oder spezielle lokale Peripherie gilt dasselbe. Wenn jedoch nur temporäre Rechenleistung, ein ständig erreichbarer Testknoten oder ein sauber getrenntes Remote-Gateway benötigt wird, ist das Mieten eines vorbereiteten Mac-Systems häufig weniger störanfällig als ein dauerhaft eingeschaltetes privates Gerät.

Blog

• SSH-Tunnel oder direkte WSS-Verbindung: Remote-Daemon, Erreichbarkeit und Webchat prüfen
• Remote-Mac mit SSH und VNC einrichten und typische Verbindungsfehler beheben