Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
801 lines (541 loc) · 58.1 KB

TROUBLESHOOTING.md

File metadata and controls

801 lines (541 loc) · 58.1 KB
Raw

Troubleshooting (Slovenčina)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

Pre používateľov: Hľadáte rýchle riešenia? Pozrite si Stručnú referenčnú príručku nižšie.

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

Bežné problémy a ich riešenia pre OmniRoute.

Rýchly prehľad

Ste v OmniRoute noví? Začnite tu — tieto riešenia vyriešia 90 % problémov:

Zobrazuje sa mi Čo to znamená Čo treba urobiť
"Can't connect" OmniRoute nie je spustený Spustite omniroute alebo docker restart omniroute
"Invalid API key" Váš kľúč je nesprávny alebo jeho platnosť vypršala Znova skopírujte kľúč z webovej lokality poskytovateľa
"Rate limit exceeded" Odosielate príliš veľa požiadaviek Počkajte 1 minútu alebo použite model: "auto" na automatické prepnutie
"Quota exceeded" Vyčerpali ste svoju bezplatnú/platenú kvótu Pripojte ďalších poskytovateľov alebo použite bezplatných poskytovateľov (Kiro, Pollinations)
"Slow responses" Poskytovateľ je vyťažený alebo príliš vzdialený Použite model: "auto/fast" alebo pripojte rýchlejšieho poskytovateľa (Groq, Cerebras)
"Wrong provider used" auto vybral iného poskytovateľa To je normálne! auto vyberá najlepšieho. Konkrétneho poskytovateľa vynútite pomocou model: "openai/gpt-4o"
"502 Bad Gateway" Poskytovateľ je nedostupný Počkajte a skúste to znova alebo použite model: "auto" na prepnutie poskytovateľa
"401 Unauthorized" Vaše prihlasovacie údaje sú nesprávne Skontrolujte svoj API kľúč alebo sa znova overte pomocou OAuth
"omniroute is not recognized" V premennej Windows PATH chýbajú globálne moduly node Pridajte svoj globálny prefix npm do premennej Windows PATH. Zistíte ho pomocou npm config get prefix.
"429 Too Many Requests" Bola prekročená frekvencia požiadaviek Počkajte 1 minútu alebo pripojte ďalších poskytovateľov

Stále máte problém? Pozrite si podrobné riešenie problémov nižšie alebo sa opýtajte na Discorde.

Podrobné riešenie problémov

Obmedzovanie frekvencie požiadaviek u bezplatných poskytovateľov (429 / 400 / 401)

Príznak: Pri používaní model: "auto" s bezplatnými poskytovateľmi alebo poskytovateľmi bez overenia (opencode, auggie atď.) sa namiesto odpovedí občas zobrazí HTTP 429, 400 alebo 401. Pri opätovnom odoslaní rovnakej výzvy o chvíľu neskôr požiadavky uspejú, ale automatizácia (úlohy cron, agenti, skripty) zlyhá už pri prvej chybe.

