Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
801 lines (541 loc) · 58.3 KB

TROUBLESHOOTING.md

File metadata and controls

801 lines (541 loc) · 58.3 KB
Raw

Troubleshooting (Čeština)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇩🇰 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 · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

Pro uživatele: Hledáte rychlá řešení? Podívejte se níže na Stručný přehled.

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇩🇰 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 · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

Běžné problémy a jejich řešení pro OmniRoute.

Rychlý přehled

Začínáte s OmniRoute? Začněte zde — tato řešení vyřeší 90 % problémů:

Co se zobrazuje Co to znamená Co dělat
„Nelze se připojit“ OmniRoute není spuštěný Spusťte omniroute nebo docker restart omniroute
„Neplatný klíč API“ Váš klíč je nesprávný nebo vypršel Zkopírujte klíč znovu z webu poskytovatele
„Překročen limit požadavků“ Odesíláte příliš mnoho požadavků Počkejte 1 minutu nebo použijte model: "auto" pro automatický přechod na záložní možnost
„Překročena kvóta“ Vyčerpali jste bezplatnou nebo placenou kvótu Připojte více poskytovatelů nebo použijte bezplatné poskytovatele (Kiro, Pollinations)
„Pomalé odpovědi“ Poskytovatel je vytížený nebo příliš vzdálený Použijte model: "auto/fast" nebo připojte rychlejšího poskytovatele (Groq, Cerebras)
„Použit nesprávný poskytovatel“ auto vybralo jiného poskytovatele To je normální! auto vybírá nejlepšího. Konkrétního poskytovatele vynuťte pomocí model: "openai/gpt-4o"
„502 Bad Gateway“ Poskytovatel je mimo provoz Počkejte a zkuste to znovu nebo použijte model: "auto" k přepnutí poskytovatele
„401 Unauthorized“ Vaše přihlašovací údaje jsou nesprávné Zkontrolujte svůj klíč API nebo se znovu ověřte pomocí OAuth
„omniroute nebyl rozpoznán“ V proměnné Windows PATH chybějí globální moduly node Přidejte globální prefix npm do proměnné Windows PATH. Zjistíte ho pomocí npm config get prefix.
„429 Too Many Requests“ Byl překročen limit požadavků Počkejte 1 minutu nebo připojte více poskytovatelů

Stále si nevíte rady? Podívejte se níže na podrobné řešení problémů nebo se zeptejte na Discordu.

Podrobné řešení problémů

Omezování počtu požadavků u bezplatných poskytovatelů (429 / 400 / 401)

Příznak: Při použití model: "auto" s bezplatnými poskytovateli nebo poskytovateli bez ověřování (opencode, auggie atd.) se vám místo odpovědí občas zobrazí HTTP 429, 400 nebo 401. Když stejný pokyn o chvíli později odešlete znovu, požadavky uspějí, ale automatizace (úlohy cron, agenti, skripty) se přeruší hned při prvním selhání.

