Skip to content

Latest commit

 

History

History
219 lines (139 loc) · 11.4 KB

TROUBLESHOOTING.md

File metadata and controls

219 lines (139 loc) · 11.4 KB

Rozwiązywanie problemów

🌐 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

Typowe problemy i rozwiązania dla OmniRoute.

Szybkie poprawki

Problem Rozwiązanie
Pierwsze logowanie nie działa Sprawdź INITIAL_PASSWORD w .env (domyślnie: 123456)
Panel kontrolny otwiera się na złym porcie Ustaw PORT=20128 i NEXT_PUBLIC_BASE_URL=http://localhost:20128
Brak dzienników żądań pod logs/ Ustaw ENABLE_REQUEST_LOGS=true
EACCES: odmowa pozwolenia Ustaw DATA_DIR=/path/to/writable/dir, aby zastąpić ~/.omniroute
Strategia routingu nie jest zapisywana Aktualizacja do wersji 1.4.11+ (poprawka schematu Zoda zapewniająca trwałość ustawień)

Problemy z dostawcą

„Model językowy nie dostarczał komunikatów”

Przyczyna: Limit dostawcy został wyczerpany.

Poprawka:

  1. Sprawdź moduł śledzenia limitów na pulpicie nawigacyjnym
  2. Użyj kombinacji z poziomami rezerwowymi
  3. Przejdź na tańszy/bezpłatny poziom

Ograniczanie szybkości

Przyczyna: Wyczerpany limit subskrypcji.

Poprawka:

  • Dodaj rezerwę: cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking
  • Użyj GLM/MiniMax jako taniej kopii zapasowej

Token OAuth wygasł

OmniRoute automatycznie odświeża tokeny. Jeśli problemy nadal występują:

  1. Panel kontrolny → Dostawca → Połącz ponownie
  2. Usuń i ponownie dodaj połączenie dostawcy

Problemy z chmurą

