Troubleshooting (Deutsch)

Kurzreferenz

Neu bei OmniRoute? Beginnen Sie hier — damit lassen sich 90 % aller Probleme lösen:

Das wird angezeigt	Bedeutung	Vorgehensweise
“Can’t connect”	OmniRoute läuft nicht	Führen Sie omniroute oder docker restart omniroute aus
“Invalid API key”	Ihr Schlüssel ist falsch oder abgelaufen	Kopieren Sie den Schlüssel erneut von der Website des Anbieters
“Rate limit exceeded”	Sie senden zu viele Anfragen	Warten Sie 1 Minute oder verwenden Sie model: "auto" für einen automatischen Fallback
“Quota exceeded”	Ihr kostenloses/bezahltes Kontingent ist aufgebraucht	Verbinden Sie weitere Anbieter oder verwenden Sie kostenlose Anbieter (Kiro, Pollinations)
“Slow responses”	Der Anbieter ist ausgelastet oder weit entfernt	Verwenden Sie model: "auto/fast" oder verbinden Sie einen schnelleren Anbieter (Groq, Cerebras)
“Wrong provider used”	auto hat einen anderen Anbieter ausgewählt	Das ist normal! auto wählt den besten aus. Erzwingen Sie mit model: "openai/gpt-4o" einen bestimmten Anbieter
“502 Bad Gateway”	Der Anbieter ist ausgefallen	Warten Sie und versuchen Sie es erneut oder verwenden Sie model: "auto", um den Anbieter zu wechseln
“401 Unauthorized”	Ihre Anmeldedaten sind falsch	Überprüfen Sie Ihren API-Schlüssel oder authentifizieren Sie sich erneut über OAuth
“omniroute is not recognized”	Im Windows-PATH fehlen globale node-Module	Fügen Sie Ihr globales npm-Präfix zum Windows-PATH hinzu. Ermitteln Sie es mit npm config get prefix.
“429 Too Many Requests”	Die Anfragerate wurde begrenzt	Warten Sie 1 Minute oder verbinden Sie weitere Anbieter

Problem weiterhin ungelöst? Lesen Sie unten die ausführliche Fehlerbehebung oder fragen Sie auf Discord.

---

Ausführliche Fehlerbehebung

---

Ratenbegrenzung bei kostenlosen Anbietern (429 / 400 / 401)

Symptom: Bei der Verwendung von model: "auto" mit kostenlosen beziehungsweise authentifizierungsfreien Anbietern (opencode, auggie usw.) erhalten Sie zeitweise HTTP 429, 400 oder 401 anstelle von Antworten. Wenn dieselbe Eingabeaufforderung kurze Zeit später erneut gesendet wird, sind die Anfragen erfolgreich, doch Automatisierungen (Cronjobs, Agenten, Skripte) brechen beim ersten Fehler ab.

Ursache: Drei voneinander unabhängige Fehlermodi überlagern sich:

