Skip to main content
Użyj tej strony do początkowego uruchomienia i późniejszej obsługi usługi Gateway.

Zaawansowane rozwiązywanie problemów

Diagnostyka według objawów z dokładnymi sekwencjami poleceń i sygnaturami dzienników.

Konfiguracja

Instrukcja konfiguracji zorientowana na zadania oraz pełna dokumentacja konfiguracji.

Zarządzanie sekretami

Kontrakt SecretRef, zachowanie migawki środowiska uruchomieniowego oraz operacje migracji i ponownego ładowania.

Kontrakt planu sekretów

Dokładne reguły celu/ścieżki secrets apply oraz zachowanie profilu uwierzytelniania wyłącznie z odwołaniami.

​
Lokalne uruchomienie w 5 minut

1

Uruchom Gateway

2

Sprawdź stan usługi

Prawidłowy stan bazowy: Runtime: running, Connectivity probe: ok oraz wiersz Capability zgodny z oczekiwaniami. Użyj openclaw gateway status --require-rpc jako potwierdzenia RPC z zakresem odczytu, a nie tylko osiągalności.
3

Sprawdź gotowość kanałów

Gdy Gateway jest osiągalny, polecenie wykonuje aktywne sondy kanałów dla poszczególnych kont oraz opcjonalne audyty. Jeśli Gateway jest nieosiągalny, CLI używa podsumowań kanałów opartych wyłącznie na konfiguracji.
Ponowne ładowanie konfiguracji Gateway monitoruje ścieżkę aktywnego pliku konfiguracji (ustaloną na podstawie wartości domyślnych profilu/stanu lub OPENCLAW_CONFIG_PATH, jeśli ją ustawiono). Trybem domyślnym jest gateway.reload.mode="hybrid". Po pierwszym pomyślnym załadowaniu działający proces korzysta z aktywnej migawki konfiguracji w pamięci; pomyślne ponowne załadowanie atomowo zastępuje tę migawkę.