Błędy synchronizacji z chmurą

  1. Sprawdź, czy BASE_URL wskazuje na działającą instancję (np. http://localhost:20128)
  2. Zweryfikuj punkty CLOUD_URL w punkcie końcowym w chmurze (np. https://omniroute.dev)
  3. Zachowaj wyrównanie wartości NEXT_PUBLIC_* z wartościami po stronie serwera

Chmura stream=false Zwraca 500

Objaw: Unexpected token 'd'... na punkcie końcowym w chmurze dla połączeń innych niż przesyłanie strumieniowe.

Przyczyna: Upstream zwraca ładunek SSE, podczas gdy klient oczekuje JSON.

Rozwiązanie: użyj stream=true do bezpośrednich połączeń w chmurze. Lokalne środowisko wykonawcze obejmuje rezerwę SSE → JSON.

Cloud wyświetla komunikat „Połączono”, ale „nieprawidłowy klucz API”

  1. Utwórz nowy klucz z lokalnego pulpitu nawigacyjnego (/api/keys)
  2. Uruchom synchronizację z chmurą: Włącz chmurę → Synchronizuj teraz
  3. Stare/niezsynchronizowane klucze nadal mogą zwracać 401 w chmurze

Problemy z Dockerem

Narzędzie CLI pokazuje, że nie jest zainstalowane

  1. Sprawdź pola wykonawcze: curl http://localhost:20128/api/cli-tools/runtime/codex | jq
  2. W trybie przenośnym: użyj docelowego obrazu runner-cli (w pakiecie CLI)
  3. W trybie montowania hosta: ustaw CLI_EXTRA_PATHS i zamontuj katalog bin hosta jako tylko do odczytu
  4. Jeśli installed=true i runnable=false: znaleziono plik binarny, ale kontrola stanu nie powiodła się

Szybka weryfikacja środowiska wykonawczego

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

Problemy z kosztami

Wysokie koszty

  1. Sprawdź statystyki użytkowania w Panelu → Użycie
  2. Zmień model podstawowy na GLM/MiniMax
  3. Korzystaj z bezpłatnej warstwy (Gemini CLI, iFlow) do zadań niekrytycznych
  4. Ustaw budżety kosztów według klucza API: Panel → Klucze API → Budżet

Debugowanie

Włącz dzienniki żądań

Ustaw ENABLE_REQUEST_LOGS=true w swoim pliku .env. Dzienniki pojawiają się w katalogu logs/.

Sprawdź stan dostawcy

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

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

Pamięć uruchomieniowa

  • Stan główny: ${DATA_DIR}/db.json (dostawcy, kombinacje, aliasy, klucze, ustawienia)
  • Użycie: ${DATA_DIR}/usage.json, ${DATA_DIR}/log.txt, ${DATA_DIR}/call_logs/
  • Dzienniki żądań: <repo>/logs/... (kiedy ENABLE_REQUEST_LOGS=true)

Problemy z wyłącznikami automatycznymi

Dostawca utknął w stanie OTWARTYM

Gdy wyłącznik automatyczny dostawcy jest OTWARTY, żądania są blokowane do czasu upłynięcia czasu odnowienia.

Poprawka:

  1. Przejdź do Panel sterowania → Ustawienia → Odporność
  2. Sprawdź kartę wyłącznika dla odpowiedniego dostawcy
  3. Kliknij Resetuj wszystko, aby wyczyścić wszystkie wyłączniki, lub poczekaj, aż upłynie czas odnowienia
  4. Przed zresetowaniem sprawdź, czy dostawca jest rzeczywiście dostępny

Dostawca ciągle uruchamia wyłącznik automatyczny

Jeśli dostawca wielokrotnie wchodzi w stan OPEN:

  1. Sprawdź Panel kontrolny → Kondycja → Kondycja dostawcy pod kątem wzorca awarii
  2. Przejdź do Ustawienia → Odporność → Profile dostawców i zwiększ próg awarii
  3. Sprawdź, czy dostawca zmienił limity API lub wymaga ponownego uwierzytelnienia
  4. Sprawdź dane telemetryczne dotyczące opóźnień — duże opóźnienia mogą powodować awarie wynikające z przekroczenia limitu czasu

Problemy z transkrypcją dźwięku

Błąd „Nieobsługiwany model”.

  • Upewnij się, że używasz prawidłowego przedrostka: deepgram/nova-3 lub assemblyai/best
  • Sprawdź, czy dostawca jest podłączony w ** Panelu → Dostawcy**

Transkrypcja zwraca wartość pustą lub kończy się niepowodzeniem

  • Sprawdź obsługiwane formaty audio: mp3, wav, m4a, flac, ogg, webm
  • Sprawdź, czy rozmiar pliku mieści się w granicach dostawcy (zwykle < 25 MB)
  • Sprawdź ważność klucza API dostawcy na karcie dostawcy

Debugowanie tłumacza

Użyj Panel kontrolny → Tłumacz, aby debugować problemy z tłumaczeniem formatu:

Tryb Kiedy stosować
Plac zabaw Porównaj formaty wejścia/wyjścia obok siebie — wklej nieudane żądanie, aby zobaczyć, jak zostanie przetłumaczone
Tester czatu Wysyłaj wiadomości na żywo i sprawdzaj pełny ładunek żądania/odpowiedzi, w tym nagłówki
Stolik testowy Przeprowadź testy wsadowe dla kombinacji formatów, aby dowiedzieć się, które tłumaczenia są uszkodzone
Monitorowanie na żywo Obserwuj przepływ żądań w czasie rzeczywistym, aby wykryć sporadyczne problemy z tłumaczeniem

Typowe problemy z formatem

  • Tagi myślenia nie pojawiają się — Sprawdź, czy dostawca docelowy obsługuje myślenie i ustawienie budżetu na myślenie
  • Porzucanie wywołań narzędzi — Niektóre tłumaczenia formatów mogą usuwać nieobsługiwane pola; sprawdź w trybie placu zabaw
  • Brak podpowiedzi systemowej — Claude i Gemini inaczej obsługują podpowiedzi systemowe; sprawdź wynik tłumaczenia
  • SDK zwraca surowy ciąg znaków zamiast obiektu — Naprawiono w wersji 1.1.0: narzędzie do czyszczenia odpowiedzi usuwa teraz niestandardowe pola (x_groq, usage_breakdown itp.), które powodują błędy sprawdzania poprawności OpenAI SDK w Pydantic
  • GLM/ERNIE odrzuca rolę system — Naprawiono w wersji 1.1.0: normalizator ról automatycznie łączy komunikaty systemowe z komunikatami użytkownika w przypadku niekompatybilnych modeli
  • developer rola nie została rozpoznana — Naprawiono w wersji 1.1.0: automatycznie konwertowana na system dla dostawców innych niż OpenAI
  • json_schema nie działa z Gemini — Naprawiono w wersji 1.1.0: response_format jest teraz konwertowany na responseMimeType Gemini + responseSchema

Ustawienia odporności

Automatyczny limit szybkości nie uruchamia się

  • Automatyczne ograniczenie szybkości dotyczy tylko dostawców kluczy API (nie OAuth/subskrypcja)
  • Sprawdź, czy Ustawienia → Odporność → Profile dostawców ma włączone automatyczne ograniczenie stawek
  • Sprawdź, czy dostawca zwraca kody stanu 429 lub nagłówki Retry-After

Dostrajanie wykładniczego wycofywania

Profile dostawców obsługują następujące ustawienia:

  • Opóźnienie bazowe — Początkowy czas oczekiwania po pierwszej awarii (domyślnie: 1 s)
  • Maks. opóźnienie — Maksymalny limit czasu oczekiwania (domyślnie: 30 s)
  • Mnożnik — O ile zwiększyć opóźnienie przy kolejnej awarii (domyślnie: 2x)

Stado przeciw grzmotom

Gdy wiele jednoczesnych żądań trafia do dostawcy z ograniczoną szybkością, OmniRoute używa mutexu i automatycznego ograniczania szybkości, aby serializować żądania i zapobiegać kaskadowym błędom. Jest to automatyczne w przypadku dostawców kluczy API.

Nadal utknąłeś?

  • Problemy z GitHubem: github.com/diegosouzapw/OmniRoute/issues
  • Architektura: Zobacz link, aby uzyskać szczegółowe informacje wewnętrzne
  • Dokumentacja API: Zobacz link dla wszystkich punktów końcowych
  • Panel stanu: Sprawdź Panel kontrolny → Zdrowie, aby sprawdzić stan systemu w czasie rzeczywistym
  • Tłumacz: Użyj Panel kontrolny → Tłumacz, aby debugować problemy z formatem