1. Ratenbegrenzung des Anbieters (429): Kostenlose Tarife können ein Kontingent pro Zeitfenster erzwingen. Ein Schub paralleler Aufrufe schöpft es aus, sodass die nächste Anfrage abgelehnt wird, bis das Zeitfenster zurückgesetzt wird.
2. Defektes Modell im Passthrough (400/401): auto/*-Pools können Passthrough-Modelle von opencode enthalten, die zwar im Katalog registriert sind, aber über keine gültigen Anmeldedaten verfügen (z. B. oc/north-mini-code-free → 401). Der automatische Router versucht eines davon, scheitert, und der Fehler wird weitergegeben, bevor der Fallback greift.
3. Verstärkung durch Parallelität (429 unter Last): Wenn mehrere Agenten-/Cron-Sitzungen gleichzeitig auf auto zugreifen, überschreitet die Gesamtanfragerate das von kostenlosen Anbietern tolerierte Maß, sodass legitime Aufrufe als missbräuchlich eingestuft werden.

Bestätigte Lösung (von der Community gemeldet, 2026-08-10): Passen Sie drei Umgebungsvariablen so an, dass Rotation, Parallelität und Fallback die Schwankungen der kostenlosen Tarife abfangen, anstatt daran zu scheitern:

export OMNIROUTE_ROTATE_ON_400=true           # bei 400/401 zu einem anderen Modell/Anbieter wechseln (überspringt defekte Passthrough-Modelle)
export OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT=4   # explizite Obergrenze für die Zulassung rechenintensiver Anfragen (standardmäßig nicht gesetzt: keine Begrenzung der Anfrageanzahl, siehe Hinweis unten)
export OMNIROUTE_CHAT_ADMISSION_QUEUE_MS=5000 # längere begrenzte Wartezeit auf Kapazität für rechenintensive Anfragen statt eines sofortigen, wiederholbaren 503-Fehlers

Legen Sie diese in der Prozessumgebung von OmniRoute fest (dem Daemon, z. B. über die LaunchAgent-plist oder systemctl edit) und starten Sie OmniRoute anschließend neu. Das Rotations-Flag hat die größte Hebelwirkung: Es verwandelt einen endgültigen Fehler in einen transparenten Wiederholungsversuch bei einem funktionsfähigen Anbieter im Pool.

Hinweis: OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT begrenzt, wie viele rechenintensive Anfragen — also Anfragen mit langem Kontext — gleichzeitig ausgeführt werden; diese Grenze ist eine Zulassungsschranke und keine Ratenbegrenzung des Anbieters. Aktualisierung zum #503-Fan-out: Diese Variable wird nicht mehr standardmäßig gesetzt (sie greift jetzt nur, wenn sie wie oben ausdrücklich konfiguriert wurde) — stattdessen wird die Zulassung rechenintensiver Anfragen durch ein automatisch abgeleitetes Byte-Budget (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES) gesteuert, das sich anhand der tatsächlichen Speicherobergrenze des Hosts skaliert. Daher sollten bei einer neuen Bereitstellung deutlich weniger Ablehnungen des Typs 503 chat_admission_busy auftreten, ohne dass diese Variable überhaupt gesetzt werden muss; wenn sie hier explizit gesetzt wird, funktioniert sie weiterhin genau wie dokumentiert. Explizite Überschreibungen des Byte-Budgets werden auf 8 MiB bis 2 GiB begrenzt. Ein 413 body_exceeds_budget ist kein vorübergehender Fehler: Erhöhen Sie dieses Byte-Budget, verringern Sie OMNIROUTE_CHAT_HARD_MAX_BODY_BYTES oder erhöhen Sie die Speicherobergrenze des Prozesses. Eine Lastabweisung des Typs inflight_bytes_budget weist auf eine vorübergehende Ressourcenkonkurrenz hin und kann weiterhin durch einen erneuten Versuch behoben werden. Die Ratenbegrenzung pro Anbieter (open-sse/services/rateLimitManager.ts) wird separat durch RATE_LIMIT_MAX_WAIT_MS, RATE_LIMIT_MAX_QUEUE_DEPTH und RATE_LIMIT_AUTO_ENABLE gesteuert — siehe .env.example.

So überprüfen Sie, ob es funktioniert hat: Führen Sie Ihren Agenten/cron zweimal kurz hintereinander aus und vergewissern Sie sich, dass beide Ausführungen erfolgreich sind. Vor der Fehlerbehebung gibt die zweite Ausführung typischerweise 429/401 zurück. Nach der Fehlerbehebung werden Fehler (falls vorhanden) transparent erneut versucht und der Aufruf wird abgeschlossen. Sie können außerdem curl /monitoring/health ausführen und bei den Provider-Verbindungen das Feld rateLimitedUntil sowie für die betroffenen Provider circuitBreakers.providerBreakers[].state beobachten — der Status ist entweder CLOSED, DEGRADED, OPEN oder HALF_OPEN (siehe src/shared/utils/circuitBreaker.ts). Ein Provider, bei dem weiterhin Fehler auftreten, wechselt von CLOSED → DEGRADED → OPEN, bevor nach Ablauf des Rücksetzungszeitfensters eine Testanfrage zugelassen wird (HALF_OPEN).

Falls weiterhin 429 angezeigt wird: Das aktive Konto für diesen Provider hat sein Kontingent tatsächlich ausgeschöpft (nicht nur das Ratenlimit erreicht). Fügen Sie im OmniRoute-Dashboard unter Providers → Accounts ein zweites Konto für denselben Provider hinzu oder verwenden Sie zusätzlich einen anderen kostenlosen Provider (z. B. routeway, auggie). Die Rotation hilft nur bei vorübergehenden Ratenbegrenzungen sowie 400-/401-Fehlern; bei einer vollständigen Ausschöpfung des Kontingents sind zweite Anmeldedaten oder ein anderer Provider erforderlich.

Falls bei Vision-Modellen (auto/vision, bazaarlink/*) 403 angezeigt wird: Das verbundene Konto verfügt nicht über einen kostenpflichtigen Tarif, der Vision umfasst, oder der API-Schlüssel besitzt nicht die erforderlichen Berechtigungen. Überprüfen Sie im Provider-Dashboard, ob der Schlüsselbereich Vision/Multimodal umfasst, oder verbinden Sie ein Konto mit kostenpflichtigem Tarif und verwenden Sie dieses weiterhin als Vision-Ziel.

---

Warnungen bei npm install (ERESOLVE / Peer-Abhängigkeiten / veraltet)

Wenn Sie npm install -g omniroute ausführen, wird möglicherweise eine ganze Reihe von Warnungen wie npm warn ERESOLVE, Hinweise zu Peer-Abhängigkeiten und deprecated-Meldungen angezeigt. Diese sind zu erwarten und harmlos. Ihre Installation war erfolgreich, wenn in der Ausgabe added <N> packages angezeigt wird.

Verwenden Sie die von OmniRoute unterstützte Installationsform, um Warnungen zur Auflösung von Peer-Abhängigkeiten zu unterdrücken:

npm install -g omniroute --legacy-peer-deps

--legacy-peer-deps unterdrückt nur ERESOLVE- und Peer-Abhängigkeitshinweise. Hinweise zu veralteten Paketen bleiben sichtbar, da sie von transitiven Drittanbieterpaketen stammen; sie bedeuten nicht, dass die Installation fehlgeschlagen ist.

Die Warnungen stammen von veralteten Peer-Abhängigkeitsbereichen in Drittanbieterpaketen, über die OmniRoute keine Kontrolle hat:

1. marked-terminal erfordert marked >=1 <16, gefunden wurde marked@18 — funktioniert in der Praxis problemlos; der Peer-Abhängigkeitsbereich des Upstream-Pakets ist lediglich veraltet.
2. deprecated prebuild-install@7.1.3 — ein transitives Hilfsprogramm zum Abrufen nativer Binärdateien. Es wird nicht zum Installieren der festgelegten wreq-js-Transportbindung verwendet und bedeutet nicht, dass die Einrichtung des Transports für den Web-Cookie-Anbieter fehlgeschlagen ist.

Keine Maßnahme erforderlich — die Warnungen können nicht vollständig unterdrückt werden, ohne die Upstream-Pakete zu forken.

---

Gemini Web und Playwright Chromium

Wenn eine Gemini-Web-Anfrage den Status 503 mit einer Meldung zurückgibt, dass Playwright Chromium nicht installiert ist, ist zwar das npm-Paket vorhanden, aber die Browser-Binärdatei fehlt. Playwright hält Browser-Downloads bewusst von der Installation des npm-Pakets getrennt, daher ist diese Antwort zu erwarten, bis der Browser installiert wurde.

Installieren Sie Chromium bei einer globalen npm-Installation aus dem Verzeichnis des OmniRoute-Pakets, damit der Browser-Cache zur selben Playwright-Installation gehört:

cd "$(npm root -g)/omniroute"
npx playwright install chromium

Starten Sie OmniRoute nach der Installation neu und versuchen Sie dann die Gemini-Web-Anfrage erneut. Wenn Sie OmniRoute über ein Docker-Image ausführen, verwenden Sie das -web-Image (oder das Build-Ziel runner-web), das Chromium und seine Abhängigkeiten enthält; das Basis-Image enthält diese nicht.

---

Schnelle Lösungen

Problem	Lösung
Erste Anmeldung funktioniert nicht	Legen Sie INITIAL_PASSWORD in .env fest (kein fest codierter Standardwert)
Dashboard wird am falschen Port geöffnet	Legen Sie PORT=20128 und NEXT_PUBLIC_BASE_URL=http://localhost:20128 fest
Es werden keine Protokolle auf die Festplatte geschrieben	Legen Sie APP_LOG_TO_FILE=true fest und überprüfen Sie, ob die Erfassung von Aufrufprotokollen aktiviert ist
EACCES: Berechtigung verweigert	Legen Sie DATA_DIR=/path/to/writable/dir fest, um ~/.omniroute zu überschreiben
Routingstrategie wird nicht gespeichert	Aktualisieren Sie auf die neueste v3.x-Version (die Korrektur des Zod-Schemas zur dauerhaften Speicherung der Einstellungen wurde in früheren Versionen veröffentlicht)
Absturz bei der Anmeldung / leere Seite	Überprüfen Sie die Node.js-Version — siehe unten Node.js-Kompatibilität
dlopen / slice is not valid mach-o file (macOS)	Führen Sie cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute aus — siehe unten Neuerstellung des nativen macOS-Moduls
Proxy: „fetch failed“	Stellen Sie sicher, dass die Proxy-Konfiguration auf der richtigen Ebene festgelegt ist — siehe unten Proxy-Probleme
Docker curl: (56) Recv failure: Connection reset by peer	Die Docker-Portbindung erfolgt möglicherweise über IPv6. Verwenden Sie -p 127.0.0.1:20128:20128, um IPv4 zu erzwingen, oder testen Sie mit curl -4. Siehe unten Docker-IPv6
Virenschutz stellt README.md unter Quarantäne	Fehlalarm — siehe unten Fehlalarme von Virenschutzprogrammen
Kaspersky stuft die Desktop-App als Trojaner ein	Verhaltensbasierter Fehlalarm beim nicht signierten Installationsprogramm — siehe unten Fehlalarme von Virenschutzprogrammen

---

Antivirus-Fehlalarme

Avast/AVG verschiebt README.md wegen MD:HttpRequest-inf[Susp] in Quarantäne

Dies ist ein Fehlalarm. Nichts ist infiziert und es sind keine Maßnahmen erforderlich.

Avast und AVG verwenden eine Heuristik, die reine Text-/Markdown-Dateien kennzeichnet, die viele Links enthalten, die wie HTTP-Anfragen aussehen. OmniRoutes README.md ist im npm-Paket enthalten (sie ist in package.json → files aufgeführt), sodass sie bei einer globalen Installation unter node_modules/omniroute/README.md landet — und sie enthält etwa 15 Beispiele mit http://localhost:20128/... (die MCP-HTTP-/SSE-Endpunkte, die A2A-.well-known-URL und curl-Ausschnitte). Diese Linkdichte reicht aus, um die Heuristik auszulösen.

Falls dies erst vor Kurzem begonnen hat: Die Art der Datei hat sich nicht geändert. Die Endpunkttabelle der README wurde erweitert (MCP HTTP + SSE + A2A wurden hinzugefügt), ebenso kamen weitere curl-Beispiele hinzu, wodurch der Schwellenwert überschritten wurde.

Die Datei ist eine inaktive Dokumentation ohne ausführbare Inhalte. Sie können sie bedenkenlos aus der Quarantäne wiederherstellen.

Was zu tun ist:

1. Benachrichtigungen deaktivieren — schließen Sie das Installationsverzeichnis in Ihrem Antivirusprogramm aus (Avast: Einstellungen → Ausnahmen), indem Sie den Pfad Ihres globalen node_modules-Verzeichnisses und/oder das OmniRoute-Datenverzeichnis (~/.omniroute/) hinzufügen.
2. Den Fehlalarm melden — https://www.avast.com/false-positive-file-form.php, und die unter Quarantäne gestellte README.md anhängen. Dies ist die Lösung, die allen hilft, da hier die Heuristik des Anbieters bei einer Textdatei überreagiert.

Warum wir dies nicht auf unserer Seite „beheben“: Bei allen Beispielen handelt es sich um http://localhost, und localhost kann nicht ohne den zusätzlichen Aufwand selbstsignierter Zertifikate https verwenden. Die Dokumentation zu verstümmeln, um die Heuristik eines einzelnen Anbieters zu umgehen, würde allen Lesern schaden, nur um einen Scannerfehler zufriedenzustellen.

Kaspersky kennzeichnet die Desktop-App als PDM:Trojan.Win32.Generic

Dies ist ein Fehlalarm einer verhaltensbasierten Heuristik. Nichts ist infiziert. Kasperskys Präfix PDM: bedeutet, dass die Einstufung von seinem Proactive Defense Module (System Watcher) stammt, das bewertet, was das Installationsprogramm tut, statt es mit bekannter Schadsoftware abzugleichen. Wenn es ausgelöst wird, macht Kaspersky die gesamte Installation „rückgängig“ — einschließlich des Löschens bereits geschriebener Dateien —, sodass die App anschließend beschädigt ist oder vollständig fehlt.

Bei den gekennzeichneten Dateien handelt es sich um unveränderte Bestandteile deklarierter Open-Source-Abhängigkeiten, die mit der Desktop-App gebündelt werden, zum Beispiel:

• resources/app/.build/next/node_modules/playwright-<hash>/lib/…/agentParser.js und workerProcessEntry.js — Playwright, die Bibliothek zur Browserautomatisierung, die für die Anbieteranmeldung innerhalb der App und browsergestützte Chats verwendet wird.
• resources/app/.build/next/node_modules/@wreq-js/binding-win32-<arch>-msvc-<hash>/wreq-js.win32-<arch>-msvc.node — die festgelegte native wreq-js-Bindung, die für HTTP mit Browser-Fingerprinting bei Anbietern mit Web-Cookies verwendet wird (<arch> ist x64 oder arm64).

Warum dies ausgelöst wird: Das Windows-Installationsprogramm ist noch nicht codesigniert, sodass ein unsigniertes NSIS-Installationsprogramm keinerlei Reputation besitzt und verhaltensbasierte Heuristiken mit maximaler Aggressivität ausgeführt werden. In Kombination mit einer gebündelten nativen DLL und Hunderten von .js-Dateien, die unter %LOCALAPPDATA%\Programs\OmniRoute geschrieben werden (einschließlich Paketverzeichnissen mit Hash-Suffix aus dem eigenständigen Next.js-Build), reicht dies aus, um die Heuristik auszulösen. Eine Codesignierung ist geplant; bis sie umgesetzt ist, kann dies bei neuen Versionen erneut auftreten.

Was zu tun ist:

1. Überprüfen Sie zuerst Ihren Download (dadurch wird eine manipulierte Datei ausgeschlossen). Jede Veröffentlichung enthält latest.yml, deren Feld sha512 (base64) das Installationsprogramm OmniRoute.Setup.<version>.exe abdeckt. Führen Sie in PowerShell aus dem Ordner, der das Installationsprogramm enthält, Folgendes aus:

   $b = [System.Security.Cryptography.SHA512]::Create().ComputeHash(
     [System.IO.File]::ReadAllBytes("$PWD\OmniRoute.Setup.<version>.exe"))
   [Convert]::ToBase64String($b)

   Die Ausgabe muss mit latest.yml → sha512 übereinstimmen. Ist dies nicht der Fall, löschen Sie die Datei und laden Sie sie ausschließlich von der GitHub-Veröffentlichungsseite erneut herunter.
2. Wiederherstellen + ausschließen — stellen Sie die rückgängig gemachten Elemente aus der Quarantäne wieder her, fügen Sie eine Ausnahme für %LOCALAPPDATA%\Programs\OmniRoute hinzu (Kaspersky → Einstellungen → Bedrohungen und Ausnahmen) und installieren Sie die App anschließend erneut.
3. Den Fehlalarm melden — https://opentip.kaspersky.com/. Von Benutzern eingereichte Fehlalarmmeldungen beschleunigen die Aufnahme in die Positivliste tatsächlich.

---

Node.js-Kompatibilität

Anmeldeseite stürzt ab oder zeigt den Fehler „Module self-registration“ an

Ursache: Sie verwenden eine Node.js-Version außerhalb der von OmniRoute freigegebenen sicheren Laufzeitversionen. Am häufigsten wird eine ältere Patch-Version von Node 22 oder 24 verwendet, die unterhalb der von OmniRoute vorausgesetzten Sicherheitsschwelle liegt.

Symptome:

• Die Anmeldeseite zeigt einen leeren Bildschirm oder einen Serverfehler an
• Die Konsole zeigt Error: Module did not self-register oder ähnliche Fehler nativer Bindings an
• Die Anmeldeseite zeigt ein orangefarbenes Warnbanner mit Ihrer Node-Version an, wenn die Laufzeitumgebung außerhalb der unterstützten Sicherheitsrichtlinie liegt

Behebung:

1. Installieren Sie eine unterstützte Node.js-LTS-Version (empfohlen: Node.js 24.x):

   nvm install 24
   nvm use 24

2. Überprüfen Sie Ihre Version: node --version sollte in der LTS-Versionsreihe 24.x v24.0.0 oder neuer anzeigen
3. Installieren Sie OmniRoute erneut: npm install -g omniroute
4. Starten Sie neu: omniroute

Unterstützte sichere Versionen: >=22.22.2 <23 oder >=24.0.0 <27. Node.js 24.x LTS (Krypton) und Node.js 26 werden vollständig unterstützt.

npm v11+: better-sqlite3 nicht installiert (Modul kann nicht gefunden werden)

Ursache: npm v11 (im Lieferumfang von Node.js 24+) blockiert standardmäßig Installationsskripte für optionale Abhängigkeiten. Da better-sqlite3 unter optionalDependencies aufgeführt ist und eine native Kompilierung (node-gyp rebuild) erfordert, überspringt npm die Installation ohne Hinweis.

Symptome:

• Der Server stürzt beim Start mit Cannot find module 'better-sqlite3' ab
• ls node_modules/better-sqlite3 zeigt „No such file or directory“ an
• npm ls better-sqlite3 zeigt (empty) an

Behebung:

1. Genehmigen Sie die Installationsskripte und installieren Sie erneut:

   npm approve-scripts better-sqlite3
   npm install

2. Oder installieren Sie das vorkompilierte Paket manuell:

   npm pack better-sqlite3@13.0.1
   tar -xzf better-sqlite3-*.tgz -C node_modules
   mv node_modules/package node_modules/better-sqlite3
   rm better-sqlite3-*.tgz

3. Überprüfen Sie die Funktion: node -e "require('better-sqlite3')(':memory:').close(); console.log('OK')"

macOS: dlopen / „slice is not valid mach-o file“

Ursache: Nach einem globalen npm install -g omniroute wurde die native Binärdatei von better-sqlite3 innerhalb des Pakets möglicherweise für eine andere Architektur oder Node.js-ABI kompiliert als die lokal ausgeführte. Dies tritt unter macOS häufig auf (sowohl bei Apple Silicon als auch bei Intel), wenn die vorkompilierte Binärdatei nicht zu Ihrer Umgebung passt.

Symptome:

• Der Server schlägt beim Start sofort mit einem dlopen-Fehler fehl
• Der Fehler enthält slice is not valid mach-o file
• Vollständiges Beispiel:

dlopen(/Users/<user>/.nvm/versions/node/v24.14.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file)

Behebung — für Ihre lokale Umgebung neu kompilieren (kein Node.js-Downgrade erforderlich):

cd $(npm root -g)/omniroute/app
npm rebuild better-sqlite3
omniroute

Hinweis: Dadurch wird das native Binding für Ihre lokale Node.js-Version und CPU-Architektur neu kompiliert und die Binärinkompatibilität behoben. Der offiziell unterstützte Laufzeitbereich ist >=22.22.2 <23 oder >=24.0.0 <27 (SUPPORTED_NODE_RANGE in src/shared/utils/nodeRuntimeSupport.ts, abgestimmt auf das Feld engines in package.json). Node.js 24.x LTS (Krypton) und Node.js 26 werden mit better-sqlite3 v12.x vollständig unterstützt.

---

Proxy-Probleme

Bei der Anbieter-Validierung wird „fetch failed“ angezeigt

Ursache: Der Endpunkt zur Validierung des API-Schlüssels (POST /api/providers/validate) hat zuvor die Proxy-Konfiguration umgangen, was in Umgebungen, die Proxy-Routing erfordern, zu Fehlern führte.

Behebung (v3.5.5+): Dies ist jetzt behoben. Die Anbieter-Validierung erfolgt über runWithProxyContext, wobei Proxy-Einstellungen auf Anbieter- und globaler Ebene automatisch berücksichtigt werden.

Die Token-Zustandsprüfung schlägt mit „fetch failed“ fehl

Ursache: Bei der OAuth-Token-Aktualisierung im Hintergrund wurde die Proxy-Konfiguration nicht für jede Verbindung separat aufgelöst.

Behebung (v3.5.5+): Der Scheduler für die Token-Zustandsprüfung löst jetzt vor dem Aktualisierungsversuch die Proxy-Konfiguration für jede Verbindung auf. Aktualisieren Sie auf v3.5.5+.

Der SOCKS5-Proxy gibt „invalid onRequestStart method“ zurück

Ursache: Unter Node.js 22 ist der Dispatcher von undici@8 nicht mit der integrierten fetch()-Implementierung von Node kompatibel.

Behebung (v3.5.5+): OmniRoute verwendet jetzt die eigene fetch()-Funktion von undici, wenn ein Proxy-Dispatcher aktiv ist, und gewährleistet so ein konsistentes Verhalten. Aktualisieren Sie auf v3.5.5+.

MITM-Proxy unter WSL: Desktop-Apps auf dem Windows-Host werden nicht abgefangen

Ursache: Der MITM-Proxy und sein CA-Zertifikat werden in der Umgebung installiert, in der OmniRoute ausgeführt wird. Unter WSL ist diese Umgebung das Linux-Gastsystem, während die KI-Desktop-Apps (Kiro, Trae, Copilot, Zed, …) auf dem Windows-Host ausgeführt werden. Die Host-Apps vertrauen dem Zertifikatsspeicher des Gastsystems nicht und leiten ihren Datenverkehr nicht über den System-Proxy des Gastsystems, sodass das Abfangen von Desktop-Datenverkehr dort nicht funktioniert.

Empfehlung: Führen Sie OmniRoute nativ auf demselben Betriebssystem aus wie die Desktop-Apps, die Sie abfangen möchten (Windows für Windows-Apps; entsprechend macOS/Linux). Wenn OmniRoute innerhalb von WSL verbleibt und gleichzeitig Host-Apps abgefangen werden sollen, müssen Sie dem generierten CA-Zertifikat auf dem Windows-Host manuell vertrauen und die Netzwerk-/Proxy-Einstellungen jeder Host-App auf den WSL-Proxy-Endpunkt verweisen lassen — eine nicht unterstützte und fehleranfällige Konfiguration.

---

Anbieter-Probleme

„Language model did not provide messages“

Ursache: Das Anbieter-Kontingent ist aufgebraucht.

Behebung:

1. Prüfen Sie die Kontingentanzeige im Dashboard
2. Verwenden Sie eine Kombination mit Ausweichstufen
3. Wechseln Sie zu einer günstigeren/kostenlosen Stufe

Ratenbegrenzung

Ursache: Das Abonnementkontingent ist aufgebraucht.

Behebung:

• Fügen Sie eine Ausweichoption hinzu: cc/claude-opus-4-6 → glm/glm-4.7 → if/qwen3.8-max-preview
• Verwenden Sie GLM/MiniMax als günstige Ausweichlösung

OAuth-Token abgelaufen

OmniRoute aktualisiert Tokens automatisch. Falls weiterhin Probleme auftreten:

1. Dashboard → Anbieter → Erneut verbinden
2. Löschen Sie die Anbieterverbindung und fügen Sie sie erneut hinzu

Kiro mit mehreren Konten: Das zweite Konto macht das erste ungültig

Ursache: Das Backend von Kiro erzwingt eine einzelne aktive Sitzung pro OIDC-Client-Registrierung. Wenn zwei Konten denselben registrierten Client verwenden (Verbindungen, die vor v3.8.0 importiert wurden), macht die Aktualisierung des Tokens eines Kontos das Aktualisierungs-Token des anderen ungültig.

Behebung (v3.8.0+): Importieren Sie die betroffenen Verbindungen erneut. Ab v3.8.0 registriert jede neue Kiro-Verbindung, die über Token importieren, Google-/GitHub-Anmeldung über soziale Konten oder Automatischer Import erstellt wird, automatisch einen eigenen dedizierten OIDC-Client. Dadurch ist die Verbindung vollständig isoliert, und die Aktualisierung eines Kontos hat keine Auswirkungen auf andere Konten.

Verbindungen, die vor v3.8.0 importiert wurden, verfügen nicht über eine Client-Registrierung pro Verbindung. Diese Verbindungen verwenden weiterhin den gemeinsam genutzten Aktualisierungs-Endpunkt für die Anmeldung über soziale Konten. Um die Isolierung zu erhalten, löschen Sie die alte Verbindung unter Dashboard → Anbieter und fügen Sie sie über einen der drei Importabläufe erneut hinzu.

Ausführliche Informationen und eine Schritt-für-Schritt-Anleitung zum parallelen Hinzufügen zweier Kiro-Konten finden Sie unter docs/guides/KIRO_SETUP.md.

---

Cloud-Probleme

Cloud-Synchronisierungsfehler

1. Stellen Sie sicher, dass BASE_URL auf Ihre laufende Instanz verweist (z. B. http://localhost:20128)
2. Stellen Sie sicher, dass CLOUD_URL auf Ihren Cloud-Endpunkt verweist (z. B. https://omniroute.dev)
3. Halten Sie die NEXT_PUBLIC_*-Werte mit den serverseitigen Werten synchron

Cloud gibt bei stream=false den Statuscode 500 zurück

Symptom: Unexpected token 'd'... am Cloud-Endpunkt bei Nicht-Streaming-Aufrufen.

Ursache: Der Upstream-Dienst gibt eine SSE-Nutzlast zurück, während der Client JSON erwartet.

Problemumgehung: Verwenden Sie stream=true für direkte Cloud-Aufrufe. Die lokale Laufzeitumgebung enthält einen SSE→JSON-Fallback.

Cloud meldet eine Verbindung, aber „Ungültiger API-Schlüssel“

1. Erstellen Sie im lokalen Dashboard einen neuen Schlüssel (/api/keys)
2. Führen Sie die Cloud-Synchronisierung aus: Cloud aktivieren → Jetzt synchronisieren
3. Alte/nicht synchronisierte Schlüssel können in der Cloud weiterhin 401 zurückgeben

---

Docker-Probleme

Docker-IPv6/Verbindungsabbruch

Symptome: curl http://localhost:20128/v1/models gibt curl: (56) Recv failure: Connection reset by peer zurück. Das Dashboard und nicht authentifizierte Endpunkte funktionieren, aber authentifizierte Endpunkte schlagen fehl — es sieht wie ein Authentifizierungsproblem aus, ist aber keines.

Ursache: docker run -p 20128:20128 veröffentlicht sowohl auf 0.0.0.0 (IPv4) als auch auf :: (IPv6), aber der Prozess innerhalb des Containers lauscht nur auf IPv4. Auf Hosts, auf denen localhost zuerst zu ::1 aufgelöst wird, landet die Verbindung auf dem veröffentlichten IPv6-Port, hinter dem kein Listener vorhanden ist → Verbindungsabbruch.

Lösung:

1. Schnelldiagnose: Führen Sie curl -4 http://localhost:20128/v1/models aus. Wenn es mit -4 funktioniert, aber ohne fehlschlägt, liegt eine Abweichung bei der IPv6-Bindung vor.
2. Dauerhafte Lösung: Binden Sie explizit an IPv4, indem Sie -p 127.0.0.1:20128:20128 in Ihrem docker run-Befehl verwenden:

   docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
     -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest

   Dadurch wird die IPv4-Bindung erzwungen und außerdem verhindert, dass der Proxy auf allen Host-Schnittstellen verfügbar gemacht wird.

---

CLI-Tool wird als nicht installiert angezeigt

1. Prüfen Sie die Laufzeitfelder: curl http://localhost:20128/api/cli-tools/runtime/codex | jq
2. Für den portablen Modus: Verwenden Sie das Image-Ziel runner-cli (gebündelte CLIs)
3. Für den Host-Mount-Modus: Legen Sie CLI_EXTRA_PATHS fest und mounten Sie das bin-Verzeichnis des Hosts schreibgeschützt
4. Wenn installed=true und runnable=false: Die Binärdatei wurde gefunden, hat aber den Integritätstest nicht bestanden

Schnelle Laufzeitvalidierung

curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'

---

Kostenprobleme

Hohe Kosten

1. Prüfen Sie die Nutzungsstatistiken unter Dashboard → Nutzung
2. Wechseln Sie beim primären Modell zu GLM/MiniMax
3. Verwenden Sie für nicht kritische Aufgaben die kostenlose Stufe (Qoder, Kiro)
4. Legen Sie Kostenbudgets pro API-Schlüssel fest: Dashboard → API-Schlüssel → Budget

---

Debugging

Protokolldateien aktivieren

Setzen Sie APP_LOG_TO_FILE=true in Ihrer .env-Datei. Anwendungsprotokolle werden unter logs/ gespeichert. Anfrageartefakte werden unter ${DATA_DIR}/call_logs/ gespeichert, wenn die Aufrufprotokoll-Pipeline in den Einstellungen aktiviert ist. Wenn die Pipeline-Erfassung aktiviert ist, setzen Sie CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=false, um Nutzlasten von Stream-Blöcken auszulassen, oder passen Sie CALL_LOG_PIPELINE_MAX_SIZE_KB an, um die Größenbegrenzung der Artefakte in KB zu ändern.

Provider-Zustand prüfen

# Zustands-Dashboard
http://localhost:20128/dashboard/health

# API-Zustandsprüfung
curl http://localhost:20128/api/monitoring/health

Laufzeitspeicher

• Hauptzustand: ${DATA_DIR}/storage.sqlite (Provider, Kombinationen, Aliase, Schlüssel, Einstellungen)
• Nutzung: SQLite-Tabellen in storage.sqlite (usage_history, call_logs, proxy_logs) + optional ${DATA_DIR}/call_logs/
• Anwendungsprotokolle: <repo>/logs/... (wenn APP_LOG_TO_FILE=true)
• Aufrufprotokoll-Artefakte: ${DATA_DIR}/call_logs/YYYY-MM-DD/..., wenn die Aufrufprotokoll-Pipeline aktiviert ist

Die Aktion Verlauf bereinigen auf der Seite „Anfrageprotokolle“ löscht call_logs, die veralteten request_detail_logs und das lokale Artefaktverzeichnis ${DATA_DIR}/call_logs/.

---

Probleme mit dem Circuit Breaker

Provider bleibt im Zustand OPEN hängen

Wenn der Circuit Breaker eines Providers OPEN ist, werden Anfragen blockiert, bis die Abkühlzeit abgelaufen ist.

Lösung:

1. Gehen Sie zu Dashboard → Settings → Resilience
2. Prüfen Sie die Circuit-Breaker-Karte des betroffenen Providers
3. Klicken Sie auf Reset All, um alle Circuit Breaker zurückzusetzen, oder warten Sie, bis die Abkühlzeit abgelaufen ist
4. Vergewissern Sie sich vor dem Zurücksetzen, dass der Provider tatsächlich verfügbar ist

Provider löst den Circuit Breaker wiederholt aus

Wenn ein Provider wiederholt in den Zustand OPEN wechselt:

1. Prüfen Sie unter Dashboard → Health → Provider Health das Fehlermuster
2. Gehen Sie zu Settings → Resilience → Provider Profiles und erhöhen Sie den Fehlerschwellenwert
3. Prüfen Sie, ob der Provider seine API-Limits geändert hat oder eine erneute Authentifizierung erfordert
4. Überprüfen Sie die Latenztelemetrie — eine hohe Latenz kann zu zeitüberschreitungsbedingten Fehlern führen

---

Probleme bei der Audiotranskription

Fehler „Unsupported model“

• Verwenden Sie eine Modell-ID, deren erstes Segment einem Provider entspricht, für den Sie Zugangsdaten besitzen (openai/whisper-1, openrouter/deepgram/nova-3). Für deepgram/nova-3 ohne Präfix ist ein nativer Deepgram-Schlüssel erforderlich.
• Vergewissern Sie sich unter Dashboard → Providers, dass der Provider verbunden ist

Transkription ist leer oder schlägt fehl

• Prüfen Sie die unterstützten Audioformate: mp3, wav, m4a, flac, ogg, webm
• Vergewissern Sie sich, dass die Dateigröße innerhalb der Limits des Providers liegt (üblicherweise < 25MB)
• Prüfen Sie auf der Provider-Karte die Gültigkeit des API-Schlüssels

---

Fehlerbehebung für den Translator

Verwenden Sie Dashboard → Translator, um Probleme bei der Formatübersetzung zu untersuchen:

Modus	Verwendungszweck
Playground	Vergleichen Sie Ein- und Ausgabeformate nebeneinander — fügen Sie eine fehlschlagende Anfrage ein, um die Übersetzung zu prüfen
Chat Tester	Senden Sie Live-Nachrichten und untersuchen Sie die vollständigen Anfrage-/Antwort-Payloads einschließlich der Header
Test Bench	Führen Sie Batch-Tests über verschiedene Formatkombinationen hinweg aus, um fehlerhafte Übersetzungen zu finden
Live Monitor	Beobachten Sie den Anfragefluss in Echtzeit, um sporadisch auftretende Übersetzungsprobleme zu erkennen

Häufige Formatprobleme

• Thinking-Tags werden nicht angezeigt — Prüfen Sie, ob der Ziel-Provider Thinking unterstützt, sowie die Einstellung für das Thinking-Budget
• Tool-Aufrufe gehen verloren — Bei einigen Formatübersetzungen werden möglicherweise nicht unterstützte Felder entfernt; prüfen Sie dies im Playground-Modus
• System-Prompt fehlt — Claude und Gemini verarbeiten System-Prompts unterschiedlich; prüfen Sie die Übersetzungsausgabe
• SDK gibt einen Rohstring statt eines Objekts zurück — In v1.x behoben; der Response-Sanitizer entfernt nicht standardmäßige Felder (x_groq, usage_breakdown usw.), die zu Pydantic-Validierungsfehlern im OpenAI SDK führen. Falls dieses Problem unter v3.x+ weiterhin auftritt, erstellen Sie bitte einen Issue.
• GLM/ERNIE lehnt die Rolle system ab — In v1.x behoben; der Rollen-Normalisierer führt Systemnachrichten für inkompatible Modelle automatisch mit Benutzernachrichten zusammen. Falls dieses Problem unter v3.x+ weiterhin auftritt, erstellen Sie bitte einen Issue.
• Rolle developer wird nicht erkannt — In v1.x behoben; für Nicht-OpenAI-Provider wird sie automatisch in system umgewandelt. Falls dieses Problem unter v3.x+ weiterhin auftritt, erstellen Sie bitte einen Issue.
• json_schema funktioniert nicht mit Gemini — In v1.x behoben; response_format wird nun in Geminis responseMimeType + responseSchema umgewandelt. Falls dieses Problem unter v3.x+ weiterhin auftritt, erstellen Sie bitte einen Issue.

---

Resilienz-Einstellungen

Automatische Ratenbegrenzung wird nicht ausgelöst

• Die automatische Ratenbegrenzung gilt nur für Anbieter mit API-Schlüssel (nicht für OAuth-/Abonnement-Anbieter)
• Überprüfen Sie, ob unter Einstellungen → Resilienz → Anbieterprofile die automatische Ratenbegrenzung aktiviert ist
• Prüfen Sie, ob der Anbieter 429-Statuscodes oder Retry-After-Header zurückgibt

Abstimmen des exponentiellen Backoffs

Anbieterprofile unterstützen diese Einstellungen:

• Basisverzögerung — Anfängliche Wartezeit nach dem ersten Fehler (Standard: 1s)
• Maximale Verzögerung — Obergrenze der maximalen Wartezeit (Standard: 30s)
• Multiplikator — Faktor, um den die Verzögerung bei jedem aufeinanderfolgenden Fehler erhöht wird (Standard: 2x)

Schutz vor Thundering-Herd-Problemen

Wenn viele gleichzeitige Anfragen auf einen ratenbegrenzten Anbieter treffen, verwendet OmniRoute Mutex-Sperren und automatische Ratenbegrenzung, um Anfragen zu serialisieren und kaskadierende Fehler zu verhindern. Dies erfolgt bei Anbietern mit API-Schlüssel automatisch.

Chat-Anfragen schlagen mit 503 / chat_admission_busy fehl

Symptome:

• Der Endpunkt für Chat-Vervollständigungen gibt eine wiederholbare 503-Antwort mit dem Fehlercode chat_admission_busy zurück.
• Die Antwort enthält Retry-After. Seit #12135 wird der Wert aus der beobachteten Auslastung abgeleitet — dem größeren Wert aus dem OMNIROUTE_CHAT_ADMISSION_QUEUE_MS-Zeitfenster, das die Anfrage bereits gewartet hat, und der Zeit, die die aktuellen Heavyweight-Leases gehalten wurden — auf volle Sekunden aufgerundet und auf 60 begrenzt. Bei einem inaktiven Gate gelten weiterhin die bisherigen Mindestwerte: 2 Sekunden beim bytebasierten Pfad und 1 Sekunde beim strukturbasierten Pfad (der außerdem reason: "structure_limit" enthält).
• Dies kann auftreten, während ein anderer Heavyweight-Chat oder eine lang laufende Streaming-Antwort noch verarbeitet wird.

Der bytebasierte Antworttext lautet:

{
  "error": {
    "message": "Chat admission capacity is temporarily unavailable. Retry shortly.",
    "type": "server_error",
    "code": "chat_admission_busy"
  }
}

Die strukturbasierte Antwort verwendet denselben Typ und Code mit der Nachricht Local chat admission capacity is busy for this structurally heavy request; upstream provider routing was not attempted. Retry shortly. und reason: "structure_limit". Bei den Standardschwellenwerten gilt eine Anfrage als strukturell aufwendig, wenn sie mindestens 200 Nachrichten, mindestens 64 Tools oder mindestens 32,000 geschätzte Token umfasst oder wenn die begrenzte Strukturschätzung ihre Grenzen von 10,000 besuchten Knoten oder einer Tiefe von 12 ausschöpft.

Ursache: Hierbei handelt es sich um eine beabsichtigte Lastabweisung innerhalb von OmniRoute und nicht um einen Fehler des Upstream-Anbieters. Jeder Prozess verwendet einen prozesslokalen Schutzmechanismus, um begrenzte Heavyweight-Kapazität zu reservieren, bevor ein großer Anfragekörper im Speicher gehalten und geparst wird. Eine Heavyweight-Lease bleibt für die gesamte Lebensdauer einer SSE- Antwort bestehen.

#503-Fan-out: Vor diesem Fix begrenzte der Schutzmechanismus die Parallelität unabhängig vom Hostspeicher auf eine feste Anzahl von Anfragen (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT, Standard 1), sodass der Fan-out von Coding-Agenten (mehrere Subagenten/CLIs, Anfragekörper regelmäßig > 256 KB) auf eine effektive Parallelität von etwa 1 reduziert wurde und unter völlig normaler Last 503-Fehler erzeugte. Der Schutzmechanismus stimmt sich nun selbst ab: Er wird durch ein automatisch abgeleitetes BYTE-Budget für die Aufnahme (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES) gesteuert, dessen Größe anhand des tatsächlichen Speicherlimits des Prozesses bestimmt wird, und berücksichtigt außerdem ein aktuelles Signal für Ressourcendruck — sodass er Last nur dann abweist, wenn der Host tatsächlich unter Speicherdruck steht, und nicht nur, weil mehr als eine aufwendige Anfrage gleichzeitig eingetroffen ist. Die alte Anzahlbegrenzung (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT) wird weiterhin berücksichtigt, jedoch nur, wenn Sie sie ausdrücklich festlegen.

Wenn die Kapazität ausgelastet ist, wartet eine Heavyweight-Anfrage zunächst bis zu OMNIROUTE_CHAT_ADMISSION_QUEUE_MS (Standard 2000, 0 deaktiviert das Warten) darauf, dass ein Platz frei wird, bevor sie mit dem wiederholbaren 503 antwortet. Die begrenzte Wartezeit sorgt dafür, dass agentenbasierte Clients (OpenCode, Claude Code, Cursor), die aufwendige Unteranfragen gleichzeitig auffächern, den Anfragestoß serialisieren, anstatt ihr gesamtes Wiederholungsbudget durch sofortige Ablehnungen aufzubrauchen und während einer Aufgabe abzubrechen. Die aktuelle Belegung durch Heavyweight-Leases, das ermittelte Byte-Budget und der aktuelle Schweregrad des Ressourcendrucks werden unter GET /api/monitoring/health → chatAdmission (inflightBytes, maxInflightBytes, budgetSource, pressureSeverity, countCapEnabled) angezeigt — prüfen Sie diese Werte, bevor Sie eine Umgebungsvariable ändern. Einstellungen → Resilienz → Anfragewarteschlange → Gleichzeitige Anfragen steuert dies nicht; diese Einstellung regelt einen separaten Warteschlangenmechanismus für Anbieteranfragen.

Lösung:

1. Versuchen Sie es zunächst erneut. Clients sollten Retry-After beachten und Backoff verwenden, anstatt die Anfrage sofort zu wiederholen.
2. Prüfen Sie /api/monitoring/health → chatAdmission, bevor Sie Einstellungen anpassen. countCapEnabled: false und ein großzügiger Wert für maxInflightBytes bedeuten, dass das automatisch abgeleitete Budget bereits wie vorgesehen funktioniert; ein pressureSeverity-Wert von high/critical bedeutet, dass der Host tatsächlich nur noch wenig Speicher hat — dies lässt sich nicht durch eine Umgebungsvariable für die Zulassungssteuerung beheben, sondern erfordert mehr RAM oder eine kleinere Arbeitslast.
3. Nur wenn /api/monitoring/health zeigt, dass das automatisch abgeleitete Budget für Ihren Host tatsächlich zu klein ist (selten — es skaliert bereits von Containern bis hin zu Bare-Metal-Systemen), sollten Sie es direkt mit OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES überschreiben, anstatt auf die alte Begrenzung anhand der Anfrageanzahl zurückzugreifen.

Die maßgeblichen Einstellungen für die Zulassungssteuerung finden Sie in der Referenz zu Umgebungsvariablen.

---

Optionale RAG-/LLM-Fehlertaxonomie (16 Probleme)

Einige OmniRoute-Benutzer platzieren das Gateway vor RAG- oder Agenten-Stacks. In solchen Konfigurationen tritt häufig ein merkwürdiges Muster auf: OmniRoute scheint fehlerfrei zu funktionieren (Provider verfügbar, Routing-Profile in Ordnung, keine Ratenbegrenzungswarnungen), aber die endgültige Antwort ist dennoch falsch.

In der Praxis werden diese Vorfälle normalerweise durch die nachgelagerte RAG-Pipeline und nicht durch das Gateway selbst verursacht.

Wenn Sie ein gemeinsames Vokabular zur Beschreibung dieser Fehler verwenden möchten, können Sie die WFGY ProblemMap nutzen. Dabei handelt es sich um eine externe, unter der MIT-Lizenz veröffentlichte Textressource, die sechzehn wiederkehrende RAG-/LLM-Fehlermuster definiert. Auf einer übergeordneten Ebene behandelt sie folgende Themen:

• Abweichungen beim Abruf und fehlerhafte Kontextgrenzen
• leere oder veraltete Indizes und Vektorspeicher
• Abweichungen zwischen Embeddings und Semantik
• Probleme bei der Prompt-Zusammenstellung und mit dem Kontextfenster
• Zusammenbruch der Logik und übermäßig selbstsichere Antworten
• Fehler bei langen Verarbeitungsketten und der Koordination von Agenten
• Abweichungen beim Gedächtnis und bei den Rollen mehrerer Agenten
• Probleme mit der Reihenfolge bei Bereitstellung und Bootstrap

Die Idee ist einfach:

1. Erfassen Sie bei der Untersuchung einer fehlerhaften Antwort Folgendes:
   • Benutzeraufgabe und Anfrage
   • Route oder Provider-Kombination in OmniRoute
   • jeglichen nachgelagert verwendeten RAG-Kontext (abgerufene Dokumente, Tool-Aufrufe usw.)
2. Ordnen Sie den Vorfall einer oder zwei Nummern der WFGY ProblemMap (No.1 … No.16) zu.
3. Speichern Sie die Nummer in Ihrem eigenen Dashboard, Runbook oder Incident-Tracker neben den OmniRoute-Protokollen.
4. Verwenden Sie die entsprechende WFGY-Seite, um zu entscheiden, ob Sie Ihren RAG-Stack, Retriever oder Ihre Routing-Strategie ändern müssen.

Der vollständige Text und konkrete Anleitungen sind hier verfügbar (MIT-Lizenz, nur Text):

README der WFGY ProblemMap

Sie können diesen Abschnitt ignorieren, wenn Sie hinter OmniRoute keine RAG- oder Agenten-Pipelines betreiben.

---

Bekannte Probleme in v3.8.0

Probleme, die speziell die Version v3.8.0 betreffen, sowie die derzeit verfügbaren Problemumgehungen. Wenn eine Fehlerbehebung in einem späteren Patch enthalten ist, wird der Eintrag aktualisiert oder entfernt.

Authentifizierungsfehler bei der Devin CLI

Symptome:

• „Devin CLI nicht gefunden“ oder „Authentifizierung fehlgeschlagen“ beim Aufrufen von Devin-basierten Tools
• Die CLI-Laufzeitprüfung meldet installed=false

Ursachen:

• CLI_DEVIN_BIN verweist auf einen nicht vorhandenen Pfad
• Die Devin CLI ist auf dem Host nicht installiert

Lösung:

1. Installieren Sie die Devin CLI für Ihre Plattform
2. Legen Sie in .env den Wert CLI_DEVIN_BIN=/usr/local/bin/devin (oder den tatsächlichen Pfad) fest
3. Starten Sie OmniRoute neu und führen Sie den Test erneut über Dashboard → CLI-Tools durch

Modell bleibt im Cooldown hängen (manuelles Zurücksetzen)

Symptome:

• Ein Modell wird weiterhin als im Cooldown befindlich aufgeführt, obwohl die Ablaufzeit bereits verstrichen ist
• Bei Anfragen wird das Modell im Kombinations-Routing weiterhin übersprungen, obwohl der Zeitstempel in der Vergangenheit liegt

Manuelles Zurücksetzen:

• Dashboard: Einstellungen → Modell-Cooldowns → klicken Sie auf der betroffenen Karte auf Erneut aktivieren
• API: DELETE /api/resilience/model-cooldowns mit Verwaltungs-Authentifizierungsheadern

Verbindung zum Command Code-Provider schlägt mit 403 fehl

Symptome:

• Beim Testen der Verbindung zum Command Code-Provider wird 403 zurückgegeben
• Die Provider-Karte zeigt nach dem erneuten Hinzufügen „nicht autorisiert“ an

Ursache: Der OAuth-Ablauf wurde nicht abgeschlossen (der Callback wurde nicht empfangen oder das Token wurde nicht dauerhaft gespeichert).

Lösung:

• Führen Sie omniroute providers über die CLI aus, um den OAuth-Ablauf erneut auszulösen, oder
• führen Sie OAuth erneut über Dashboard → Provider → Command Code → Erneut verbinden aus

ModelScope gibt aggressive 429-Cooldowns zurück

Symptome:

• Sehr kurze oder sofortige Cooldowns bei ModelScope nach einer kleinen Serie von Anfragen
• Das Kombinations-Routing überspringt ModelScope früher als erwartet

Ursache: ModelScope gibt providerspezifische Retry-After-Header aus. v3.8.0 enthält eine spezielle Verarbeitung für diese Header, während ältere Versionen sie fälschlicherweise als allgemeine Hinweise zur Ratenbegrenzung interpretieren.

Lösung:

• Stellen Sie sicher, dass Sie v3.8.0 oder höher verwenden
• Überprüfen Sie, ob der Schalter useUpstream429BreakerHints unter Einstellungen → Resilienz aktiviert ist

OMNIROUTE_WS_BRIDGE_SECRET fehlt in der Produktionsumgebung

Symptome:

• 401 bei jeder WebSocket-Bridge-Anfrage von Codex/Responses, wenn die Anwendung auf einem entfernten Produktionshost ausgeführt wird
• Der WebSocket-Bridge-Handshake wird unmittelbar nach dem Verbindungsaufbau beendet

Ursache: Die Umgebungsvariable OMNIROUTE_WS_BRIDGE_SECRET fehlt in der Produktionsumgebung.

Lösung:

1. Generieren Sie ein zufälliges Geheimnis: openssl rand -hex 32
2. Legen Sie OMNIROUTE_WS_BRIDGE_SECRET=<random-secret> in der Umgebung des Produktionsservers fest (sowie in jedem Client, der mit der Bridge kommuniziert)
3. Starten Sie OmniRoute neu

Responses API: Hintergrundmodus auf synchrone Ausführung herabgestuft

Symptome:

• Protokollierte Warnung: background mode degraded to synchronous
• Eine Anfrage mit background: true gibt eine normale synchrone Antwort anstelle eines Handles für einen Hintergrundauftrag zurück

Ursache: v3.8.0 stuft background: true in der Responses API absichtlich auf eine synchrone Ausführung herab und gibt dabei eine Warnung aus. Eine vollständige asynchrone Hintergrundausführung ist für eine zukünftige Version vorgesehen.

Lösung:

• Passen Sie den Client so an, dass der Aufruf ohne background erfolgt, oder
• warten Sie auf eine spätere Version mit vollständig asynchronem Hintergrundmodus (verfolgen Sie das Änderungsprotokoll)

---

Langsamer Start / Zeitüberschreitung bei der Bereitschaftsprüfung

Wenn die CLI ⚠ Server did not respond within 60s ausgibt, der Server aber tatsächlich funktioniert, ist das Zeitbudget der Bereitschaftsprüfung für Ihre Umgebung zu kurz.

Dies tritt häufig unter Windows (Virenscanner, Dateisystem-Watcher) oder in Containern mit hoher Arbeitslast beim Start auf.

Lösung — Zeitbudget erhöhen:

# Über eine Umgebungsvariable (bleibt über mehrere Starts hinweg bestehen):
export OMNIROUTE_READY_TIMEOUT_MS=180000   # 3 Minuten
omniroute serve

# Über ein CLI-Flag (einmalig):
omniroute serve --ready-timeout 180000

Der Standardwert beträgt 60 000 ms (60 s). Die Warnung dient nur zur Information; der Server wird im Hintergrund weiter gestartet und ist erreichbar, sobald der Startvorgang abgeschlossen ist.

Vollständige Informationen zu OMNIROUTE_READY_TIMEOUT_MS finden Sie unter docs/reference/ENVIRONMENT.md.

---

Immer noch Probleme?

• GitHub-Issues: github.com/diegosouzapw/OmniRoute/issues
• Architektur: Interne Details finden Sie unter docs/architecture/ARCHITECTURE.md
• API-Referenz: Alle Endpunkte finden Sie unter docs/reference/API_REFERENCE.md
• Zustandsübersicht: Den Systemstatus in Echtzeit finden Sie unter Dashboard → Health
• Übersetzer: Verwenden Sie Dashboard → Translator, um Formatprobleme zu diagnostizieren

---

OmniRoute-Quellcode (a58000c7685f)