Základní příčina: Sčítají se tři nezávislé režimy selhání:

  1. Limit požadavků poskytovatele (429): Bezplatné úrovně mohou vynucovat kvótu pro určité časové období. Náhlá série souběžných volání ji vyčerpá, takže další požadavek je odmítnut, dokud se časové období neobnoví.
  2. Nefunkční model v režimu passthrough (400/401): Fondy auto/* mohou obsahovat modely passthrough od opencode, které jsou registrovány v katalogu, ale nemají platné přihlašovací údaje (např. oc/north-mini-code-free → 401). Automatický směrovač některý z nich vyzkouší, selže a chyba se rozšíří dříve, než se aktivuje záložní možnost.
  3. Zesílení souběžností (429 při zátěži): Když k auto současně přistupuje více relací agentů nebo úloh cron, souhrnná frekvence požadavků překročí míru, kterou bezplatní poskytovatelé tolerují, takže jsou legitimní volání označena za zneužití.

Ověřená oprava (nahlášeno komunitou, 2026-08-10): Upravte tři proměnné prostředí tak, aby rotace, souběžnost a záložní možnosti zvládaly nestabilitu bezplatných úrovní namísto toho, aby kvůli ní selhávaly:

export OMNIROUTE_ROTATE_ON_400=true           # při 400/401 přejít na jiný model nebo poskytovatele (přeskočí nefunkční modely passthrough)
export OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT=4   # explicitní horní limit přijímání náročných požadavků (ve výchozím nastavení nenastaveno: bez omezení počtu požadavků, viz poznámka níže)
export OMNIROUTE_CHAT_ADMISSION_QUEUE_MS=5000 # delší omezené čekání na kapacitu pro náročné požadavky namísto okamžité opakovatelné chyby 503

Nastavte je v prostředí procesu OmniRoute (démonu, např. prostřednictvím plist LaunchAgent nebo systemctl edit) a poté OmniRoute restartujte. Příznak rotace má zdaleka největší dopad: mění definitivní selhání na transparentní opakovaný pokus u funkčního poskytovatele ve fondu.

Poznámka: OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT omezuje počet náročných požadavků — požadavků s dlouhým kontextem — spuštěných současně; tento limit je vstupní branou, nikoli omezovačem počtu požadavků poskytovatele. Aktualizace #503-fanout: tato proměnná již není ve výchozím nastavení nastavena (nyní se použije pouze při explicitní konfiguraci, jako výše) — přijímání náročných požadavků je namísto toho řízeno automaticky odvozeným bajtovým rozpočtem (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES), který se přizpůsobuje skutečnému paměťovému limitu hostitele, takže by se v nové instalaci mělo bez jakéhokoli nastavování této proměnné objevovat mnohem méně odmítnutí 503 chat_admission_busy; její explicitní nastavení zde stále funguje přesně podle dokumentace. Explicitně zadané bajtové rozpočty jsou omezeny na rozsah 8 MiB–2 GiB. Chyba 413 body_exceeds_budget není dočasná: zvyšte tento bajtový rozpočet, snižte OMNIROUTE_CHAT_HARD_MAX_BODY_BYTES nebo zvyšte paměťový limit procesu. Odmítnutí inflight_bytes_budget je způsobeno dočasným soupeřením o prostředky a požadavek lze nadále opakovat. Omezování počtu požadavků pro jednotlivé poskytovatele (open-sse/services/rateLimitManager.ts) je řízeno samostatně pomocí RATE_LIMIT_MAX_WAIT_MS, RATE_LIMIT_MAX_QUEUE_DEPTH a RATE_LIMIT_AUTO_ENABLE — viz .env.example.

Jak ověřit, že oprava funguje: spusťte svého agenta/cron dvakrát rychle po sobě a ověřte, že obě spuštění proběhnou úspěšně. Před opravou druhé spuštění obvykle vyvolá chybu 429/401. Po opravě se neúspěšné požadavky (pokud k nim dojde) transparentně zopakují a volání se dokončí. Můžete také spustit curl /monitoring/health a sledovat pole rateLimitedUntil u připojení poskytovatelů a circuitBreakers.providerBreakers[].state u dotčených poskytovatelů — stav může být CLOSED, DEGRADED, OPEN nebo HALF_OPEN (viz src/shared/utils/circuitBreaker.ts) a poskytovatel, u kterého chyby přetrvávají, přejde přes stavy CLOSED → DEGRADED → OPEN, než okno pro reset umožní průchod testovacího požadavku (HALF_OPEN).

Pokud se stále zobrazuje chyba 429: aktivní účet daného poskytovatele skutečně vyčerpal svou kvótu (nejde pouze o omezení frekvence požadavků). Přidejte druhý účet stejného poskytovatele v ovládacím panelu OmniRoute → Providers → Accounts nebo zapojte jiného bezplatného poskytovatele (např. routeway, auggie). Rotace pomáhá pouze s přechodnými chybami omezení frekvence požadavků/400/401; úplné vyčerpání kvóty vyžaduje druhé přihlašovací údaje nebo jiného poskytovatele.

Pokud se u modelů pro vizuální vstupy (auto/vision, bazaarlink/*) zobrazuje chyba 403: připojený účet nemá placený tarif zahrnující zpracování vizuálních vstupů nebo API klíč nemá dostatečná oprávnění. V ovládacím panelu poskytovatele ověřte, že rozsah oprávnění klíče zahrnuje zpracování vizuálních/multimodálních vstupů, případně připojte účet s placeným tarifem a ponechte jej jako cíl pro vizuální vstupy.

Varování při npm install (ERESOLVE / peer / deprecated)

Při spuštění npm install -g omniroute se může zobrazit záplava varování, například npm warn ERESOLVE, upozornění na peer závislosti a zprávy deprecated. Tato varování jsou očekávaná a neškodná. Instalace proběhla úspěšně, pokud ve výstupu vidíte added <N> packages.

Chcete-li potlačit varování při řešení peer závislostí, použijte podporovaný způsob instalace OmniRoute:

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

--legacy-peer-deps potlačuje pouze upozornění ERESOLVE a upozornění na peer závislosti. Upozornění na zastaralé balíčky zůstávají viditelná, protože pocházejí z tranzitivních balíčků třetích stran; neznamenají, že instalace selhala.

Varování pocházejí ze zastaralých rozsahů peer závislostí v balíčcích třetích stran, které OmniRoute nemůže ovlivnit:

  1. marked-terminal vyžaduje marked >=1 <16, nalezeno marked@18 — v praxi funguje bez problémů; rozsah peer závislosti v upstream balíčku je pouze zastaralý.
  2. deprecated prebuild-install@7.1.3 — tranzitivní pomocný nástroj pro stahování nativních binárních souborů. Nepoužívá se k instalaci připnutého transportního rozhraní wreq-js a neznamená, že nastavení transportu poskytovatele webových cookies selhalo.

Není vyžadována žádná akce — bez forknutí upstream balíčků nelze tato varování zcela potlačit.

Gemini Web a Playwright Chromium

Pokud požadavek Gemini Web vrátí stav 503 se zprávou, že Playwright Chromium není nainstalován, balíček npm je přítomen, ale chybí binární soubor prohlížeče. Playwright záměrně odděluje stahování prohlížečů od instalace balíčku npm, takže tato odpověď je očekávaná, dokud prohlížeč nenainstalujete.

U globální instalace npm nainstalujte Chromium z adresáře balíčku OmniRoute, aby mezipaměť prohlížeče patřila ke stejné instalaci Playwright:

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

Po instalaci restartujte OmniRoute a poté požadavek Gemini Web zopakujte. Pokud OmniRoute spouštíte z obrazu Docker, použijte obraz -web (nebo cíl sestavení runner-web), který obsahuje Chromium a jeho závislosti; základní obraz je neobsahuje.

Rychlá řešení

Problém Řešení
První přihlášení nefunguje Nastavte INITIAL_PASSWORD v .env (žádná pevně zakódovaná výchozí hodnota)
Řídicí panel se otevírá na nesprávném portu Nastavte PORT=20128 a NEXT_PUBLIC_BASE_URL=http://localhost:20128
Na disk se nezapisují žádné protokoly Nastavte APP_LOG_TO_FILE=true a ověřte, že je povoleno zaznamenávání protokolů volání
EACCES: oprávnění zamítnuto Nastavením DATA_DIR=/path/to/writable/dir přepište ~/.omniroute
Strategie směrování se neukládá Aktualizujte na nejnovější vydání v3.x (oprava schématu Zod pro trvalé ukládání nastavení byla vydána v dřívějších verzích)
Pád při přihlášení / prázdná stránka Zkontrolujte verzi Node.js — viz níže Kompatibilita s Node.js
dlopen / slice is not valid mach-o file (macOS) Spusťte cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute — viz níže opětovné sestavení nativního modulu v macOS
Proxy hlásí „fetch failed“ Ujistěte se, že je konfigurace proxy nastavena na správné úrovni — viz níže Problémy s proxy
Docker curl: (56) Recv failure: Connection reset by peer Vazba portu Docker může směřovat na IPv6. Použijte -p 127.0.0.1:20128:20128 k vynucení IPv4 nebo testujte pomocí curl -4. Viz níže Docker IPv6
Antivirus umístí README.md do karantény Falešně pozitivní detekce — viz níže Falešně pozitivní detekce antiviru
Kaspersky označí desktopovou aplikaci za trojského koně Falešně pozitivní detekce chování nepodepsaného instalátoru — viz níže Falešně pozitivní detekce antiviru

Falešně pozitivní nálezy antiviru

Avast/AVG umisťuje README.md do karantény s detekcí MD:HttpRequest-inf[Susp]

Jde o falešně pozitivní nález. Nic není infikováno a není nutné podnikat žádné kroky.

Avast a AVG používají heuristiku, která označuje prosté textové soubory a soubory Markdown obsahující mnoho odkazů připomínajících HTTP požadavky. Soubor README.md projektu OmniRoute je součástí npm balíčku (je uveden v package.json → files), takže při globální instalaci skončí v node_modules/omniroute/README.md — a obsahuje přibližně 15 příkladů http://localhost:20128/... (koncové body MCP HTTP/SSE, adresu URL A2A .well-known a ukázky příkazu curl). Tato hustota odkazů stačí ke spuštění heuristiky.

Pokud se problém objevil teprve nedávno: podstata souboru se nezměnila. V README se rozšířila tabulka koncových bodů (byly přidány MCP HTTP + SSE + A2A) a přibyly další příklady curl, čímž byla překročena prahová hodnota.

Soubor je neaktivní dokumentace bez jakéhokoli spustitelného obsahu. Můžete jej bezpečně obnovit z karantény.

Co dělat:

  1. Zastavte upozornění — v antiviru vylučte instalační adresář (Avast: Nastavení → Výjimky) přidáním cesty ke globálnímu adresáři node_modules a/nebo datovému adresáři OmniRoute (~/.omniroute/).
  2. Nahlaste falešně pozitivní nález — https://www.avast.com/false-positive-file-form.php, přiložte soubor README.md z karantény. Toto řešení pomůže všem, protože se jedná o přehnanou reakci heuristiky výrobce na textový soubor.

Proč to „neopravujeme“ na naší straně: všechny příklady používají http://localhost a localhost nelze používat přes https bez komplikací s certifikátem podepsaným svým držitelem. Znehodnocení dokumentace kvůli obejití heuristiky jednoho výrobce by poškodilo všechny čtenáře jen proto, aby se vyhovělo chybě skeneru.

Kaspersky označuje desktopovou aplikaci jako PDM:Trojan.Win32.Generic

Jde o falešně pozitivní nález behaviorální heuristiky. Nic není infikováno. Předpona PDM: společnosti Kaspersky znamená, že verdikt pochází z modulu Proactive Defense Module (System Watcher), který posuzuje, co instalační program dělá, místo aby jej porovnával se známým malwarem. Když se detekce spustí, Kaspersky „vrátí zpět“ celou instalaci — odstraní soubory, které již zapsal — takže aplikace zůstane poškozená nebo bude zcela chybět.

Soubory, které označuje, jsou standardními součástmi deklarovaných open-source závislostí přibalených k desktopové aplikaci, například:

  • resources/app/.build/next/node_modules/playwright-<hash>/lib/…/agentParser.js a workerProcessEntry.js — Playwright, knihovna pro automatizaci prohlížeče používaná pro přihlašování k poskytovatelům v aplikaci a chat využívající prohlížeč.
  • resources/app/.build/next/node_modules/@wreq-js/binding-win32-<arch>-msvc-<hash>/wreq-js.win32-<arch>-msvc.node — připnutá nativní vazba wreq-js používaná pro HTTP s otiskem prohlížeče u poskytovatelů využívajících webové cookies (<arch> je x64 nebo arm64).

Proč se detekce spouští: instalační program pro Windows zatím není podepsán kódem, takže nepodepsaný instalační program NSIS nemá žádnou reputaci a behaviorální heuristiky pracují s maximální agresivitou. V kombinaci s přibalenou nativní knihovnou DLL a stovkami souborů .js zapisovaných do %LOCALAPPDATA%\Programs\OmniRoute (včetně adresářů balíčků s příponami hashů ze samostatného sestavení Next.js) to stačí ke spuštění heuristiky. Podepisování kódu je plánováno; dokud nebude zavedeno, může se situace u nových vydání opakovat.

Co dělat:

  1. Nejprve ověřte stažený soubor (tím vyloučíte, že byl pozměněn). Každé vydání zveřejňuje soubor latest.yml, jehož pole sha512 (base64) pokrývá instalační soubor OmniRoute.Setup.<version>.exe. V PowerShellu spusťte ze složky obsahující instalační soubor: 
    $b = [System.Security.Cryptography.SHA512]::Create().ComputeHash(
  [System.IO.File]::ReadAllBytes("$PWD\OmniRoute.Setup.<version>.exe"))
[Convert]::ToBase64String($b)
    Výstup se musí shodovat s latest.yml → sha512. Pokud se neshoduje, soubor odstraňte a stáhněte jej znovu výhradně ze stránky vydání na GitHubu.
  2. Obnovte + vylučte — obnovte z karantény položky odstraněné při vrácení instalace zpět a přidejte výjimku pro %LOCALAPPDATA%\Programs\OmniRoute (Kaspersky → Nastavení → Hrozby a výjimky), poté proveďte instalaci znovu.
  3. Nahlaste falešně pozitivní nález — https://opentip.kaspersky.com/. Hlášení falešně pozitivních nálezů odeslaná uživateli skutečně urychlují přidání na seznam povolených položek.

Kompatibilita s Node.js

Přihlašovací stránka padá nebo zobrazuje chybu „Module self-registration“

Příčina: Používáte verzi Node.js, která nesplňuje minimální požadavky zabezpečeného běhového prostředí schváleného pro OmniRoute. Nejčastěji jde o starší opravnou verzi Node 22 nebo 24, která je nižší než opravená bezpečná verze vyžadovaná OmniRoute.

Příznaky:

  • Přihlašovací stránka zobrazuje prázdnou obrazovku nebo chybu serveru
  • Konzole zobrazuje Error: Module did not self-register nebo podobné chyby nativních vazeb
  • Pokud běhové prostředí nevyhovuje podporovaným zásadám zabezpečení, zobrazí přihlašovací stránka oranžový varovný pruh s vaší verzí Node

Řešení:

  1. Nainstalujte podporovanou verzi Node.js LTS (doporučeno: Node.js 24.x): 
    nvm install 24
nvm use 24
  2. Ověřte svou verzi: node --version by měl ve větvi 24.x LTS zobrazit v24.0.0 nebo novější
  3. Znovu nainstalujte OmniRoute: npm install -g omniroute
  4. Restartujte aplikaci: omniroute

Podporované bezpečné verze: >=22.22.2 <23 nebo >=24.0.0 <27. Node.js 24.x LTS (Krypton) a Node.js 26 jsou plně podporovány.

npm v11+: better-sqlite3 není nainstalován (modul nelze najít)

Příčina: npm v11 (dodávaný s Node.js 24+) ve výchozím nastavení blokuje instalační skripty volitelných závislostí. Protože je better-sqlite3 uveden v optionalDependencies a vyžaduje nativní kompilaci (node-gyp rebuild), npm jej bez upozornění přeskočí.

Příznaky:

  • Server při spuštění spadne s chybou Cannot find module 'better-sqlite3'
  • ls node_modules/better-sqlite3 zobrazí „No such file or directory“
  • npm ls better-sqlite3 zobrazí (empty)

Řešení:

  1. Schvalte instalační skripty a proveďte novou instalaci: 
    npm approve-scripts better-sqlite3
npm install
  2. Případně nainstalujte předkompilovaný balíček ručně: 
    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. Ověřte funkčnost: node -e "require('better-sqlite3')(':memory:').close(); console.log('OK')"

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

Příčina: Po globálním spuštění npm install -g omniroute mohl být nativní binární soubor better-sqlite3 uvnitř balíčku zkompilován pro jinou architekturu nebo ABI Node.js, než jaké se používají lokálně. K tomu běžně dochází v systému macOS (na Apple Silicon i Intel), pokud předkompilovaný binární soubor neodpovídá vašemu prostředí.

Příznaky:

  • Server ihned při spuštění selže s chybou dlopen
  • Chyba obsahuje slice is not valid mach-o file
  • Úplný pří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)

Řešení — znovu sestavte modul pro své lokální prostředí (přechod na starší verzi Node.js není nutný):

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

Poznámka: Tím se nativní vazba znovu zkompiluje pro vaši lokální verzi Node.js a architekturu procesoru, čímž se vyřeší nekompatibilita binárního souboru. Oficiálně podporovaný rozsah běhového prostředí je >=22.22.2 <23 nebo >=24.0.0 <27 (SUPPORTED_NODE_RANGE v src/shared/utils/nodeRuntimeSupport.ts, v souladu s polem engines v package.json). Node.js 24.x LTS (Krypton) a Node.js 26 jsou plně podporovány s better-sqlite3 v12.x.

Problémy s proxy

Ověření poskytovatele zobrazuje chybu „fetch failed“

Příčina: Koncový bod pro ověření klíče API (POST /api/providers/validate) dříve obcházel konfiguraci proxy, což způsobovalo selhání v prostředích, která vyžadují směrování přes proxy.

Oprava (v3.5.5+): Tento problém je nyní opraven. Ověření poskytovatele probíhá prostřednictvím runWithProxyContext a automaticky respektuje nastavení proxy na úrovni poskytovatele i globální nastavení proxy.

Kontrola platnosti tokenu selhává s chybou „fetch failed“

Příčina: Obnovování tokenů OAuth na pozadí nevyhodnocovalo konfiguraci proxy pro jednotlivá připojení.

Oprava (v3.5.5+): Plánovač kontroly platnosti tokenů nyní před pokusem o obnovení vyhodnotí konfiguraci proxy pro každé připojení. Aktualizujte na v3.5.5+.

Proxy SOCKS5 vrací chybu „invalid onRequestStart method“

Příčina: V Node.js 22 není dispatcher z undici@8 kompatibilní s vestavěnou implementací fetch() v Node.js.

Oprava (v3.5.5+): Když je aktivní dispatcher proxy, OmniRoute nyní používá vlastní funkci fetch() z undici, čímž zajišťuje konzistentní chování. Aktualizujte na v3.5.5+.

Proxy MITM ve WSL: desktopové aplikace v hostitelském systému Windows nejsou zachycovány

Příčina: Proxy MITM a její certifikát CA se instalují do prostředí, ve kterém běží OmniRoute. Ve WSL je tímto prostředím hostovaný systém Linux, zatímco desktopové aplikace AI (Kiro, Trae, Copilot, Zed, …) běží v hostitelském systému Windows. Hostitelské aplikace nedůvěřují úložišti certifikátů hostovaného systému a nesměrují provoz přes jeho systémovou proxy, takže u nich k zachytávání desktopového provozu nedochází.

Doporučení: Spusťte OmniRoute nativně ve stejném operačním systému jako desktopové aplikace, jejichž provoz chcete zachytávat (Windows pro aplikace ve Windows; obdobně pro macOS/Linux). Ponechání OmniRoute uvnitř WSL při cílení na hostitelské aplikace vyžaduje ručně nastavit důvěryhodnost vygenerovaného certifikátu CA v hostitelském systému Windows a nasměrovat síťová nastavení či nastavení proxy každé hostitelské aplikace na koncový bod proxy ve WSL — jde o nepodporované a nespolehlivé řešení.

Problémy s poskytovateli

„Language model did not provide messages“

Příčina: Kvóta poskytovatele byla vyčerpána.

Oprava:

  1. Zkontrolujte ukazatel kvóty na řídicím panelu
  2. Použijte kombinaci se záložními úrovněmi
  3. Přejděte na levnější nebo bezplatnou úroveň

Omezování počtu požadavků

Příčina: Kvóta předplatného byla vyčerpána.

Oprava:

  • Přidejte záložní varianty: cc/claude-opus-4-6 → glm/glm-4.7 → if/qwen3.8-max-preview
  • Použijte GLM/MiniMax jako levnou zálohu

Platnost tokenu OAuth vypršela

OmniRoute tokeny automaticky obnovuje. Pokud problémy přetrvávají:

  1. Řídicí panel → Poskytovatel → Znovu připojit
  2. Odstraňte připojení poskytovatele a znovu jej přidejte

Více účtů Kiro: druhý účet zneplatní první

Příčina: Backend služby Kiro vynucuje pouze jednu aktivní relaci pro každou registraci klienta OIDC. Když dva účty sdílejí stejného registrovaného klienta (připojení importovaná před v3.8.0), obnovení tokenu jednoho účtu zneplatní obnovovací token druhého účtu.

Oprava (v3.8.0+): Znovu importujte dotčená připojení. Od verze v3.8.0 si každé nové připojení Kiro vytvořené prostřednictvím možnosti Importovat token, Sociální přihlášení přes Google/GitHub nebo Automatický import automaticky zaregistruje vlastního vyhrazeného klienta OIDC. Připojení je proto zcela izolované a obnovení jednoho účtu nemá žádný vliv na ostatní účty.

Připojení importovaná před v3.8.0 nemají registraci klienta pro jednotlivá připojení. Tato připojení nadále používají sdílený koncový bod pro obnovení prostřednictvím sociálního přihlášení. Chcete-li dosáhnout izolace, odstraňte staré připojení v části Řídicí panel → Poskytovatelé a znovu je přidejte pomocí kteréhokoli ze tří způsobů importu.

Úplné podrobnosti a podrobné pokyny k přidání dvou účtů Kiro vedle sebe najdete v souboru docs/guides/KIRO_SETUP.md.

Problémy s cloudem

Chyby synchronizace s cloudem

  1. Ověřte, že BASE_URL odkazuje na vaši spuštěnou instanci (např. http://localhost:20128)
  2. Ověřte, že CLOUD_URL odkazuje na váš cloudový koncový bod (např. https://omniroute.dev)
  3. Udržujte hodnoty NEXT_PUBLIC_* v souladu s hodnotami na straně serveru

Cloud při stream=false vrací 500

Příznak: Unexpected token 'd'... na cloudovém koncovém bodu u volání bez streamování.

Příčina: Nadřazená služba vrací datovou část SSE, zatímco klient očekává JSON.

Alternativní řešení: Pro přímá cloudová volání použijte stream=true. Lokální běhové prostředí obsahuje záložní převod SSE→JSON.

Cloud hlásí připojení, ale také „Neplatný klíč API“

  1. Vytvořte nový klíč na lokálním řídicím panelu (/api/keys)
  2. Spusťte synchronizaci s cloudem: Povolit cloud → Synchronizovat nyní
  3. Staré či nesynchronizované klíče mohou v cloudu stále vracet 401

Problémy s Dockerem

IPv6 v Dockeru / resetování připojení

Příznaky: curl http://localhost:20128/v1/models vrací curl: (56) Recv failure: Connection reset by peer. Řídicí panel a koncové body bez ověřování fungují, ale ověřované koncové body selhávají — vypadá to jako problém s ověřováním, ale není.

Příčina: docker run -p 20128:20128 zveřejní port na 0.0.0.0 (IPv4) i :: (IPv6), ale proces uvnitř kontejneru naslouchá pouze na IPv4. Na hostitelích, kde se localhost nejprve překládá na ::1, se připojení dostane na zveřejněný port IPv6, za kterým žádný proces nenaslouchá → připojení se resetuje.

Oprava:

  1. Rychlá diagnostika: Spusťte curl -4 http://localhost:20128/v1/models. Pokud s -4 funguje, ale bez něj selže, máte nesoulad ve vazbě IPv6.
  2. Trvalá oprava: Navažte port explicitně na IPv4 pomocí -p 127.0.0.1:20128:20128 v příkazu 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ím vynutíte vazbu na IPv4 a zároveň zabráníte zpřístupnění proxy na všech síťových rozhraních hostitele.

Nástroj CLI se zobrazuje jako nenainstalovaný

  1. Zkontrolujte pole běhového prostředí: curl http://localhost:20128/api/cli-tools/runtime/codex | jq
  2. Pro přenosný režim: použijte cíl obrazu runner-cli (obsahuje nástroje CLI)
  3. Pro režim s připojením hostitele: nastavte CLI_EXTRA_PATHS a připojte adresář s binárními soubory hostitele pouze pro čtení
  4. Pokud installed=true a runnable=false: binární soubor byl nalezen, ale kontrola stavu selhala

Rychlé ověření běhového prostředí

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áklady

Vysoké náklady

  1. Zkontrolujte statistiky využití v části Řídicí panel → Využití
  2. Přepněte primární model na GLM/MiniMax
  3. Pro úlohy, které nejsou kritické, použijte bezplatnou úroveň (Qoder, Kiro)
  4. Nastavte rozpočty nákladů pro jednotlivé klíče API: Řídicí panel → Klíče API → Rozpočet

Ladění

Povolení souborů protokolu

Nastavte APP_LOG_TO_FILE=true v souboru .env. Protokoly aplikace se zapisují do adresáře logs/. Artefakty požadavků se ukládají do ${DATA_DIR}/call_logs/, když je v nastavení povolena pipeline protokolování volání. Když je povoleno zachytávání v pipeline, nastavte CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=false, chcete-li vynechat datové části streamovaných fragmentů, nebo upravte CALL_LOG_PIPELINE_MAX_SIZE_KB, chcete-li změnit limit velikosti artefaktů v KB.

Kontrola stavu poskytovatele

# Řídicí panel stavu
http://localhost:20128/dashboard/health

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

Úložiště běhového prostředí

  • Hlavní stav: ${DATA_DIR}/storage.sqlite (poskytovatelé, kombinace, aliasy, klíče, nastavení)
  • Využití: tabulky SQLite v storage.sqlite (usage_history, call_logs, proxy_logs) + volitelně ${DATA_DIR}/call_logs/
  • Protokoly aplikace: <repo>/logs/... (když je APP_LOG_TO_FILE=true)
  • Artefakty protokolů volání: ${DATA_DIR}/call_logs/YYYY-MM-DD/..., když je povolena pipeline protokolování volání

Akce Vymazat historii na stránce Protokoly požadavků vymaže call_logs, starší request_detail_logs a lokální adresář artefaktů ${DATA_DIR}/call_logs/.

Problémy s jističem

Poskytovatel uvízl ve stavu OPEN

Když je jistič poskytovatele ve stavu OPEN, požadavky jsou blokovány, dokud neuplyne doba ochlazení.

Řešení:

  1. Přejděte do části Řídicí panel → Nastavení → Odolnost
  2. Zkontrolujte kartu jističe příslušného poskytovatele
  3. Kliknutím na Resetovat vše resetujte všechny jističe, případně počkejte, až uplyne doba ochlazení
  4. Před resetováním ověřte, že je poskytovatel skutečně dostupný

Poskytovatel opakovaně aktivuje jistič

Pokud poskytovatel opakovaně přechází do stavu OPEN:

  1. Zkontrolujte vzorec selhání v části Řídicí panel → Stav → Stav poskytovatelů
  2. Přejděte do části Nastavení → Odolnost → Profily poskytovatelů a zvyšte prahovou hodnotu selhání
  3. Zkontrolujte, zda poskytovatel nezměnil limity API nebo nevyžaduje opětovné ověření
  4. Projděte telemetrii latence — vysoká latence může způsobovat selhání kvůli vypršení časového limitu

Problémy s přepisem zvuku

Chyba „Nepodporovaný model“

  • Použijte ID modelu, jehož první částí je poskytovatel, pro kterého máte přihlašovací údaje (openai/whisper-1, openrouter/deepgram/nova-3). Samotný identifikátor deepgram/nova-3 vyžaduje nativní klíč Deepgram.
  • Ověřte, že je poskytovatel připojen v části Řídicí panel → Poskytovatelé

Přepis je prázdný nebo selže

  • Zkontrolujte podporované zvukové formáty: mp3, wav, m4a, flac, ogg, webm
  • Ověřte, že velikost souboru nepřekračuje limity poskytovatele (obvykle < 25MB)
  • Na kartě poskytovatele zkontrolujte platnost klíče API poskytovatele

Ladění překladače

K ladění problémů s převodem formátů použijte část Řídicí panel → Překladač:

Režim Kdy jej použít
Hřiště Porovnejte vstupní a výstupní formáty vedle sebe — vložte selhávající požadavek a podívejte se, jak se převede
Tester chatu Odesílejte živé zprávy a kontrolujte kompletní datovou část požadavku a odpovědi včetně hlaviček
Testovací prostředí Spouštějte dávkové testy různých kombinací formátů a zjistěte, které převody jsou nefunkční
Živé sledování Sledujte tok požadavků v reálném čase a zachyťte občasné problémy s převodem

Běžné problémy s formáty

  • Nezobrazují se značky uvažování — Zkontrolujte, zda cílový poskytovatel podporuje uvažování, a ověřte nastavení rozpočtu pro uvažování
  • Volání nástrojů se ztrácejí — Některé převody formátů mohou odstranit nepodporovaná pole; ověřte to v režimu Hřiště
  • Chybí systémová výzva — Claude a Gemini zpracovávají systémové výzvy odlišně; zkontrolujte výstup převodu
  • SDK vrací nezpracovaný řetězec namísto objektu — Vyřešeno ve v1.x; nástroj pro sanitizaci odpovědí odstraňuje nestandardní pole (x_groq, usage_breakdown atd.), která způsobují selhání validace Pydantic v OpenAI SDK. Pokud tento problém stále pozorujete ve v3.x+, nahlaste jej.
  • GLM/ERNIE odmítá roli system — Vyřešeno ve v1.x; normalizátor rolí u nekompatibilních modelů automaticky slučuje systémové zprávy se zprávami uživatele. Pokud tento problém stále pozorujete ve v3.x+, nahlaste jej.
  • Role developer není rozpoznána — Vyřešeno ve v1.x; u poskytovatelů jiných než OpenAI je automaticky převedena na system. Pokud tento problém stále pozorujete ve v3.x+, nahlaste jej.
  • json_schema nefunguje s Gemini — Vyřešeno ve v1.x; response_format se nyní převádí na responseMimeType + responseSchema pro Gemini. Pokud tento problém stále pozorujete ve v3.x+, nahlaste jej.

Nastavení odolnosti

Automatické omezení rychlosti se neaktivuje

  • Automatické omezení rychlosti se vztahuje pouze na poskytovatele používající klíče API (nikoli OAuth/předplatné)
  • Ověřte, že je v části Settings → Resilience → Provider Profiles povoleno automatické omezení rychlosti
  • Zkontrolujte, zda poskytovatel vrací stavové kódy 429 nebo hlavičky Retry-After

Ladění exponenciálního prodlužování prodlevy

Profily poskytovatelů podporují tato nastavení:

  • Základní prodleva — Počáteční doba čekání po prvním selhání (výchozí: 1s)
  • Maximální prodleva — Horní limit doby čekání (výchozí: 30s)
  • Násobitel — O kolik se má prodleva zvýšit při každém po sobě jdoucím selhání (výchozí: 2x)

Ochrana před nárazovým souběhem požadavků

Když mnoho souběžných požadavků narazí na poskytovatele s omezenou rychlostí, OmniRoute používá mutex + automatické omezení rychlosti k serializaci požadavků a zabránění kaskádovým selháním. U poskytovatelů používajících klíče API je toto chování automatické.

Požadavky chatu selhávají s 503 / chat_admission_busy

Příznaky:

  • Koncový bod pro dokončování chatu vrací opakovatelnou odpověď 503, jejíž kód chyby je chat_admission_busy.
  • Odpověď obsahuje Retry-After. Od verze #12135 je hodnota odvozena od pozorovaného vytížení — použije se vyšší z hodnot: okno OMNIROUTE_CHAT_ADMISSION_QUEUE_MS, po které již požadavek čekal, a doba, po kterou jsou drženy aktuální výpočetně náročné lease — zaokrouhlená nahoru na celé sekundy a omezená na maximálně 60. U nečinné brány zachovává historická minima: 2 sekundy pro cestu založenou na bajtech, 1 sekundu pro cestu založenou na struktuře (která také obsahuje reason: "structure_limit").
  • K tomu může dojít, když stále probíhá jiný výpočetně náročný chat nebo dlouhotrvající streamovaná odpověď.

Tělo odpovědi založené na bajtech je:

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

Odpověď založená na struktuře používá stejný typ a kód se zprávou Local chat admission capacity is busy for this structurally heavy request; upstream provider routing was not attempted. Retry shortly. a reason: "structure_limit". Při výchozích prahových hodnotách je požadavek považován za strukturálně náročný, pokud obsahuje alespoň 200 zpráv, alespoň 64 nástrojů nebo alespoň 32,000 odhadovaných tokenů, případně pokud omezený odhad struktury vyčerpá své limity 10,000 navštívených uzlů nebo hloubky 12.

Příčina: Jde o záměrné odlehčení zátěže uvnitř OmniRoute, nikoli o selhání nadřazeného poskytovatele. Každý proces používá lokální ochranu procesu k rezervaci omezené kapacity pro výpočetně náročné požadavky ještě před uchováním a analýzou velkého těla požadavku. Lease pro výpočetně náročný požadavek zůstává držen po celou dobu životnosti odpovědi SSE.

#503-fanout: před touto opravou omezovala ochrana souběžnost pevným POČTEM požadavků (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT, výchozí 1) bez ohledu na paměť hostitele, takže souběžné větvení kódovacích agentů (více subagentů/CLI, těla běžně > 256 KB) snižovalo efektivní souběžnost přibližně na 1 a při zcela běžném zatížení vedlo k odpovědím 503. Ochrana se nyní přizpůsobuje automaticky: řídí se automaticky odvozeným BAJTOVÝM rozpočtem pro příjem (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES) určeným podle skutečného paměťového limitu procesu a také zohledňuje živý signál zatížení prostředků — zátěž tedy omezuje pouze tehdy, když je hostitel skutečně pod tlakem kvůli nedostatku paměti, nikoli jen proto, že dorazil více než jeden náročný požadavek současně. Původní limit počtu (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT) je nadále respektován, ale pouze pokud jej explicitně nastavíte.

Když je kapacita obsazena, výpočetně náročný požadavek nejprve čeká až OMNIROUTE_CHAT_ADMISSION_QUEUE_MS (výchozí 2000, hodnota 0 čekání zakáže) na uvolnění místa a teprve poté vrátí opakovatelnou odpověď 503. Omezené čekání existuje proto, aby klienti fungující jako agenti (OpenCode, Claude Code, Cursor), kteří souběžně větví náročné dílčí požadavky, serializovali nárazovou zátěž, místo aby vyčerpali celý svůj limit opakování okamžitými odmítnutími a selhali uprostřed úlohy. Aktuální obsazenost lease pro výpočetně náročné požadavky, vypočtený bajtový rozpočet a aktuální závažnost tlaku jsou k dispozici na GET /api/monitoring/health → chatAdmission (inflightBytes, maxInflightBytes, budgetSource, pressureSeverity, countCapEnabled) — před změnou jakékoli proměnné prostředí je zkontrolujte. Settings → Resilience → Request Queue → Concurrent Requests toto chování neovládá; dané nastavení řídí samostatný mechanismus fronty požadavků poskytovatele.

Řešení:

  1. Nejprve požadavek zopakujte. Klienti by měli respektovat Retry-After a používat prodlužování prodlevy namísto okamžitého opakování požadavku.
  2. Před jakýmkoli laděním zkontrolujte /api/monitoring/health → chatAdmission. countCapEnabled: false a dostatečně vysoká hodnota maxInflightBytes znamenají, že automaticky odvozený rozpočet již funguje správně; hodnota pressureSeverity nastavená na high/critical znamená, že hostitel má skutečně nedostatek paměti — to nelze vyřešit proměnnou prostředí pro přijímání požadavků, ale vyžaduje to více paměti RAM nebo menší pracovní zátěž.
  3. Pouze pokud /api/monitoring/health ukazuje, že automaticky odvozený rozpočet je pro vašeho hostitele skutečně příliš malý (což je vzácné — již se škáluje od kontejnerů až po fyzické servery), přepište jej přímo pomocí OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES namísto návratu ke staršímu limitu počtu požadavků.

Směrodatná nastavení přijímání požadavků najdete v referenci proměnných prostředí.

Volitelná taxonomie selhání RAG / LLM (16 problémů)

Někteří uživatelé OmniRoute umisťují bránu před RAG nebo agentní stacky. V takových konfiguracích se běžně objevuje zvláštní vzorec: OmniRoute vypadá v pořádku (poskytovatelé jsou dostupní, profily směrování jsou správně nastavené, žádná upozornění na omezení rychlosti), ale výsledná odpověď je přesto chybná.

V praxi tyto incidenty obvykle pocházejí z navazujícího RAG pipeline, nikoli ze samotné brány.

Pokud chcete používat společnou terminologii pro popis těchto selhání, můžete využít WFGY ProblemMap, externí textový zdroj s licencí MIT, který definuje šestnáct opakujících se vzorců selhání RAG / LLM. Na obecné úrovni zahrnuje:

  • odchylky při vyhledávání a narušené hranice kontextu
  • prázdné nebo zastaralé indexy a vektorová úložiště
  • nesoulad embeddingů a sémantiky
  • problémy se sestavováním promptů a kontextovým oknem
  • zhroucení logiky a přehnaně sebejisté odpovědi
  • selhání dlouhých řetězců a koordinace agentů
  • problémy s pamětí více agentů a odchylky rolí
  • problémy s pořadím nasazení a inicializace

Princip je jednoduchý:

  1. Při vyšetřování chybné odpovědi zaznamenejte:
    • úlohu a požadavek uživatele
    • trasu nebo kombinaci poskytovatelů v OmniRoute
    • veškerý RAG kontext použitý v navazujícím zpracování (načtené dokumenty, volání nástrojů atd.)
  2. Přiřaďte incident k jednomu nebo dvěma číslům ve WFGY ProblemMap (No.1 … No.16).
  3. Uložte číslo do vlastního řídicího panelu, provozní příručky nebo systému pro sledování incidentů vedle protokolů OmniRoute.
  4. Pomocí odpovídající stránky WFGY rozhodněte, zda potřebujete změnit svůj RAG stack, retriever nebo strategii směrování.

Úplný text a konkrétní postupy naleznete zde (licence MIT, pouze text):

README WFGY ProblemMap

Pokud za OmniRoute neprovozujete RAG nebo agentní pipeline, můžete tuto část ignorovat.

Známé problémy ve v3.8.0

Problémy specifické pro vydání v3.8.0 a jejich aktuální náhradní řešení. Pokud bude oprava zahrnuta v pozdější opravné verzi, položka bude aktualizována nebo odstraněna.

Selhání autentizace Devin CLI

Příznaky:

  • „Devin CLI nebylo nalezeno“ nebo „autentizace selhala“ při volání nástrojů využívajících Devin
  • Kontrola běhového prostředí CLI hlásí installed=false

Příčiny:

  • CLI_DEVIN_BIN odkazuje na cestu, která neexistuje
  • Devin CLI není na hostiteli nainstalováno

Oprava:

  1. Nainstalujte Devin CLI pro svou platformu
  2. Nastavte CLI_DEVIN_BIN=/usr/local/bin/devin (nebo skutečnou cestu) v .env
  3. Restartujte OmniRoute a proveďte nový test v části Řídicí panel → Nástroje CLI

Zaseknuté pozastavení modelu (ruční reset)

Příznaky:

  • Model zůstává uveden jako pozastavený i po uplynutí doby platnosti
  • Požadavky při kombinovaném směrování model stále přeskakují, přestože časové razítko je již v minulosti

Ruční reset:

  • Řídicí panel: Nastavení → Pozastavení modelů → na kartě příslušného modelu klikněte na Znovu povolit
  • API: DELETE /api/resilience/model-cooldowns s autentizačními hlavičkami pro správu

Připojení k poskytovateli Command Code selhává s chybou 403

Příznaky:

  • Chyba 403 při testování připojení k poskytovateli Command Code
  • Karta poskytovatele po novém přidání zobrazuje stav „neautorizováno“

Příčina: Tok OAuth nebyl dokončen (zpětné volání nebylo přijato nebo token nebyl trvale uložen).

Oprava:

  • Spusťte omniroute providers z CLI, abyste znovu aktivovali tok OAuth, nebo
  • Znovu spusťte OAuth v části Řídicí panel → Poskytovatelé → Command Code → Znovu připojit

ModelScope vrací agresivní pozastavení 429

Příznaky:

  • Velmi krátká nebo okamžitá pozastavení ModelScope po malé dávce požadavků
  • Kombinované směrování přeskakuje ModelScope dříve, než se očekávalo

Příčina: ModelScope odesílá hlavičky Retry-After specifické pro poskytovatele. v3.8.0 obsahuje vyhrazené zpracování těchto hlaviček, takže starší verze je nesprávně interpretují jako obecná doporučení pro omezení rychlosti.

Oprava:

  • Ujistěte se, že používáte v3.8.0 nebo novější
  • Ověřte, že je přepínač useUpstream429BreakerHints povolen v části Nastavení → Odolnost

Chybějící OMNIROUTE_WS_BRIDGE_SECRET v produkčním prostředí

Příznaky:

  • Chyba 401 u každého požadavku na WebSocket bridge Codex/Responses při provozu na vzdáleném produkčním hostiteli
  • Navazování spojení s WebSocket bridge se ukončí ihned po připojení

Příčina: V produkčním prostředí chybí proměnná prostředí OMNIROUTE_WS_BRIDGE_SECRET.

Oprava:

  1. Vygenerujte náhodný tajný klíč: openssl rand -hex 32
  2. Nastavte OMNIROUTE_WS_BRIDGE_SECRET=<random-secret> v prostředí produkčního serveru (a u všech klientů, kteří komunikují s bridge)
  3. Restartujte OmniRoute

Responses API: režim na pozadí degradován na synchronní

Příznaky:

  • Zaznamenané upozornění: background mode degraded to synchronous
  • Požadavek s background: true vrátí běžnou synchronní odpověď namísto identifikátoru úlohy na pozadí

Příčina: v3.8.0 záměrně převádí background: true v Responses API na synchronní provádění a současně vydává upozornění. Plné asynchronní provádění na pozadí bude dodáno v budoucnu.

Oprava:

  • Upravte klienta tak, aby volání prováděl bez background, nebo
  • Počkejte na pozdější vydání s plným asynchronním režimem na pozadí (sledujte protokol změn)

Pomalé spuštění / vypršení časového limitu připravenosti

Pokud CLI vypíše ⚠ Server did not respond within 60s, ale server ve skutečnosti funguje, limit sondy připravenosti je pro vaše prostředí příliš krátký.

K tomu běžně dochází ve Windows (antivirový software, sledování změn souborového systému) nebo v kontejnerech s vysokou zátěží při spouštění.

Řešení — zvyšte limit:

# Pomocí proměnné prostředí (platí i při dalších spuštěních):
export OMNIROUTE_READY_TIMEOUT_MS=180000   # 3 minuty
omniroute serve

# Pomocí příznaku CLI (jednorázově):
omniroute serve --ready-timeout 180000

Výchozí hodnota je 60 000 ms (60 s). Varování má pouze informativní charakter; server se nadále spouští na pozadí a bude dostupný po dokončení spouštění.

Úplné podrobnosti o OMNIROUTE_READY_TIMEOUT_MS najdete v souboru docs/reference/ENVIRONMENT.md.

Stále jste se neposunuli dál?