Dlaczego Hermes uparcie przełącza się na fallback — i jak raz na zawsze pozbyć się tego komunikatu

Oznacza to, że dopóki Twój główny provider nie odzyska pełnej przepustowości (albo nie zmienisz jego konfiguracji), będziesz otrzymywać ten alert za każdym razem, gdy wyślesz nową wiadomość.

Dlaczego problem się powtarza — główne przyczyny

1. Rzeczywisty rate limit na poziomie dostawcy

Najprostsza przyczyna: Twój klucz API lub konto u danego dostawcy faktycznie wyczerpało limit żądań. OpenClaw (gateway często współpracujący z Hermesem) wyraźnie klasyfikuje błędy HTTP 429 jako problemy z limitem na poziomie upstream, które trzeba diagnozować po stronie gatewaya, a nie w interfejsie użytkownika .

Dodatkowo, komunikaty 429 mogą dotyczyć tzw. długich kontekstów (ang. long context requests). Jeśli wysyłasz bardzo rozbudowane prompty, upstream może odrzucić zapytanie ze wskazaniem: „Extra usage is required for long context requests” .

2. Wspólna pula kluczy lub ten sam backend

Kluczowe znaczenie ma konfiguracja w pliku config.yaml (zwykle ~/.hermes/config.yaml). Jeśli zarówno primary, jak i fallback — w tym przypadku sg-claude-opus-4.7 via custom — korzystają z tego samego dostawcy, tej samej bramki lub współdzielonych kluczy API, przełączenie na model zapasowy nie ominie blokady. Obie ścieżki będą obciążać ten sam przeciążony zasób .

Według dokumentacji Hermesa, niestandardowe endpointy („custom endpoint”) są zapisywane w config.yaml, a łańcuch fallback definiuje się pod kluczem fallback_providers . Jeśli Twój primary i sg-claude-opus-4.7 via custom wskazują de facto na tę samą infrastrukturę, zmiana modelu niewiele pomoże.

3. Fałszywy alert o limicie — błąd gatewaya

Zdarzają się też sytuacje, gdy API działa poprawnie (testowane poza OpenClaw czy Hermesem), a sam gateway błędnie raportuje limit. Problem ten był zgłaszany m.in. na GitHubie jako fałszywy komunikat o wyczerpaniu limitu API wynikający z mechanizmu cooldown wewnątrz OpenClaw . W takich przypadkach kluczowe jest uruchomienie diagnostyki gatewaya.

Jak skutecznie naprawić problem — lista kontrolna

Krok 1: Zidentyfikuj swój główny model i łańcuch fallback

Otwórz plik config.yaml i sprawdź:

• Jaki model jest ustawiony jako primary.
• Jakie pary provider:model widnieją na liście fallback_providers .
• Gdzie wskazuje niestandardowy endpoint używany przez sg-claude-opus-4.7 via custom .

Jeśli primary i fallback korzystają z tego samego providera (np. oba przez OpenRouter albo oba przez ten sam klucz Anthropic), problem leży właśnie tutaj.

Krok 2: Zweryfikuj, czy dostawca faktycznie odrzuca żądania

Jeśli korzystasz z OpenClaw jako gatewaya, uruchom:

openclaw gateway probe

To polecenie pokaże, czy bramka jest osiągalna i jakie ma uprawnienia. Szukaj konkretnych kodów błędów: HTTP 429, RESOURCE_EXHAUSTED, wzmianek o retry-after .

Przetestuj też ten sam klucz API poza ekosystemem OpenClaw/Hermes — na przykład za pomocą Claude Code lub Qwen Code. Jeśli tam działa, przyczyna leży w gatewayu .

Krok 3: Sprawdź długość kontekstu

Jeśli błąd 429 pojawia się wyłącznie przy dłuższych rozmowach, przyczyną może być polityka dostawcy dotycząca długich kontekstów. OpenClaw w dokumentacji wyraźnie wskazuje, że „Extra usage is required for long context requests” jest częstą przyczyną limitu 429 . Rozważ podzielenie bardzo długich promptów lub użycie modelu z wyższym limitem tokenów.

Krok 4: Popraw konfigurację kluczy i zmiennych środowiskowych

Jeśli gateway działa jako usługa systemowa (systemd/launchd), klucze API najlepiej umieszczać w pliku ~/.openclaw/.env, aby demon mógł je odczytać. Po każdej zmianie kluczy lub konfiguracji zrestartuj gateway:

systemctl restart openclaw-gateway   # dla systemd
# lub
launchctl kickstart -k gui/$(id -u)/com.openclaw.gateway   # dla launchd

Potem ponownie sprawdź status .

Krok 5: Skonfiguruj prawdziwie niezależny fallback

Aby fallback faktycznie ratował sytuację, powinien wskazywać na innego dostawcę (np. OpenRouter z modelem Claude) lub na osobny klucz API z oddzielnym limitem. Możesz dodać zapasowy provider przez:

hermes fallback add

Lub bezpośrednio w config.yaml:

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4

Unikaj sytuacji, gdzie zarówno primary, jak i fallback są tym samym providerem z tym samym kluczem .

Krok 6: Rozważ zwiększenie timeoutów

Jeśli błędy wynikają z przeciążenia, a nie z twardego limitu, możesz zwiększyć timeout żądań w konfiguracji:

providers:
  <provider-id>:
    request_timeout_seconds: 120
    models:
      <model-name>:
        timeout_seconds: 180

Daje to więcej czasu na odpowiedź przy dużym obciążeniu .

Podsumowanie

Powtarzający się komunikat o przełączeniu na fallback nie jest wadą systemu — to symptom nierozwiązanego problemu z głównym dostawcą. Hermes działa tu dokładnie tak, jak powinien: przy każdym nowym zapytaniu próbuje wrócić do primary, a gdy limit nadal obowiązuje, elegancko przechodzi na model zapasowy .

Dopóki nie usuniesz źródłowej przyczyny (przeciążony klucz, błędna konfiguracja gatewaya, zbyt długie konteksty), alert będzie powracał. Zacznij od sprawdzenia config.yaml, porównania puli kluczy między primary a fallbackiem i diagnostyki gatewaya. W większości przypadków rozwiązaniem jest albo prawdziwie niezależny fallback, albo przerzucenie ruchu na mniej obciążony klucz API.

Jeśli potrzebujesz dokładnej pomocy przy analizie konkretnego pliku konfiguracyjnego — pokaż, który model jest primary, gdzie wskazuje custom endpoint i jakie masz wpisy w fallback_providers. Pomożemy zdiagnozować to raz-dwa.