Gateway

• Domyślnie Gateway odmawia uruchomienia, chyba że w ~/.openclaw/openclaw.json ustawiono gateway.mode=local. Użyj --allow-unconfigured do jednorazowych uruchomień ad hoc/deweloperskich.
• Oczekuje się, że openclaw onboard --mode local i openclaw setup zapiszą gateway.mode=local. Jeśli plik istnieje, ale brakuje gateway.mode, potraktuj to jako uszkodzoną lub nadpisaną konfigurację i napraw ją zamiast zakładać tryb lokalny domyślnie.
• Jeśli plik istnieje i brakuje gateway.mode, Gateway traktuje to jako podejrzane uszkodzenie konfiguracji i odmawia „zgadywania trybu lokalnego” za Ciebie.
• Bindowanie poza loopback bez uwierzytelniania jest blokowane (zabezpieczenie).
• SIGUSR1 wyzwala restart w procesie, gdy jest autoryzowany (commands.restart jest domyślnie włączone; ustaw commands.restart: false, aby zablokować ręczny restart, przy jednoczesnym pozostawieniu dozwolonych operacji narzędzia Gateway/config apply/update).
• Handlery SIGINT/SIGTERM zatrzymują proces Gateway, ale nie przywracają żadnego niestandardowego stanu terminala. Jeśli opakowujesz CLI za pomocą TUI lub wejścia w trybie surowym, przywróć terminal przed wyjściem.

• Rekordy przechowują metadane operacyjne: nazwy zdarzeń, liczniki, rozmiary bajtów, odczyty pamięci, stan kolejki/sesji, nazwy kanałów/pluginów oraz zredagowane podsumowania sesji. Nie przechowują tekstu czatu, treści webhooków, wyników narzędzi, surowych treści żądań ani odpowiedzi, tokenów, cookies, wartości sekretów, nazw hostów ani surowych identyfikatorów sesji. Ustaw diagnostics.enabled: false, aby całkowicie wyłączyć rejestrator.
• Przy krytycznych wyjściach Gateway, timeoutach zamykania i błędach uruchamiania po restarcie OpenClaw zapisuje tę samą migawkę diagnostyczną do ~/.openclaw/logs/stability/openclaw-stability-*.json, gdy rejestrator ma zdarzenia. Sprawdź najnowszy pakiet za pomocą openclaw gateway stability --bundle latest; --limit, --type i --since-seq mają też zastosowanie do wyjścia pakietu.

• gateway status pozostaje dostępne do diagnostyki nawet wtedy, gdy lokalna konfiguracja CLI jest brakująca lub nieprawidłowa.
• Domyślne gateway status potwierdza stan usługi, połączenie WebSocket oraz możliwość uwierzytelniania widoczną w czasie uzgadniania połączenia. Nie potwierdza operacji odczytu/zapisu/administracyjnych.
• Sondy diagnostyczne nie modyfikują uwierzytelniania urządzenia przy pierwszym użyciu: ponownie używają istniejącego, buforowanego tokena urządzenia, gdy taki istnieje, ale nie tworzą nowej tożsamości urządzenia CLI ani rekordu parowania urządzenia tylko do odczytu tylko po to, aby sprawdzić status.
• gateway status rozwiązuje skonfigurowane SecretRefs uwierzytelniania dla uwierzytelniania sondy, gdy to możliwe.
• Jeśli wymagany SecretRef uwierzytelniania nie zostanie rozwiązany w tej ścieżce polecenia, gateway status --json zgłasza rpc.authWarning, gdy łączność/uwierzytelnianie sondy się nie powiedzie; przekaż jawnie --token/--password albo najpierw rozwiąż źródło sekretu.
• Jeśli sonda się powiedzie, ostrzeżenia o nierozwiązanych odwołaniach do uwierzytelniania są wyciszane, aby uniknąć fałszywych alarmów.
• Używaj --require-rpc w skryptach i automatyzacji, gdy nasłuchująca usługa nie wystarcza i potrzebujesz także sprawnych wywołań RPC z zakresem odczytu.
• --deep dodaje best-effort skanowanie dodatkowych instalacji launchd/systemd/schtasks. Gdy wykryto wiele usług podobnych do Gateway, wyjście czytelne dla człowieka drukuje wskazówki czyszczenia i ostrzega, że większość konfiguracji powinna uruchamiać jeden Gateway na maszynę.
• --deep zgłasza także niedawne przekazanie restartu nadzorcy Gateway, gdy proces usługi zakończył się czysto na potrzeby restartu przez zewnętrznego nadzorcę.
• Wyjście czytelne dla człowieka zawiera rozwiązaną ścieżkę pliku dziennika oraz migawkę ścieżek/poprawności konfiguracji CLI względem usługi, aby pomóc diagnozować rozbieżności profilu lub katalogu stanu.

• W instalacjach Linux systemd kontrole rozbieżności uwierzytelniania usługi odczytują zarówno wartości Environment=, jak i EnvironmentFile= z jednostki (w tym %h, ścieżki w cudzysłowie, wiele plików oraz opcjonalne pliki -).
• Kontrole rozbieżności rozwiązują SecretRefs gateway.auth.token przy użyciu scalonego środowiska uruchomieniowego (najpierw środowisko polecenia usługi, następnie awaryjnie środowisko procesu).
• Jeśli uwierzytelnianie tokenem nie jest faktycznie aktywne (jawny gateway.auth.mode równy password/none/trusted-proxy albo tryb nieustawiony, gdzie hasło może wygrać i żaden kandydat tokena nie może wygrać), kontrole rozbieżności tokena pomijają rozwiązywanie tokena konfiguracji.

