Skip to content

Latest commit

 

History

History
219 lines (139 loc) · 10.8 KB

TROUBLESHOOTING.md

File metadata and controls

219 lines (139 loc) · 10.8 KB

Problemen oplossen

🌐 Languages: 🇺🇸 English | 🇧🇷 Português (Brasil) | 🇪🇸 Español | 🇫🇷 Français | 🇮🇹 Italiano | 🇷🇺 Русский | 🇨🇳 中文 (简体) | 🇩🇪 Deutsch | 🇮🇳 हिन्दी | 🇹🇭 ไทย | 🇺🇦 Українська | 🇸🇦 العربية | 🇯🇵 日本語 | 🇻🇳 Tiếng Việt | 🇧🇬 Български | 🇩🇰 Dansk | 🇫🇮 Suomi | 🇮🇱 עברית | 🇭🇺 Magyar | 🇮🇩 Bahasa Indonesia | 🇰🇷 한국어 | 🇲🇾 Bahasa Melayu | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇵🇹 Português (Portugal) | 🇷🇴 Română | 🇵🇱 Polski | 🇸🇰 Slovenčina | 🇸🇪 Svenska | 🇵🇭 Filipino

Veelvoorkomende problemen en oplossingen voor OmniRoute.

Snelle oplossingen

| Probleem | Oplossing | | ----------------------------------- | ----------------------------------------------------------------------- | ---------------- | | Eerste login werkt niet | Controleer INITIAL_PASSWORD in .env (standaard: 123456) | | Dashboard opent op verkeerde poort | Stel PORT=20128 en NEXT_PUBLIC_BASE_URL=http://localhost:20128 | in | | Geen verzoeklogboeken onder logs/ | Stel ENABLE_REQUEST_LOGS=true | in | | EACCES: toestemming geweigerd | Stel DATA_DIR=/path/to/writable/dir in om ~/.omniroute | te overschrijven | | Routeringsstrategie bespaart niet | Update naar v1.4.11+ (Zod-schemafix voor persistentie van instellingen) |

Problemen met providers

"Taalmodel heeft geen berichten geleverd"

Oorzaak: Providerquotum is opgebruikt.

Opgelost:

  1. Controleer de dashboardquotatracker
  2. Gebruik een combo met fallback-lagen
  3. Schakel over naar het goedkopere/gratis niveau

Snelheidslimiet

Oorzaak: Abonnementsquota zijn opgebruikt.

Opgelost:

  • Terugval toevoegen: cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking
  • Gebruik GLM/MiniMax als goedkope back-up

OAuth-token verlopen

OmniRoute vernieuwt tokens automatisch. Als de problemen aanhouden:

  1. Dashboard → Provider → Opnieuw verbinden
  2. Verwijder de providerverbinding en voeg deze opnieuw toe

Cloudproblemen