​
Model środowiska uruchomieniowego

  • Jeden stale działający proces do routingu, płaszczyzny sterowania i połączeń kanałów.
  • Jeden multipleksowany port dla:
    • sterowania i RPC przez WebSocket
    • interfejsów API HTTP (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • tras HTTP Pluginów, takich jak opcjonalna /api/v1/admin/rpc
    • interfejsu sterowania i punktów zaczepienia
  • Domyślny tryb powiązania: loopback. W wykrytym środowisku kontenerowym efektywną wartością domyślną jest auto (rozwiązywaną do 0.0.0.0 na potrzeby przekierowania portów), chyba że aktywne jest udostępnianie lub przekazywanie Tailscale, które zawsze wymusza loopback.
  • Uwierzytelnianie jest domyślnie wymagane. Konfiguracje ze współdzielonym sekretem używają gateway.auth.token / gateway.auth.password (lub OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), a konfiguracje odwrotnego serwera proxy poza interfejsem pętli zwrotnej mogą używać gateway.auth.mode: "trusted-proxy".

​
Punkty końcowe zgodne z OpenAI

Najbardziej użyteczna warstwa zgodności OpenClaw:
  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses
Dlaczego ten zestaw jest ważny:
  • Większość integracji Open WebUI, LobeChat i LibreChat najpierw sonduje /v1/models.
  • Wiele potoków RAG i pamięci oczekuje /v1/embeddings.
  • Klienty natywne dla agentów coraz częściej preferują /v1/responses.
/v1/models działa przede wszystkim z myślą o agentach: zwraca openclaw, openclaw/default i openclaw/<agentId> dla każdego skonfigurowanego agenta. openclaw/default jest stabilnym aliasem, który zawsze wskazuje skonfigurowanego agenta domyślnego. Wyślij x-openclaw-model, aby zastąpić dostawcę/model zaplecza; w przeciwnym razie obowiązuje standardowa konfiguracja modelu i osadzania wybranego agenta. Wszystkie te punkty końcowe działają na głównym porcie Gateway i korzystają z tej samej granicy uwierzytelniania zaufanego operatora co pozostała część interfejsu HTTP API Gateway. Administracyjne RPC HTTP (POST /api/v1/admin/rpc) jest osobną, domyślnie wyłączoną trasą Pluginu dla narzędzi hosta, które nie mogą korzystać z RPC przez WebSocket. Zobacz Administracyjne RPC HTTP.

​
Kolejność pierwszeństwa portu i powiązania

Zainstalowane usługi Gateway zapisują ustaloną wartość --port w metadanych nadzorcy. Po zmianie gateway.port uruchom openclaw doctor --fix lub openclaw gateway install --force, aby launchd/systemd/schtasks uruchamiał proces na nowym porcie. Podczas uruchamiania Gateway używa tego samego efektywnego portu i powiązania do zainicjowania lokalnych źródeł interfejsu sterowania dla powiązań innych niż pętla zwrotna. Na przykład --bind lan --port 3000 inicjuje http://localhost:3000 i http://127.0.0.1:3000 przed rozpoczęciem walidacji środowiska uruchomieniowego. Jawnie dodaj wszystkie źródła zdalnych przeglądarek, takie jak adresy URL serwera proxy HTTPS, do gateway.controlUi.allowedOrigins.

​
Tryby ponownego ładowania na gorąco

​
Zestaw poleceń operatora

gateway status --deep służy do dodatkowego wykrywania usług (LaunchDaemons/jednostki systemowe systemd/schtasks), a nie do dokładniejszej sondy stanu RPC.

​
Wiele instancji Gateway (na tym samym hoście)

W większości instalacji na jednej maszynie powinien działać jeden Gateway. Jeden Gateway może obsługiwać wielu agentów i wiele kanałów. Wiele instancji Gateway jest potrzebnych tylko wtedy, gdy celowo wymagana jest izolacja lub bot ratunkowy. Przydatne kontrole:
Oczekiwane zachowanie:
  • gateway status --deep może zgłosić Other gateway-like services detected (best effort) i wyświetlić wskazówki dotyczące czyszczenia, gdy nadal istnieją nieaktualne instalacje launchd/systemd/schtasks.
  • gateway probe może ostrzec o multiple reachable gateway identities, gdy odpowiadają różne instancje Gateway lub gdy OpenClaw nie może potwierdzić, że osiągalne cele są tą samą instancją Gateway. Tunel SSH, adres URL serwera proxy lub skonfigurowany zdalny adres URL prowadzący do tej samej instancji Gateway oznacza jedną instancję z wieloma transportami, nawet jeśli porty transportów są różne.
  • Jeśli jest to zamierzone, dla każdej instancji Gateway odizoluj porty, konfigurację/stan oraz katalogi główne przestrzeni roboczych.
Lista kontrolna dla każdej instancji:
  • Unikatowy gateway.port
  • Unikatowy OPENCLAW_CONFIG_PATH
  • Unikatowy OPENCLAW_STATE_DIR
  • Unikatowy agents.defaults.workspace
Przykład:
Szczegółowa konfiguracja: /gateway/multiple-gateways.

​
Dostęp zdalny

Preferowane rozwiązanie: Tailscale/VPN. Rozwiązanie zapasowe: tunel SSH.
Następnie lokalnie połącz klienty z ws://127.0.0.1:18789.
Tunele SSH nie omijają uwierzytelniania Gateway. W przypadku uwierzytelniania współdzielonym sekretem klienty nadal muszą wysyłać token/password, nawet przez tunel. W trybach przenoszących tożsamość żądanie nadal musi spełniać wymagania tej ścieżki uwierzytelniania.
Zobacz: Zdalny Gateway, Uwierzytelnianie, Tailscale.

​
Nadzór i cykl życia usługi

W celu uzyskania niezawodności zbliżonej do środowiska produkcyjnego używaj uruchomień nadzorowanych.
Do ponownego uruchamiania używaj openclaw gateway restart. Nie łącz kolejno openclaw gateway stop i openclaw gateway start jako zamiennika ponownego uruchomienia.W systemie macOS gateway stop domyślnie używa launchctl bootout. Powoduje to usunięcie LaunchAgenta z bieżącej sesji rozruchowej bez trwałego wyłączania, dzięki czemu automatyczne odzyskiwanie KeepAlive nadal działa po nieoczekiwanych awariach, a gateway start ponownie włącza usługę bez problemów. Aby trwale wyłączyć automatyczne ponowne uruchamianie po kolejnych rozruchach, przekaż --disable: openclaw gateway stop --disable.Etykiety LaunchAgenta to ai.openclaw.gateway (domyślna) lub ai.openclaw.<profile> (profil nazwany). openclaw doctor przeprowadza audyt i naprawia rozbieżności konfiguracji usługi.
Błędy nieprawidłowej konfiguracji powodują zakończenie z kodem 78. Jednostki systemd w systemie Linux używają RestartPreventExitStatus=78, aby wstrzymać ponowne uruchamianie do czasu naprawienia konfiguracji. launchd i Harmonogram zadań systemu Windows nie mają równoważnej reguły zatrzymywania zależnej od kodu zakończenia, dlatego Gateway przechowuje również historię szybkich nieprawidłowych uruchomień i po powtarzających się niepowodzeniach uruchamiania wyłącza automatyczne uruchamianie kont kanałów/dostawców. W tym trybie bezpiecznym płaszczyzna sterowania nadal uruchamia się w celu inspekcji i naprawy, ponowne ładowanie konfiguracji na gorąco oraz secrets.reload odmawiają automatycznego ponownego uruchamiania kanałów, a jawne żądanie operatora channels.start może zastąpić to ograniczenie.

​
Szybka ścieżka profilu deweloperskiego

Wartości domyślne obejmują odizolowany stan/konfigurację i bazowy port Gateway 19001.

​
Skrócona dokumentacja protokołu (widok operatora)

  • Pierwszą ramką klienta musi być connect.
  • Gateway zwraca ramkę hello-ok z snapshot (presence, health, stateVersion, uptimeMs) oraz limitami policy (maxPayload, maxBufferedBytes, tickIntervalMs).
  • hello-ok.features.methods / events stanowią zachowawczą listę wykrywania, a nie wygenerowany zrzut każdej możliwej do wywołania trasy pomocniczej.
  • Żądania: req(method, params) → res(ok/payload|error).
  • Typowe zdarzenia obejmują connect.challenge, agent, chat, session.message, session.operation, session.tool, opcjonalne session.approval, sessions.changed, presence, tick, health, heartbeat, zdarzenia cyklu życia parowania/zatwierdzania oraz shutdown.
Uruchomienia agenta są dwuetapowe:
  1. Natychmiastowe potwierdzenie przyjęcia (status:"accepted")
  2. Końcowa odpowiedź o ukończeniu (status:"ok"|"error"), ze strumieniowanymi pomiędzy nimi zdarzeniami agent.
Pełna dokumentacja protokołu: Protokół Gateway.

​
Kontrole operacyjne

​
Aktywność

  • Otwórz połączenie WS i wyślij connect.
  • Oczekuj odpowiedzi hello-ok z migawką.

​
Gotowość

​
Odzyskiwanie po luce

Zdarzenia nie są odtwarzane. W przypadku luk w sekwencji przed kontynuowaniem odśwież stan (health, system-presence).

​
Typowe sygnatury błędów

Pełne procedury diagnostyczne zawiera Rozwiązywanie problemów z Gateway.

​
Gwarancje bezpieczeństwa

  • Klienci protokołu Gateway natychmiast zgłaszają błąd, gdy Gateway jest niedostępny (bez niejawnego przełączania awaryjnego na kanał bezpośredni).
  • Nieprawidłowe pierwsze ramki lub pierwsze ramki inne niż ramki połączenia są odrzucane, a połączenie jest zamykane.
  • Łagodne zamknięcie emituje zdarzenie shutdown przed zamknięciem gniazda.

​
Powiązane