• Reachable: yes oznacza, że co najmniej jeden cel zaakceptował połączenie WebSocket.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only zgłasza, co sonda mogła potwierdzić o uwierzytelnianiu. Jest to oddzielne od osiągalności.
• Read probe: ok oznacza, że szczegółowe wywołania RPC z zakresem odczytu (health/status/system-presence/config.get) także się powiodły.
• Read probe: limited - missing scope: operator.read oznacza, że połączenie się powiodło, ale RPC z zakresem odczytu jest ograniczone. Jest to zgłaszane jako zdegradowana osiągalność, a nie pełna awaria.
• Read probe: failed po Connect: ok oznacza, że Gateway zaakceptował połączenie WebSocket, ale dalsza diagnostyka odczytu przekroczyła limit czasu lub się nie powiodła. To także zdegradowana osiągalność, a nie nieosiągalny Gateway.
• Podobnie jak gateway status, sonda ponownie używa istniejącego buforowanego uwierzytelniania urządzenia, ale nie tworzy pierwszorazowej tożsamości urządzenia ani stanu parowania.
• Kod zakończenia jest niezerowy tylko wtedy, gdy żaden sondowany cel nie jest osiągalny.

Poziom główny:

• ok: co najmniej jeden cel jest osiągalny.
• degraded: co najmniej jeden cel zaakceptował połączenie, ale nie ukończył pełnej szczegółowej diagnostyki RPC.
• capability: najlepsza możliwość widziana wśród osiągalnych celów (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope lub unknown).
• primaryTargetId: najlepszy cel do traktowania jako aktywnego zwycięzcę w tej kolejności: jawny URL, tunel SSH, skonfigurowany zdalny cel, następnie local loopback.
• warnings[]: rekordy ostrzeżeń best-effort z code, message i opcjonalnym targetIds.
• network: wskazówki URL dla local loopback/tailnet pochodzące z bieżącej konfiguracji i sieci hosta.
• discovery.timeoutMs i discovery.count: rzeczywisty budżet wykrywania/liczba wyników użyte dla tego przebiegu sondy.

Dla celu (targets[].connect):

• ok: osiągalność po klasyfikacji połączenia + degradacji.
• rpcOk: pełny sukces szczegółowego RPC.
• scopeLimited: szczegółowe RPC nie powiodło się z powodu brakującego zakresu operatora.

Dla celu (targets[].auth):

• role: rola uwierzytelniania zgłoszona w hello-ok, gdy dostępna.
• scopes: przyznane zakresy zgłoszone w hello-ok, gdy dostępne.
• capability: ujawniona klasyfikacja możliwości uwierzytelniania dla tego celu.

• ssh_tunnel_failed: konfiguracja tunelu SSH nie powiodła się; polecenie wróciło do bezpośrednich sond.
• multiple_gateways: osiągalny był więcej niż jeden cel; jest to nietypowe, chyba że celowo uruchamiasz izolowane profile, takie jak bot ratunkowy.
• auth_secretref_unresolved: skonfigurowany SecretRef uwierzytelniania nie mógł zostać rozwiązany dla nieudanego celu.
• probe_scope_limited: połączenie WebSocket się powiodło, ale sonda odczytu została ograniczona przez brakujący operator.read.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
• gateway restart: --safe, --force, --wait <duration>, --json
• gateway uninstall|start|stop: --json

• Użyj gateway restart, aby zrestartować zarządzaną usługę. Nie łącz gateway stop i gateway start jako zamiennika restartu; w macOS gateway stop celowo wyłącza LaunchAgent przed zatrzymaniem go.
• gateway restart --safe prosi działający Gateway o wstępne sprawdzenie aktywnej pracy OpenClaw i odroczenie restartu do czasu opróżnienia dostarczania odpowiedzi, osadzonych uruchomień i uruchomień zadań. --safe nie można łączyć z --force ani --wait.
• gateway restart --wait 30s zastępuje skonfigurowany budżet opróżniania restartu dla tego restartu. Same liczby oznaczają milisekundy; akceptowane są jednostki takie jak s, m i h. --wait 0 czeka bezterminowo.
• gateway restart --force pomija opróżnianie aktywnej pracy i restartuje natychmiast. Użyj tego, gdy operator sprawdził już wymienione blokery zadań i chce natychmiast przywrócić gateway.
• Polecenia cyklu życia akceptują --json do skryptowania.

• Gdy uwierzytelnianie tokenem wymaga tokena, a gateway.auth.token jest zarządzany przez SecretRef, gateway install sprawdza, czy SecretRef można rozwiązać, ale nie zapisuje rozwiązanego tokena w metadanych środowiska usługi.
• Jeśli uwierzytelnianie tokenem wymaga tokena, a skonfigurowany SecretRef tokena pozostaje nierozwiązany, instalacja kończy się niepowodzeniem w trybie zamkniętym zamiast zapisywać awaryjny tekst jawny.
• W przypadku uwierzytelniania hasłem w gateway run preferuj OPENCLAW_GATEWAY_PASSWORD, --password-file albo gateway.auth.password oparty na SecretRef zamiast wbudowanego --password.
• W wywnioskowanym trybie uwierzytelniania dostępne tylko w powłoce OPENCLAW_GATEWAY_PASSWORD nie łagodzi wymagań dotyczących tokena instalacyjnego; podczas instalowania zarządzanej usługi użyj trwałej konfiguracji (gateway.auth.password lub konfiguracji env).
• Jeśli skonfigurowano zarówno gateway.auth.token, jak i gateway.auth.password, a gateway.auth.mode nie jest ustawiony, instalacja jest blokowana do czasu jawnego ustawienia trybu.