Cloudsynchronisatiefouten

  1. Controleer of BASE_URL verwijst naar uw actieve exemplaar (bijvoorbeeld http://localhost:20128)
  2. Controleer of CLOUD_URL verwijst naar uw cloudeindpunt (bijvoorbeeld https://omniroute.dev)
  3. Zorg ervoor dat de NEXT_PUBLIC_*-waarden overeenkomen met de waarden op de server

Wolk stream=false Retourneert 500

Symptoom: Unexpected token 'd'... op cloudeindpunt voor niet-streaming oproepen.

Oorzaak: Upstream retourneert SSE-payload terwijl de client JSON verwacht.

Oplossing: Gebruik stream=true voor directe cloudoproepen. Lokale runtime omvat SSE → JSON-fallback.

Cloud zegt verbonden maar "Ongeldige API-sleutel"

  1. Maak een nieuwe sleutel vanaf het lokale dashboard (/api/keys)
  2. Voer cloudsynchronisatie uit: Schakel Cloud in → Nu synchroniseren
  3. Oude/niet-gesynchroniseerde sleutels kunnen nog steeds 401 retourneren in de cloud

Docker-problemen

CLI-tool geeft aan dat deze niet is geïnstalleerd

  1. Controleer runtimevelden: curl http://localhost:20128/api/cli-tools/runtime/codex | jq
  2. Voor draagbare modus: gebruik afbeeldingsdoel runner-cli (gebundelde CLI's)
  3. Voor de host-aankoppelmodus: stel CLI_EXTRA_PATHS in en koppel de hostbin-map aan als alleen-lezen
  4. Als installed=true en runnable=false: binair bestand is gevonden maar de statuscheck is mislukt

Snelle runtime-validatie

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}'

Kostenproblemen

Hoge kosten

  1. Controleer gebruiksstatistieken in Dashboard → Gebruik
  2. Schakel het primaire model over naar GLM/MiniMax
  3. Gebruik de gratis laag (Gemini CLI, iFlow) voor niet-kritieke taken
  4. Stel kostenbudgetten per API-sleutel in: Dashboard → API-sleutels → Budget

Foutopsporing

Verzoeklogboeken inschakelen

Stel ENABLE_REQUEST_LOGS=true in uw .env bestand in. Logboeken verschijnen onder de map logs/.

Controleer de gezondheid van de provider

# Health dashboard
http://localhost:20128/dashboard/health

# API health check
curl http://localhost:20128/api/monitoring/health

Runtime-opslag

  • Hoofdstatus: ${DATA_DIR}/db.json (providers, combo's, aliassen, sleutels, instellingen)
  • Gebruik: ${DATA_DIR}/usage.json, ${DATA_DIR}/log.txt, ${DATA_DIR}/call_logs/
  • Logboeken aanvragen: <repo>/logs/... (wanneer ENABLE_REQUEST_LOGS=true)

Problemen met stroomonderbrekers

Provider zit vast in OPEN-status

Wanneer de stroomonderbreker van een provider OPEN is, worden verzoeken geblokkeerd totdat de cooldown is verstreken.

Opgelost:

  1. Ga naar Dashboard → Instellingen → Veerkracht
  2. Controleer de stroomonderbrekerkaart van de betreffende provider
  3. Klik op Alles resetten om alle onderbrekers te wissen, of wacht tot de cooldown is verstreken
  4. Controleer of de provider daadwerkelijk beschikbaar is voordat u reset

De provider schakelt de stroomonderbreker steeds uit

Als een aanbieder herhaaldelijk in de OPEN-status komt:

  1. Controleer Dashboard → Gezondheid → Providergezondheid voor het foutpatroon
  2. Ga naar Instellingen → Veerkracht → Providerprofielen en verhoog de foutdrempel
  3. Controleer of de provider de API-limieten heeft gewijzigd of herauthenticatie vereist
  4. Controleer latentie-telemetrie: hoge latentie kan op time-outs gebaseerde fouten veroorzaken

Problemen met audiotranscriptie

Fout 'Niet-ondersteund model'

  • Zorg ervoor dat u het juiste voorvoegsel gebruikt: deepgram/nova-3 of assemblyai/best
  • Controleer of de provider is verbonden in Dashboard → Providers

Transcriptie is leeg of mislukt

  • Controleer ondersteunde audioformaten: mp3, wav, m4a, flac, ogg, webm
  • Controleer of de bestandsgrootte binnen de limieten van de provider ligt (doorgaans < 25 MB)
  • Controleer de geldigheid van de API-sleutel van de provider op de providerkaart

Foutopsporing bij vertalers

Gebruik Dashboard → Vertaler om problemen met de vertaling van formaten op te lossen:

Modus Wanneer gebruiken
Speeltuin Vergelijk invoer-/uitvoerformaten naast elkaar - plak een mislukt verzoek om te zien hoe het zich vertaalt
Chattester Verzend live berichten en inspecteer de volledige payload van verzoeken/antwoorden, inclusief headers
Proefbank Voer batchtests uit voor indelingscombinaties om te ontdekken welke vertalingen niet werken
Livemonitor Bekijk de realtime aanvraagstroom om intermitterende vertaalproblemen op te sporen

Veelvoorkomende formaatproblemen

  • Thinking-tags verschijnen niet — Controleer of de doelaanbieder het denken en de instelling van het denkbudget ondersteunt
  • Tooloproepen vervallen — Bij sommige formaatvertalingen kunnen niet-ondersteunde velden worden verwijderd; verifiëren in Speeltuinmodus
  • Systeemprompt ontbreekt — Claude en Gemini behandelen de systeemprompts anders; controleer de vertalingsuitvoer
  • SDK retourneert onbewerkte tekenreeks in plaats van object — Opgelost in v1.1.0: respons sanitizer verwijdert nu niet-standaard velden (x_groq, usage_breakdown, etc.) die OpenAI SDK Pydantic-validatiefouten veroorzaken
  • GLM/ERNIE weigert de rol system — Opgelost in v1.1.0: de rolnormalizer voegt systeemberichten automatisch samen met gebruikersberichten voor incompatibele modellen
  • developer rol niet herkend — Opgelost in v1.1.0: automatisch geconverteerd naar system voor niet-OpenAI-providers
  • json_schema werkt niet met Gemini — Opgelost in v1.1.0: response_format is nu geconverteerd naar Gemini's responseMimeType + responseSchema

Veerkrachtinstellingen

Automatische snelheidslimiet wordt niet geactiveerd

  • Automatische tarieflimiet is alleen van toepassing op API-sleutelproviders (niet op OAuth/abonnement)
  • Controleer of bij Instellingen → Veerkracht → Providerprofielen** automatische tarieflimiet is ingeschakeld
  • Controleer of de provider 429 statuscodes of Retry-After headers retourneert

Exponentiële uitstel afstemmen

Providerprofielen ondersteunen deze instellingen:

  • Basisvertraging — Initiële wachttijd na eerste storing (standaard: 1s)
  • Max. vertraging — Maximale wachttijdlimiet (standaard: 30s)
  • Vermenigvuldiger — Hoeveel vertraging per opeenvolgende fout moet worden vergroot (standaard: 2x)

Anti-donderende kudde

Wanneer veel gelijktijdige verzoeken een provider met een beperkte snelheid bereiken, gebruikt OmniRoute mutex + automatische snelheidsbeperking om verzoeken te serialiseren en trapsgewijze fouten te voorkomen. Dit gebeurt automatisch voor API-sleutelproviders.

Zit je nog steeds vast?

  • GitHub-problemen: github.com/diegosouzapw/OmniRoute/issues
  • Architectuur: zie link voor interne details
  • API-referentie: zie link voor alle eindpunten
  • Gezondheidsdashboard: controleer Dashboard → Gezondheid voor de realtime systeemstatus
  • Vertaler: gebruik Dashboard → Vertaler om formaatproblemen op te lossen