Hlavná príčina: Súčasne sa prejavujú tri nezávislé režimy zlyhania:

  1. Obmedzenie frekvencie požiadaviek poskytovateľa (429): Bezplatné úrovne môžu vynucovať kvótu na časové okno. Dávka paralelných volaní ju vyčerpá, takže ďalšia požiadavka bude odmietnutá, kým sa časové okno neobnoví.
  2. Nefunkčný model pri priamom preposielaní (400/401): Fondy auto/* môžu obsahovať modely s priamym preposielaním od opencode, ktoré sú zaregistrované v katalógu, ale nemajú platné prihlasovacie údaje (napr. oc/north-mini-code-free → 401). Automatický smerovač jeden z nich vyskúša, zlyhá a chyba sa rozšíri skôr, než sa aktivuje záložný mechanizmus.
  3. Zosilnenie súbežnosťou (429 pri zaťažení): Keď viacero relácií agentov alebo úloh cron pristupuje k auto naraz, celková frekvencia požiadaviek prekročí toleranciu bezplatných poskytovateľov, takže legitímne volania sú označené ako zneužitie.

Overené riešenie (ohlásené komunitou, 2026-08-10): nastavte tri premenné prostredia tak, aby rotácia, súbežnosť a záložný mechanizmus zvládli nestabilitu bezplatnej úrovne namiesto toho, aby na nej zlyhali:

export OMNIROUTE_ROTATE_ON_400=true           # pri 400/401 prejsť na iný model/poskytovateľa (preskočí nefunkčné modely s priamym preposielaním)
export OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT=4   # explicitný maximálny počet prijatých náročných požiadaviek (predvolene nenastavené: bez obmedzenia počtu požiadaviek, pozrite si poznámku nižšie)
export OMNIROUTE_CHAT_ADMISSION_QUEUE_MS=5000 # dlhšie obmedzené čakanie na kapacitu pre náročné požiadavky namiesto okamžitej opakovateľnej chyby 503

Nastavte ich v prostredí procesu OmniRoute (v démonovi, napr. prostredníctvom súboru plist služby LaunchAgent alebo systemctl edit) a potom OmniRoute reštartujte. Príznak rotácie má zo všetkých nastavení najväčší účinok: zmení úplné zlyhanie na transparentný opakovaný pokus prostredníctvom funkčného poskytovateľa vo fonde.

Poznámka: OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT obmedzuje počet súčasne spustených náročných požiadaviek — požiadaviek s dlhým kontextom; toto obmedzenie je vstupnou bránou, nie obmedzovačom frekvencie požiadaviek poskytovateľa. Aktualizácia #503-fanout: táto premenná už nie je predvolene nastavená (teraz sa uplatní iba pri explicitnej konfigurácii, ako je uvedené vyššie) — prijímanie náročných požiadaviek namiesto toho riadi automaticky odvodený bajtový rozpočet (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES), ktorý sa prispôsobuje skutočnému pamäťovému limitu hostiteľa. Nové nasadenie by preto malo zaznamenať oveľa menej odmietnutí 503 chat_admission_busy bez potreby nastaviť túto premennú; jej explicitné nastavenie na tomto mieste naďalej funguje presne podľa dokumentácie. Explicitné prepisy bajtového rozpočtu sú obmedzené na 8 MiB–2 GiB. Chyba 413 body_exceeds_budget nie je dočasná: zvýšte tento bajtový rozpočet, znížte OMNIROUTE_CHAT_HARD_MAX_BODY_BYTES alebo zvýšte pamäťový limit procesu. Odmietnutie inflight_bytes_budget spôsobuje dočasné súperenie o prostriedky a požiadavku možno naďalej zopakovať. Obmedzovanie frekvencie požiadaviek pre jednotlivých poskytovateľov (open-sse/services/rateLimitManager.ts) osobitne riadia RATE_LIMIT_MAX_WAIT_MS, RATE_LIMIT_MAX_QUEUE_DEPTH a RATE_LIMIT_AUTO_ENABLE — pozrite si .env.example.

Ako overiť, že to funguje: spustite agenta/cron dvakrát rýchlo za sebou a overte, že obe spustenia uspejú. Pred opravou druhé spustenie zvyčajne vyhodí chybu 429/401. Po oprave sa neúspešné pokusy (ak sa vyskytnú) transparentne zopakujú a volanie sa dokončí. Môžete tiež spustiť curl /monitoring/health a sledovať pole rateLimitedUntil pri pripojeniach poskytovateľov a circuitBreakers.providerBreakers[].state pri dotknutých poskytovateľoch — stav je jeden z CLOSED, DEGRADED, OPEN alebo HALF_OPEN (pozrite si src/shared/utils/circuitBreaker.ts) a poskytovateľ, ktorého volania opakovane zlyhávajú, prejde zo stavu CLOSED → DEGRADED → OPEN, kým okno obnovenia nepovolí skúšobné volanie (HALF_OPEN).

Ak sa chyba 429 zobrazuje aj naďalej: aktívny účet daného poskytovateľa skutočne vyčerpal svoju kvótu (nejde iba o obmedzenie frekvencie požiadaviek). Pridajte druhý účet pre toho istého poskytovateľa v ovládacom paneli OmniRoute → Providers → Accounts alebo pridajte iného bezplatného poskytovateľa (napr. routeway, auggie). Rotácia pomáha iba pri prechodných chybách obmedzenia frekvencie požiadaviek/400/401; úplné vyčerpanie kvóty vyžaduje druhé prihlasovacie poverenie alebo iného poskytovateľa.

Ak sa pri modeloch na spracovanie obrazu (auto/vision, bazaarlink/*) zobrazuje chyba 403: pripojený účet nemá platený program, ktorý zahŕňa spracovanie obrazu, alebo API kľúč nemá dostatočné oprávnenia. V ovládacom paneli poskytovateľa overte, že rozsah oprávnení kľúča zahŕňa spracovanie obrazu/multimodálne funkcie, alebo pripojte účet s plateným programom a ponechajte ho ako cieľ pre spracovanie obrazu.

Upozornenia pri npm install (ERESOLVE / peer / deprecated)

Pri spustení npm install -g omniroute sa môže zobraziť množstvo upozornení, ako napríklad npm warn ERESOLVE, oznámenia o partnerských závislostiach a správy deprecated. Tieto upozornenia sú očakávané a neškodné. Inštalácia bola úspešná, ak sa vo výstupe zobrazí added <N> packages.

Ak chcete potlačiť upozornenia týkajúce sa riešenia partnerských závislostí, použite podporovaný spôsob inštalácie OmniRoute:

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

--legacy-peer-deps potlačí iba upozornenia ERESOLVE a oznámenia o partnerských závislostiach. Oznámenia o zastaraných balíkoch zostanú viditeľné, pretože pochádzajú z tranzitívnych balíkov tretích strán; neznamenajú, že inštalácia zlyhala.

Upozornenia pochádzajú zo zastaraných rozsahov partnerských závislostí v balíkoch tretích strán, ktoré OmniRoute nemá pod kontrolou:

  1. marked-terminal vyžaduje marked >=1 <16, našla sa verzia marked@18 — v praxi funguje správne; rozsah partnerskej závislosti v nadradenom projekte je iba zastaraný.
  2. deprecated prebuild-install@7.1.3 — tranzitívny pomocný nástroj na získavanie natívnych binárnych súborov. Nepoužíva sa na inštaláciu pripnutého transportného rozhrania wreq-js a neznamená, že nastavenie transportu poskytovateľa webových súborov cookie zlyhalo.

Nie je potrebná žiadna akcia — upozornenia nemožno úplne potlačiť bez vytvorenia forkov nadradených balíkov.

Gemini Web a Playwright Chromium

Ak požiadavka Gemini Web vráti stav 503 so správou, že Playwright Chromium nie je nainštalovaný, balík npm je prítomný, ale chýba binárny súbor prehliadača. Playwright zámerne oddeľuje sťahovanie prehliadačov od inštalácie balíkov npm, takže táto odpoveď je očakávaná, kým sa prehliadač nenainštaluje.

Pri globálnej inštalácii npm nainštalujte Chromium z adresára balíka OmniRoute, aby vyrovnávacia pamäť prehliadača patrila k rovnakej inštalácii Playwright:

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

Po inštalácii reštartujte OmniRoute a potom požiadavku Gemini Web zopakujte. Ak spúšťate OmniRoute z obrazu Docker, použite obraz -web (alebo cieľ zostavenia runner-web), ktorý obsahuje Chromium a jeho závislosti; základný obraz ich neobsahuje.

Rýchle riešenia

Problém Riešenie
Prvé prihlásenie nefunguje Nastavte INITIAL_PASSWORD v .env (bez pevne zakódovanej predvolenej hodnoty)
Ovládací panel sa otvára na nesprávnom porte Nastavte PORT=20128 a NEXT_PUBLIC_BASE_URL=http://localhost:20128
Na disk sa nezapisujú žiadne protokoly Nastavte APP_LOG_TO_FILE=true a overte, či je povolené zachytávanie protokolov volaní
EACCES: prístup odmietnutý Nastavte DATA_DIR=/path/to/writable/dir, čím prepíšete ~/.omniroute
Stratégia smerovania sa neukladá Aktualizujte na najnovšie vydanie v3.x (oprava schémy Zod pre ukladanie nastavení bola vydaná v skorších verziách)
Zlyhanie prihlásenia / prázdna stránka Skontrolujte verziu Node.js — pozrite si nižšie časť Kompatibilita s Node.js
dlopen / slice is not valid mach-o file (macOS) Spustite cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute — pozrite si nižšie časť Opätovné zostavenie natívneho modulu v systéme macOS
Proxy: „fetch failed“ Uistite sa, že konfigurácia proxy je nastavená na správnej úrovni — pozrite si nižšie časť Problémy s proxy
Docker curl: (56) Recv failure: Connection reset by peer Väzba portu Docker môže smerovať na IPv6. Použite -p 127.0.0.1:20128:20128, čím vynútite IPv4, alebo vykonajte test pomocou curl -4. Pozrite si nižšie časť Docker IPv6
Antivírus umiestni README.md do karantény Falošne pozitívny nález — pozrite si nižšie časť Falošne pozitívne nálezy antivírusu
Kaspersky označí desktopovú aplikáciu za trójskeho koňa Falošne pozitívny nález založený na správaní nepodpísaného inštalátora — pozrite si nižšie časť Falošne pozitívne nálezy antivírusu

Falošné pozitívne detekcie antivírusu

Avast/AVG umiestňuje README.md do karantény s detekciou MD:HttpRequest-inf[Susp]

Ide o falošne pozitívnu detekciu. Nič nie je infikované a nie je potrebné vykonať žiadne kroky.

Avast a AVG používajú heuristiku, ktorá označuje textové súbory alebo súbory Markdown obsahujúce veľa odkazov pripomínajúcich HTTP požiadavky. Súbor README.md projektu OmniRoute je súčasťou npm balíka (je uvedený v package.json → files), takže pri globálnej inštalácii sa uloží do node_modules/omniroute/README.md — a obsahuje približne 15 príkladov http://localhost:20128/... (koncové body MCP HTTP/SSE, adresu URL A2A .well-known a ukážky príkazov curl). Takáto hustota odkazov stačí na spustenie heuristiky.

Ak sa to začalo diať len nedávno: charakter súboru sa nezmenil. V README sa rozšírila tabuľka koncových bodov (boli pridané MCP HTTP + SSE + A2A) a pribudli ďalšie príklady príkazov curl, čím súbor prekročil prah detekcie.

Súbor je neaktívna dokumentácia bez akéhokoľvek spustiteľného obsahu. Môžete ho bezpečne obnoviť z karantény.

Čo treba urobiť:

  1. Zastavte upozornenia — pridajte inštalačný adresár medzi výnimky antivírusu (Avast: Nastavenia → Výnimky), pričom pridajte cestu ku globálnemu adresáru node_modules a/alebo dátový adresár OmniRoute (~/.omniroute/).
  2. Nahláste falošne pozitívnu detekciu — https://www.avast.com/false-positive-file-form.php, pričom priložte súbor README.md z karantény. Toto riešenie pomôže všetkým, pretože ide o neprimeranú reakciu heuristiky dodávateľa na textový súbor.

Prečo to „neopravíme“ na našej strane: všetky príklady používajú http://localhost a localhost nemožno používať cez https bez komplikácií so samopodpísaným certifikátom. Komolenie dokumentácie s cieľom obísť heuristiku jedného dodávateľa by poškodilo každého čitateľa len preto, aby sa vyhovelo chybe skenera.

Kaspersky označuje desktopovú aplikáciu ako PDM:Trojan.Win32.Generic

Ide o falošne pozitívnu detekciu behaviorálnej heuristiky. Nič nie je infikované. Predpona PDM: v produktoch Kaspersky znamená, že verdikt pochádza z modulu Proactive Defense Module (System Watcher), ktorý posudzuje, čo inštalátor robí, namiesto toho, aby ho porovnával so známym malvérom. Keď sa detekcia spustí, Kaspersky „vráti späť“ celú inštaláciu — odstráni súbory, ktoré už zapísal — takže aplikácia je následne poškodená alebo chýba.

Súbory, ktoré označuje, sú štandardnými súčasťami deklarovaných závislostí s otvoreným zdrojovým kódom, ktoré sú pribalené k desktopovej aplikácii, napríklad:

  • resources/app/.build/next/node_modules/playwright-<hash>/lib/…/agentParser.js a workerProcessEntry.js — Playwright, knižnica na automatizáciu prehliadača používaná na prihlasovanie k poskytovateľom v aplikácii a čet využívajúci prehliadač.
  • resources/app/.build/next/node_modules/@wreq-js/binding-win32-<arch>-msvc-<hash>/wreq-js.win32-<arch>-msvc.node — pripnutá natívna väzba wreq-js používaná na HTTP požiadavky s odtlačkom prehliadača pri poskytovateľoch využívajúcich webové súbory cookie (<arch> je x64 alebo arm64).

Prečo sa detekcia spustí: inštalátor pre Windows zatiaľ nie je podpísaný kódom, takže nepodpísaný inštalátor NSIS nemá žiadnu reputáciu a behaviorálne heuristiky pracujú s maximálnou agresivitou. V kombinácii s pribalenou natívnou knižnicou DLL a stovkami súborov .js zapisovaných do %LOCALAPPDATA%\Programs\OmniRoute (vrátane adresárov balíkov s príponou obsahujúcou hash zo samostatného zostavenia Next.js) to stačí na spustenie heuristiky. Podpisovanie kódu sa plánuje; dovtedy sa to môže opakovať pri každom novom vydaní.

Čo treba urobiť:

  1. Najskôr overte stiahnutý súbor (tým vylúčite manipuláciu so súborom). Každé vydanie obsahuje latest.yml, ktorého pole sha512 (base64) pokrýva inštalátor OmniRoute.Setup.<version>.exe. V prostredí PowerShell spustite v priečinku obsahujúcom inštalátor: 
    $b = [System.Security.Cryptography.SHA512]::Create().ComputeHash(
  [System.IO.File]::ReadAllBytes("$PWD\OmniRoute.Setup.<version>.exe"))
[Convert]::ToBase64String($b)
    Výstup sa musí zhodovať s hodnotou latest.yml → sha512. Ak sa nezhoduje, odstráňte súbor a znova ho stiahnite iba zo stránky vydaní na GitHube.
  2. Obnovte súbory a pridajte výnimku — obnovte položky odstránené pri vrátení inštalácie z karantény a pridajte výnimku pre %LOCALAPPDATA%\Programs\OmniRoute (Kaspersky → Nastavenia → Hrozby a výnimky), potom aplikáciu znova nainštalujte.
  3. Nahláste falošne pozitívnu detekciu — https://opentip.kaspersky.com/. Hlásenia falošne pozitívnych detekcií od používateľov skutočne urýchľujú pridanie do zoznamu povolených položiek.

Kompatibilita s Node.js

Prihlasovacia stránka zlyhá alebo zobrazí chybu „Module self-registration“

Príčina: Používate verziu Node.js mimo schváleného bezpečného rozsahu behového prostredia OmniRoute. Najčastejšie ide o používanie staršej opravnej verzie Node 22 alebo 24, ktorá nespĺňa minimálnu úroveň bezpečnostných opráv vyžadovanú službou OmniRoute.

Príznaky:

  • Prihlasovacia stránka zobrazí prázdnu obrazovku alebo chybu servera
  • Konzola zobrazí Error: Module did not self-register alebo podobné chyby natívnych väzieb
  • Ak je behového prostredie mimo podporovaných bezpečnostných pravidiel, na prihlasovacej stránke sa zobrazí oranžový výstražný banner s vašou verziou Node

Riešenie:

  1. Nainštalujte podporované vydanie Node.js LTS (odporúčané: Node.js 24.x): 
    nvm install 24
nvm use 24
  2. Overte svoju verziu: node --version by malo v rámci línie 24.x LTS zobraziť v24.0.0 alebo novšiu verziu
  3. Preinštalujte OmniRoute: npm install -g omniroute
  4. Reštartujte aplikáciu: omniroute

Podporované bezpečné verzie: >=22.22.2 <23 alebo >=24.0.0 <27. Node.js 24.x LTS (Krypton) a Node.js 26 sú plne podporované.

npm v11+: balík better-sqlite3 nie je nainštalovaný (Cannot find module)

Príčina: npm v11 (dodávaný s Node.js 24+) predvolene blokuje inštalačné skripty voliteľných závislostí. Keďže better-sqlite3 je uvedený v optionalDependencies a vyžaduje natívnu kompiláciu (node-gyp rebuild), npm ho bez upozornenia preskočí.

Príznaky:

  • Server pri spustení zlyhá s chybou Cannot find module 'better-sqlite3'
  • ls node_modules/better-sqlite3 zobrazí „No such file or directory“
  • npm ls better-sqlite3 zobrazí (empty)

Riešenie:

  1. Povoľte inštalačné skripty a vykonajte opätovnú inštaláciu: 
    npm approve-scripts better-sqlite3
npm install
  2. Alebo manuálne nainštalujte vopred zostavený balík: 
    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. Overte jeho funkčnosť: node -e "require('better-sqlite3')(':memory:').close(); console.log('OK')"

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

Príčina: Po globálnom spustení npm install -g omniroute mohol byť natívny binárny súbor better-sqlite3 v balíku skompilovaný pre inú architektúru alebo ABI Node.js, než aké sa používa lokálne. Je to bežné v systéme macOS (na platformách Apple Silicon aj Intel), keď vopred zostavený binárny súbor nezodpovedá vášmu prostrediu.

Príznaky:

  • Server ihneď po spustení zlyhá s chybou dlopen
  • Chyba obsahuje slice is not valid mach-o file
  • Úplný príklad:
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)

Riešenie — zostavte modul znova pre svoje lokálne prostredie (prechod na staršiu verziu Node.js nie je potrebný):

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

Poznámka: Týmto sa natívna väzba znova skompiluje pre vašu lokálnu verziu Node.js a architektúru procesora, čím sa vyrieši nezhoda binárnych súborov. Oficiálne podporovaný rozsah behového prostredia je >=22.22.2 <23 alebo >=24.0.0 <27 (SUPPORTED_NODE_RANGE v src/shared/utils/nodeRuntimeSupport.ts, zosúladený s poľom engines v súbore package.json). Node.js 24.x LTS (Krypton) a Node.js 26 sú plne podporované s better-sqlite3 v12.x.

Problémy s proxy

Overenie poskytovateľa zobrazuje „fetch failed“

Príčina: Koncový bod na overenie API kľúča (POST /api/providers/validate) predtým obchádzal konfiguráciu proxy, čo spôsobovalo zlyhania v prostrediach vyžadujúcich smerovanie cez proxy.

Oprava (v3.5.5+): Tento problém je teraz opravený. Overenie poskytovateľa je smerované cez runWithProxyContext, pričom sa automaticky rešpektujú nastavenia proxy na úrovni poskytovateľa aj globálne nastavenia proxy.

Kontrola stavu tokenu zlyhá s hlásením „fetch failed“

Príčina: Obnovovanie tokenov OAuth na pozadí neurčovalo konfiguráciu proxy pre jednotlivé pripojenia.

Oprava (v3.5.5+): Plánovač kontroly stavu tokenov teraz pred pokusom o obnovenie určuje konfiguráciu proxy pre každé pripojenie. Aktualizujte na v3.5.5+.

Proxy SOCKS5 vracia „invalid onRequestStart method“

Príčina: V Node.js 22 nie je dispatcher undici@8 kompatibilný so vstavanou implementáciou fetch() v Node.

Oprava (v3.5.5+): Keď je aktívny proxy dispatcher, OmniRoute teraz používa vlastnú funkciu fetch() z undici, čím zabezpečuje konzistentné správanie. Aktualizujte na v3.5.5+.

Proxy MITM vo WSL: desktopové aplikácie na hostiteľskom systéme Windows nie sú zachytávané

Príčina: Proxy MITM a jej certifikát CA sa nainštalujú do prostredia, v ktorom je spustený OmniRoute. Vo WSL je týmto prostredím hosťovský systém Linux, zatiaľ čo desktopové aplikácie AI (Kiro, Trae, Copilot, Zed, …) sú spustené na hostiteľskom systéme Windows. Hostiteľské aplikácie nedôverujú úložisku certifikátov hosťovského systému a nesmerujú komunikáciu cez systémovú proxy hosťovského systému, takže zachytávanie desktopových aplikácií sa v takomto prípade neaktivuje.

Odporúčanie: Spustite OmniRoute natívne v rovnakom operačnom systéme ako desktopové aplikácie, ktoré chcete zachytávať (Windows pre aplikácie systému Windows; obdobne pre macOS/Linux). Zachovanie OmniRoute vo WSL pri súčasnom zacielení na hostiteľské aplikácie vyžaduje manuálne nastaviť dôveryhodnosť vygenerovaného certifikátu CA na hostiteľskom systéme Windows a nasmerovať sieťové/proxy nastavenia každej hostiteľskej aplikácie na koncový bod proxy vo WSL — ide o nepodporované a nestabilné nastavenie.

Problémy s poskytovateľmi

„Language model did not provide messages“

Príčina: Kvóta poskytovateľa bola vyčerpaná.

Oprava:

  1. Skontrolujte sledovanie kvóty na ovládacom paneli
  2. Použite kombináciu so záložnými úrovňami
  3. Prepnite na lacnejšiu/bezplatnú úroveň

Obmedzenie rýchlosti

Príčina: Kvóta predplatného bola vyčerpaná.

Oprava:

  • Pridajte záložnú možnosť: cc/claude-opus-4-6 → glm/glm-4.7 → if/qwen3.8-max-preview
  • Použite GLM/MiniMax ako lacnú zálohu

Platnosť tokenu OAuth vypršala

OmniRoute automaticky obnovuje tokeny. Ak problémy pretrvávajú:

  1. Ovládací panel → Poskytovateľ → Znovu pripojiť
  2. Odstráňte pripojenie poskytovateľa a znova ho pridajte

Viacero účtov Kiro: druhý účet zneplatní prvý

Príčina: Backend služby Kiro vynucuje jednu aktívnu reláciu pre každú registráciu klienta OIDC. Keď dva účty zdieľajú rovnakého registrovaného klienta (pripojenia importované pred v3.8.0), obnovenie tokenu jedného účtu zneplatní obnovovací token druhého účtu.

Oprava (v3.8.0+): Znova importujte dotknuté pripojenia. Od verzie v3.8.0 si každé nové pripojenie Kiro vytvorené prostredníctvom možnosti Importovať token, Sociálne prihlásenie cez Google/GitHub alebo Automatický import automaticky zaregistruje vlastného vyhradeného klienta OIDC. Pripojenie je preto úplne izolované a obnovenie jedného účtu nemá žiadny vplyv na iný účet.

Pripojenia importované pred v3.8.0 nemajú registráciu klienta pre jednotlivé pripojenia. Tieto pripojenia naďalej používajú zdieľaný koncový bod na obnovenie sociálneho overenia. Ak chcete dosiahnuť izoláciu, odstráňte staré pripojenie cez Ovládací panel → Poskytovatelia a znova ho pridajte pomocou ktoréhokoľvek z troch spôsobov importu.

Úplné podrobnosti a podrobné pokyny na pridanie dvoch účtov Kiro vedľa seba nájdete v dokumente docs/guides/KIRO_SETUP.md.

Problémy s cloudom

Chyby synchronizácie s cloudom

  1. Overte, či BASE_URL smeruje na vašu spustenú inštanciu (napr. http://localhost:20128)
  2. Overte, či CLOUD_URL smeruje na váš cloudový koncový bod (napr. https://omniroute.dev)
  3. Udržiavajte hodnoty NEXT_PUBLIC_* zosúladené s hodnotami na strane servera

Cloud s stream=false vracia 500

Príznak: Unexpected token 'd'... na cloudovom koncovom bode pri volaniach bez streamovania.

Príčina: Nadradená služba vracia dáta SSE, zatiaľ čo klient očakáva JSON.

Dočasné riešenie: Pri priamych volaniach cloudu použite stream=true. Lokálne runtime prostredie obsahuje záložný prevod SSE→JSON.

Cloud hlási pripojenie, ale zobrazí „Invalid API key“

  1. Vytvorte nový kľúč v lokálnom dashboarde (/api/keys)
  2. Spustite synchronizáciu s cloudom: Enable Cloud → Sync Now
  3. Staré alebo nesynchronizované kľúče môžu v cloude stále vracať 401

Problémy s Dockerom

Docker IPv6 / resetovanie pripojenia

Príznaky: curl http://localhost:20128/v1/models vráti curl: (56) Recv failure: Connection reset by peer. Dashboard a neautentifikované koncové body fungujú, ale autentifikované koncové body zlyhávajú — vyzerá to ako problém s autentifikáciou, ale nie je.

Príčina: docker run -p 20128:20128 publikuje na 0.0.0.0 (IPv4) aj :: (IPv6), ale proces v kontajneri počúva iba na IPv4. Na hostiteľoch, kde sa localhost najskôr preloží na ::1, pripojenie smeruje na publikovaný port IPv6, za ktorým nie je žiadny počúvajúci proces → pripojenie sa resetuje.

Riešenie:

  1. Rýchla diagnostika: Spustite curl -4 http://localhost:20128/v1/models. Ak to s -4 funguje, ale bez neho zlyhá, máte nezhodu vo väzbe IPv6.
  2. Trvalé riešenie: Vynúťte väzbu na IPv4 použitím -p 127.0.0.1:20128:20128 v príkaze docker run: 
    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
    Týmto vynútite väzbu na IPv4 a zároveň zabránite sprístupneniu proxy na všetkých rozhraniach hostiteľa.

Nástroj CLI sa zobrazuje ako nenainštalovaný

  1. Skontrolujte polia runtime prostredia: curl http://localhost:20128/api/cli-tools/runtime/codex | jq
  2. Pre prenosný režim: použite cieľ obrazu runner-cli (s pribalenými nástrojmi CLI)
  3. Pre režim pripojenia z hostiteľa: nastavte CLI_EXTRA_PATHS a pripojte adresár binárnych súborov hostiteľa iba na čítanie
  4. Ak installed=true a runnable=false: binárny súbor bol nájdený, ale kontrola stavu zlyhala

Rýchle overenie runtime prostredia

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

Problémy s nákladmi

Vysoké náklady

  1. Skontrolujte štatistiky používania v Dashboard → Usage
  2. Prepnite primárny model na GLM/MiniMax
  3. Na nekritické úlohy použite bezplatnú úroveň (Qoder, Kiro)
  4. Nastavte rozpočty nákladov pre jednotlivé kľúče API: Dashboard → API Keys → Budget

Ladenie

Povolenie súborov denníka

Nastavte APP_LOG_TO_FILE=true v súbore .env. Denníky aplikácie sa zapisujú do adresára logs/. Artefakty požiadaviek sa ukladajú do ${DATA_DIR}/call_logs/, keď je v nastaveniach povolený proces zaznamenávania volaní. Keď je povolené zachytávanie v procese, nastavte CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=false, aby sa vynechali dáta fragmentov streamu, alebo upravte CALL_LOG_PIPELINE_MAX_SIZE_KB, ak chcete zmeniť limit veľkosti artefaktov v kB.

Kontrola stavu poskytovateľa

# Dashboard stavu
http://localhost:20128/dashboard/health

# Kontrola stavu API
curl http://localhost:20128/api/monitoring/health

Úložisko runtime prostredia

  • Hlavný stav: ${DATA_DIR}/storage.sqlite (poskytovatelia, kombinácie, aliasy, kľúče, nastavenia)
  • Používanie: tabuľky SQLite v storage.sqlite (usage_history, call_logs, proxy_logs) + voliteľne ${DATA_DIR}/call_logs/
  • Denníky aplikácie: <repo>/logs/... (keď APP_LOG_TO_FILE=true)
  • Artefakty denníka volaní: ${DATA_DIR}/call_logs/YYYY-MM-DD/..., keď je povolený proces zaznamenávania volaní

Akcia Clean history na stránke Request Logs vymaže call_logs, staršie request_detail_logs a lokálny adresár artefaktov ${DATA_DIR}/call_logs/.

Problémy s ističom

Poskytovateľ uviazol v stave OPEN

Keď je istič poskytovateľa v stave OPEN, požiadavky sú blokované až do uplynutia času obnovenia.

Riešenie:

  1. Prejdite na Dashboard → Settings → Resilience
  2. Skontrolujte kartu ističa pre dotknutého poskytovateľa
  3. Kliknutím na Reset All vymažte všetky ističe alebo počkajte na uplynutie času obnovenia
  4. Pred resetovaním overte, či je poskytovateľ skutočne dostupný

Poskytovateľ opakovane aktivuje istič

Ak poskytovateľ opakovane prechádza do stavu OPEN:

  1. Skontrolujte vzorec zlyhaní v časti Dashboard → Health → Provider Health
  2. Prejdite na Settings → Resilience → Provider Profiles a zvýšte prah zlyhaní
  3. Skontrolujte, či poskytovateľ nezmenil limity API alebo nevyžaduje opätovné overenie
  4. Skontrolujte telemetriu latencie — vysoká latencia môže spôsobovať zlyhania v dôsledku prekročenia časového limitu

Problémy s prepisom zvuku

Chyba „Unsupported model“

  • Použite ID modelu, ktorého prvý segment zodpovedá poskytovateľovi, pre ktorého máte prihlasovacie údaje (openai/whisper-1, openrouter/deepgram/nova-3). Samostatné deepgram/nova-3 vyžaduje natívny kľúč Deepgram.
  • Overte, či je poskytovateľ pripojený v časti Dashboard → Providers

Prepis je prázdny alebo zlyhá

  • Skontrolujte podporované zvukové formáty: mp3, wav, m4a, flac, ogg, webm
  • Overte, či je veľkosť súboru v rámci limitov poskytovateľa (zvyčajne < 25MB)
  • Na karte poskytovateľa skontrolujte platnosť kľúča API

Ladenie prekladača

Na ladenie problémov s prevodom formátov použite Dashboard → Translator:

Režim Kedy ho použiť
Playground Porovnajte vstupné a výstupné formáty vedľa seba — vložte zlyhávajúcu požiadavku a pozrite sa, ako sa prevedie
Chat Tester Odosielajte živé správy a kontrolujte kompletný obsah požiadavky a odpovede vrátane hlavičiek
Test Bench Spustite dávkové testy naprieč kombináciami formátov a zistite, ktoré prevody nefungujú
Live Monitor Sledujte tok požiadaviek v reálnom čase a zachyťte občasné problémy s prevodom

Bežné problémy s formátmi

  • Značky uvažovania sa nezobrazujú — Skontrolujte, či cieľový poskytovateľ podporuje uvažovanie, a nastavenie rozpočtu na uvažovanie
  • Volania nástrojov sa strácajú — Niektoré prevody formátov môžu odstrániť nepodporované polia; overte to v režime Playground
  • Chýba systémová výzva — Claude a Gemini spracúvajú systémové výzvy odlišne; skontrolujte výstup prevodu
  • SDK vracia nespracovaný reťazec namiesto objektu — Vyriešené vo v1.x; sanitizátor odpovedí odstraňuje neštandardné polia (x_groq, usage_breakdown atď.), ktoré spôsobujú zlyhania validácie Pydantic v OpenAI SDK. Ak sa tento problém stále vyskytuje vo v3.x+, nahláste ho.
  • GLM/ERNIE odmieta rolu system — Vyriešené vo v1.x; normalizátor rolí automaticky zlučuje systémové správy s používateľskými správami pre nekompatibilné modely. Ak sa tento problém stále vyskytuje vo v3.x+, nahláste ho.
  • Rola developer nebola rozpoznaná — Vyriešené vo v1.x; pre poskytovateľov iných než OpenAI sa automaticky konvertuje na system. Ak sa tento problém stále vyskytuje vo v3.x+, nahláste ho.
  • json_schema nefunguje s Gemini — Vyriešené vo v1.x; response_format sa teraz konvertuje na responseMimeType + responseSchema Gemini. Ak sa tento problém stále vyskytuje vo v3.x+, nahláste ho.

Nastavenia odolnosti

Automatické obmedzenie frekvencie sa nespúšťa

  • Automatické obmedzenie frekvencie sa vzťahuje iba na poskytovateľov s API kľúčom (nie na OAuth/predplatné)
  • Overte, či je v časti Nastavenia → Odolnosť → Profily poskytovateľov povolené automatické obmedzenie frekvencie
  • Skontrolujte, či poskytovateľ vracia stavové kódy 429 alebo hlavičky Retry-After

Ladenie exponenciálneho odstupu

Profily poskytovateľov podporujú tieto nastavenia:

  • Základné oneskorenie — Počiatočný čas čakania po prvom zlyhaní (predvolene: 1s)
  • Maximálne oneskorenie — Horný limit času čakania (predvolene: 30s)
  • Násobiteľ — Miera zvýšenia oneskorenia pri každom po sebe nasledujúcom zlyhaní (predvolene: 2x)

Ochrana proti lavínovému efektu

Keď veľa súbežných požiadaviek zasiahne poskytovateľa s obmedzenou frekvenciou, OmniRoute používa mutex + automatické obmedzenie frekvencie na serializáciu požiadaviek a zabránenie kaskádovým zlyhaniam. Pre poskytovateľov s API kľúčom je to automatické.

Požiadavky chatu zlyhávajú s chybou 503 / chat_admission_busy

Príznaky:

  • Koncový bod na dokončenia chatu vracia opakovateľnú odpoveď 503, ktorej chybový kód je chat_admission_busy.
  • Odpoveď obsahuje Retry-After. Od verzie #12135 sa hodnota odvodzuje od pozorovaného vyťaženia — použije sa väčšia hodnota z časového okna OMNIROUTE_CHAT_ADMISSION_QUEUE_MS, počas ktorého už požiadavka čakala, a času, počas ktorého sú držané aktuálne prenájmy pre náročné požiadavky — zaokrúhlená nahor na celé sekundy a obmedzená na 60. Pri nevyťaženej bráne zachováva historické minimá: 2 sekundy pre cestu založenú na bajtoch, 1 sekundu pre cestu založenú na štruktúre (ktorá obsahuje aj reason: "structure_limit").
  • Môže sa to stať, kým stále prebieha iný náročný chat alebo dlhotrvajúca streamovaná odpoveď.

Telo odpovede založenej na bajtoch je:

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

Odpoveď založená na štruktúre používa rovnaký typ a kód so správou Local chat admission capacity is busy for this structurally heavy request; upstream provider routing was not attempted. Retry shortly. a reason: "structure_limit". Pri predvolených prahových hodnotách je požiadavka štrukturálne náročná, ak obsahuje aspoň 200 správ, aspoň 64 nástrojov alebo aspoň 32,000 odhadovaných tokenov, prípadne ak obmedzený odhad štruktúry vyčerpá svoje limity 10,000 navštívených uzlov alebo hĺbku 12.

Príčina: Ide o zámerné odľahčenie záťaže v rámci OmniRoute, nie o zlyhanie upstreamového poskytovateľa. Každý proces používa lokálnu ochranu procesu na rezerváciu obmedzenej kapacity pre náročné požiadavky ešte pred uchovaním a spracovaním veľkého tela požiadavky. Prenájom pre náročnú požiadavku zostáva držaný počas celej životnosti SSE odpovede.

#503-fanout: pred touto opravou ochrana obmedzovala súbežnosť pevným POČTOM požiadaviek (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT, predvolene 1) bez ohľadu na pamäť hostiteľa, takže rozvetvenie kódovacích agentov (viacero subagentov/CLI, telá bežne > 256 KB) viedlo k efektívnej súbežnosti ~1 a chybám 503 pri úplne bežnom zaťažení. Ochrana sa teraz automaticky prispôsobuje: riadi sa automaticky odvodeným BAJTOVÝM rozpočtom príjmu (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES) stanoveným podľa skutočného pamäťového limitu procesu a zároveň zohľadňuje živý signál tlaku na zdroje — takže odmieta požiadavky iba vtedy, keď je hostiteľ skutočne pod tlakom na pamäť, nie iba preto, že naraz prišlo viac než jedna náročná požiadavka. Starý limit počtu (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT) sa naďalej rešpektuje, ale iba ak ho explicitne nastavíte.

Keď je kapacita obsadená, náročná požiadavka najprv čaká až OMNIROUTE_CHAT_ADMISSION_QUEUE_MS (predvolene 2000, hodnota 0 čakanie zakáže), kým sa uvoľní miesto, a až potom vráti opakovateľnú chybu 503. Obmedzené čakanie existuje preto, aby klienti typu agent (OpenCode, Claude Code, Cursor), ktorí súbežne rozvetvujú náročné podpožiadavky, serializovali nápor namiesto vyčerpania celého rozpočtu opakovaných pokusov okamžitými odmietnutiami a zlyhania uprostred úlohy. Aktuálne vyťaženie prenájmov pre náročné požiadavky, určený bajtový rozpočet a aktuálna závažnosť tlaku sú dostupné na GET /api/monitoring/health → chatAdmission (inflightBytes, maxInflightBytes, budgetSource, pressureSeverity, countCapEnabled) — skontrolujte ich skôr, než zmeníte akúkoľvek premennú prostredia. Nastavenia → Odolnosť → Front požiadaviek → Súbežné požiadavky toto neovláda; toto nastavenie riadi samostatný mechanizmus frontu požiadaviek poskytovateľa.

Oprava:

  1. Najprv požiadavku zopakujte. Klienti by mali rešpektovať Retry-After a používať odstup namiesto okamžitého opakovania požiadavky.
  2. Pred ladením čohokoľvek skontrolujte /api/monitoring/health → chatAdmission. countCapEnabled: false a veľkorysá hodnota maxInflightBytes znamenajú, že automaticky odvodený rozpočet už funguje správne; hodnota pressureSeverity nastavená na high/critical znamená, že hostiteľ má skutočne nedostatok pamäte — to nemožno opraviť premennou prostredia pre prijímanie požiadaviek, ale vyžaduje si to viac RAM alebo menšiu pracovnú záťaž.
  3. Iba ak /api/monitoring/health ukazuje, že automaticky odvodený rozpočet je pre vášho hostiteľa skutočne príliš malý (čo je zriedkavé — už sa škáluje od kontajnerov až po bare-metal), prepíšte ho priamo pomocou OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES namiesto návratu k zastaranému limitu počtu požiadaviek.

Autoritatívne nastavenia prijímania požiadaviek nájdete v referenčnej dokumentácii premenných prostredia.

Voliteľná taxonómia zlyhaní RAG / LLM (16 problémov)

Niektorí používatelia OmniRoute umiestňujú bránu pred RAG alebo agentové systémy. V takýchto konfiguráciách sa často objavuje zvláštny jav: OmniRoute vyzerá byť v poriadku (poskytovatelia sú dostupní, smerovacie profily fungujú, žiadne upozornenia na obmedzenie frekvencie požiadaviek), no konečná odpoveď je napriek tomu nesprávna.

V praxi tieto incidenty zvyčajne pochádzajú z nadväzujúceho RAG pipeline, nie zo samotnej brány.

Ak chcete používať spoločnú terminológiu na opis týchto zlyhaní, môžete použiť WFGY ProblemMap, externý textový zdroj s licenciou MIT, ktorý definuje šestnásť opakujúcich sa vzorov zlyhaní RAG / LLM. Na vysokej úrovni zahŕňa:

  • odklon pri vyhľadávaní a narušené hranice kontextu
  • prázdne alebo zastarané indexy a vektorové úložiská
  • nesúlad embeddingov a sémantiky
  • problémy so zostavovaním promptov a kontextovým oknom
  • kolaps logiky a príliš sebavedomé odpovede
  • zlyhania dlhých reťazcov a koordinácie agentov
  • odklon pamäte a rolí medzi viacerými agentmi
  • problémy s poradím nasadenia a inicializácie

Myšlienka je jednoduchá:

  1. Pri vyšetrovaní nesprávnej odpovede zaznamenajte:
    • úlohu a požiadavku používateľa
    • trasu alebo kombináciu poskytovateľov v OmniRoute
    • akýkoľvek RAG kontext použitý v nadväzujúcom spracovaní (vyhľadané dokumenty, volania nástrojov atď.)
  2. Priraďte incident k jednému alebo dvom číslam vo WFGY ProblemMap (No.1 … No.16).
  3. Uložte číslo vo svojom dashboarde, prevádzkovej príručke alebo systéme na sledovanie incidentov vedľa protokolov OmniRoute.
  4. Pomocou príslušnej stránky WFGY rozhodnite, či potrebujete zmeniť svoj RAG systém, vyhľadávací mechanizmus alebo stratégiu smerovania.

Úplný text a konkrétne postupy nájdete tu (licencia MIT, iba text):

README WFGY ProblemMap

Ak za OmniRoute neprevádzkujete RAG alebo agentové pipeline, môžete túto časť ignorovať.

Známe problémy vo v3.8.0

Problémy špecifické pre vydanie v3.8.0 a ich aktuálne náhradné riešenia. Ak bude oprava zahrnutá v neskoršej opravnej verzii, príslušná položka sa aktualizuje alebo odstráni.

Zlyhania autentifikácie Devin CLI

Príznaky:

  • „Devin CLI sa nenašlo“ alebo „autentifikácia zlyhala“ pri spúšťaní nástrojov založených na Devin
  • Kontrola prostredia CLI hlási installed=false

Príčiny:

  • CLI_DEVIN_BIN odkazuje na cestu, ktorá neexistuje
  • Devin CLI nie je na hostiteľovi nainštalované

Oprava:

  1. Nainštalujte Devin CLI pre svoju platformu
  2. Nastavte CLI_DEVIN_BIN=/usr/local/bin/devin (alebo skutočnú cestu) v .env
  3. Reštartujte OmniRoute a zopakujte test cez Dashboard → Nástroje CLI

Model zostal zablokovaný v režime ochladzovania (manuálne obnovenie)

Príznaky:

  • Model zostáva uvedený v režime ochladzovania aj po uplynutí času platnosti
  • Požiadavky pri kombinovanom smerovaní model stále preskakujú, hoci časová značka je už v minulosti

Manuálne obnovenie:

  • Dashboard: Nastavenia → Ochladzovanie modelov → na príslušnej karte kliknite na Znova povoliť
  • API: DELETE /api/resilience/model-cooldowns s hlavičkami autentifikácie správy

Pripojenie poskytovateľa Command Code zlyhá s chybou 403

Príznaky:

  • Chyba 403 pri testovaní pripojenia k poskytovateľovi Command Code
  • Po novom pridaní sa na karte poskytovateľa zobrazuje „neautorizované“

Príčina: Tok OAuth sa nedokončil (spätné volanie nebolo prijaté alebo token nebol uložený).

Oprava:

  • Spustením omniroute providers z CLI znova aktivujte tok OAuth alebo
  • Znova spustite OAuth cez Dashboard → Poskytovatelia → Command Code → Znova pripojiť

ModelScope vracia agresívne ochladzovanie pri chybe 429

Príznaky:

  • Veľmi krátke alebo okamžité ochladzovanie ModelScope po malej dávke požiadaviek
  • Kombinované smerovanie preskočí ModelScope skôr, než sa očakáva

Príčina: ModelScope odosiela hlavičky Retry-After špecifické pre poskytovateľa. v3.8.0 obsahuje špecializované spracovanie týchto hlavičiek, takže staršie verzie ich nesprávne interpretujú ako všeobecné indikátory obmedzenia frekvencie požiadaviek.

Oprava:

  • Uistite sa, že používate v3.8.0 alebo novšiu verziu
  • Skontrolujte, či je prepínač useUpstream429BreakerHints povolený v časti Nastavenia → Odolnosť

Chýbajúca premenná OMNIROUTE_WS_BRIDGE_SECRET v produkčnom prostredí

Príznaky:

  • Chyba 401 pri každej požiadavke na WebSocket most Codex/Responses pri spustení na vzdialenom produkčnom hostiteľovi
  • Nadviazanie spojenia s WebSocket mostom sa ukončí ihneď po pripojení

Príčina: V produkčnom prostredí chýba premenná prostredia OMNIROUTE_WS_BRIDGE_SECRET.

Oprava:

  1. Vygenerujte náhodný tajný kľúč: openssl rand -hex 32
  2. Nastavte OMNIROUTE_WS_BRIDGE_SECRET=<random-secret> v prostredí produkčného servera (a v každom klientovi, ktorý komunikuje s mostom)
  3. Reštartujte OmniRoute

Responses API: režim na pozadí degradovaný na synchrónny

Príznaky:

  • Zaznamenané upozornenie: background mode degraded to synchronous
  • Požiadavka s background: true vráti normálnu synchrónnu odpoveď namiesto identifikátora úlohy na pozadí

Príčina: v3.8.0 zámerne degraduje background: true v Responses API na synchrónne vykonávanie a zároveň vygeneruje upozornenie. Úplné asynchrónne vykonávanie na pozadí je plánované do budúcnosti.

Oprava:

  • Upravte klienta tak, aby volanie vykonával bez background, alebo
  • Počkajte na neskoršie vydanie, ktoré bude obsahovať úplný asynchrónny režim na pozadí (sledujte zoznam zmien)

Pomalé spustenie / časový limit pripravenosti

Ak CLI zobrazí ⚠ Server did not respond within 60s, ale server v skutočnosti funguje, limit sondy pripravenosti je pre vaše prostredie príliš krátky.

Bežne sa to stáva v systéme Windows (antivírus, sledovanie súborového systému) alebo v kontajneroch s náročnými úlohami pri spustení.

Riešenie — zvýšte časový limit:

# Prostredníctvom premennej prostredia (platí aj pri ďalších spusteniach):
export OMNIROUTE_READY_TIMEOUT_MS=180000   # 3 minúty
omniroute serve

# Prostredníctvom príznaku CLI (jednorazovo):
omniroute serve --ready-timeout 180000

Predvolená hodnota je 60 000 ms (60 s). Upozornenie má iba informatívny charakter; server pokračuje v spúšťaní na pozadí a po dokončení spustenia bude dostupný.

Úplné podrobnosti o OMNIROUTE_READY_TIMEOUT_MS nájdete v súbore docs/reference/ENVIRONMENT.md.

Stále máte problémy?