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 domyślnie zakładać tryb lokalny.
• Jeśli plik istnieje i brakuje gateway.mode, Gateway traktuje to jako podejrzane uszkodzenie konfiguracji i odmawia „zgadywania lokalności” za Ciebie.
• Bindowanie poza loopback bez uwierzytelniania jest blokowane (zabezpieczenie bezpieczeństwa).
• lan, tailnet i custom obecnie rozwiązują się przez ścieżki BYOH tylko dla IPv4.
• BYOH tylko dla IPv6 nie jest dziś natywnie obsługiwane na tej ścieżce. Użyj sidecara IPv4 lub proxy, jeśli sam host obsługuje tylko IPv6.
• SIGUSR1 wyzwala restart w procesie, gdy jest autoryzowany (commands.restart jest domyślnie włączone; ustaw commands.restart: false, aby zablokować ręczny restart, podczas gdy narzędzia Gateway/konfiguracja apply/update pozostają dozwolone).
• 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 raw, przywróć terminal przed wyjściem.

• Rekordy zachowują metadane operacyjne: nazwy zdarzeń, liczby, rozmiary w bajtach, odczyty pamięci, stan kolejki/sesji, identyfikatory zatwierdzeń, nazwy kanałów/Plugin oraz zredagowane podsumowania sesji. Nie zachowują tekstu czatu, treści webhooków, wyników narzędzi, surowych treści żądań lub odpowiedzi, tokenów, ciasteczek, 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 niepowodzeniach startu 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 outputu 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ą podczas uzgadniania. Nie potwierdza operacji odczytu/zapisu/administracyjnych.
• Próby diagnostyczne nie modyfikują uwierzytelniania urządzenia przy pierwszym użyciu: wykorzystują istniejący buforowany token urządzenia, jeśli istnieje, ale nie tworzą nowej tożsamości urządzenia CLI ani rekordu parowania urządzenia tylko do odczytu wyłącznie po to, aby sprawdzić status.
• gateway status w miarę możliwości rozwiązuje skonfigurowane SecretRefs uwierzytelniania na potrzeby uwierzytelnienia próby.
• Jeśli wymagany auth SecretRef jest nierozwiązany na tej ścieżce polecenia, gateway status --json zgłasza rpc.authWarning, gdy łączność/uwierzytelnianie próby się nie powiedzie; przekaż jawnie --token/--password albo najpierw rozwiąż źródło sekretu.
• Jeśli próba się powiedzie, ostrzeżenia o nierozwiązanych auth-ref są wyciszane, aby uniknąć fałszywych alarmów.
• Gdy próbkowanie jest włączone, wynik JSON zawiera gateway.version, gdy uruchomiony Gateway ją zgłasza; --require-rpc może awaryjnie użyć ładunku RPC status.runtimeVersion, jeśli następcza próba uzgadniania nie może dostarczyć metadanych wersji.
• Używaj --require-rpc w skryptach i automatyzacji, gdy nasłuchująca usługa nie wystarcza i wywołania RPC o zakresie odczytu też muszą być zdrowe.
• --deep dodaje najlepszy możliwy skan dodatkowych instalacji launchd/systemd/schtasks. Gdy wykryto wiele usług podobnych do gateway, wynik czytelny dla człowieka wypisuje wskazówki czyszczenia i ostrzega, że większość konfiguracji powinna uruchamiać jeden gateway na maszynę.
• --deep zgłasza też niedawne przekazanie restartu nadzorcy Gateway, gdy proces usługi zakończył się poprawnie na potrzeby restartu przez zewnętrznego nadzorcę.
• --deep uruchamia walidację konfiguracji w trybie świadomym pluginów (pluginValidation: "full") i ujawnia skonfigurowane ostrzeżenia manifestu pluginu (na przykład brakujące metadane konfiguracji kanału), aby testy smoke instalacji i aktualizacji je wykrywały. Domyślne gateway status zachowuje szybką ścieżkę tylko do odczytu, która pomija walidację pluginów.
• Wynik czytelny 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ć rozjazd profilu lub katalogu stanu.

• W instalacjach Linux systemd kontrole dryfu uwierzytelniania usługi odczytują z jednostki zarówno wartości Environment=, jak i EnvironmentFile= (w tym %h, ścieżki w cudzysłowach, wiele plików oraz opcjonalne pliki -).
• Kontrole dryfu rozwiązują SecretRefs gateway.auth.token przy użyciu scalonego środowiska uruchomieniowego (najpierw środowisko polecenia usługi, potem awaryjnie środowisko procesu).
• Jeśli uwierzytelnianie tokenem nie jest efektywnie aktywne (jawny gateway.auth.mode równy password/none/trusted-proxy albo nieustawiony tryb, w którym hasło może wygrać i żaden kandydat tokenu nie może wygrać), kontrole dryfu tokenu pomijają rozwiązywanie tokenu 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 próba mogła potwierdzić o uwierzytelnianiu. Jest to oddzielne od osiągalności.
• Read probe: ok oznacza, że wywołania RPC szczegółów o zakresie odczytu (health/status/system-presence/config.get) również się powiodły.
• Read probe: limited - missing scope: operator.read oznacza, że połączenie się powiodło, ale RPC o zakresie 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 następcza diagnostyka odczytu przekroczyła limit czasu lub się nie powiodła. To również jest zdegradowana osiągalność, a nie nieosiągalny Gateway.
• Podobnie jak gateway status, próba wykorzystuje istniejące buforowane uwierzytelnianie urządzenia, ale nie tworzy tożsamości urządzenia przy pierwszym użyciu ani stanu parowania.
• Kod wyjścia jest niezerowy tylko wtedy, gdy żaden sprawdzany cel nie jest osiągalny.

Poziom najwyższy:

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

Dla celu (targets[].connect):

• ok: osiągalność po połączeniu + klasyfikacja degradacji.
• rpcOk: pełny sukces szczegółów RPC.
• scopeLimited: szczegóły RPC nie powiodły 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 prób.
• multiple_gateways: osiągalne były odrębne tożsamości gateway albo OpenClaw nie mógł potwierdzić, że osiągalne cele są tym samym gateway. Tunel SSH, adres URL proxy lub skonfigurowany zdalny adres URL do tego samego gateway nie wywołuje tego ostrzeżenia.
• auth_secretref_unresolved: skonfigurowany auth SecretRef nie mógł zostać rozwiązany dla nieudanego celu.
• probe_scope_limited: połączenie WebSocket się powiodło, ale próba odczytu została ograniczona przez brakujące 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, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --json

• Użyj gateway restart, aby zrestartować zarządzaną usługę. Nie łącz gateway stop i gateway start jako zamiennika restartu.
• Na macOS gateway stop domyślnie używa launchctl bootout, co usuwa LaunchAgent z bieżącej sesji rozruchowej bez trwałego zapisania wyłączenia — automatyczne odzyskiwanie KeepAlive pozostaje aktywne dla przyszłych awarii, a gateway start ponownie włącza usługę w czysty sposób bez ręcznego launchctl enable. Przekaż --disable, aby trwale wstrzymać KeepAlive i RunAtLoad, tak aby gateway nie odradzał się do następnego jawnego gateway start; użyj tego, gdy ręczne zatrzymanie ma przetrwać ponowne uruchomienia komputera lub systemu.
• gateway restart --safe prosi działający Gateway o wstępne sprawdzenie aktywnej pracy i zaplanowanie jednego scalonego restartu po opróżnieniu aktywnej pracy. Domyślny bezpieczny restart czeka na aktywną pracę do skonfigurowanego gateway.reload.deferralTimeoutMs (domyślnie 5 minut); po wyczerpaniu tego budżetu restart jest wymuszany. Ustaw gateway.reload.deferralTimeoutMs na 0, aby bezpieczne oczekiwanie było bezterminowe i nigdy nie wymuszało restartu. --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 są milisekundami; akceptowane są jednostki takie jak s, m i h. --wait 0 czeka bezterminowo.
• gateway restart --safe --skip-deferral uruchamia świadomy OpenClaw bezpieczny restart, ale omija bramkę odroczenia, więc Gateway emituje restart natychmiast, nawet gdy zgłoszono blokady. Awaryjne wyjście operatora dla odroczeń zablokowanego uruchomienia zadania; wymaga --safe.
• gateway restart --force pomija opróżnianie aktywnej pracy i restartuje natychmiast. Użyj tego, gdy operator sprawdził już wymienione blokady zadań i chce natychmiast przywrócić gateway.
• Polecenia cyklu życia akceptują --json do skryptów.

• Gdy uwierzytelnianie tokenem wymaga tokenu, a gateway.auth.token jest zarządzane przez SecretRef, gateway install sprawdza, czy SecretRef można rozwiązać, ale nie utrwala rozwiązanego tokenu w metadanych środowiska usługi.
• Jeśli uwierzytelnianie tokenem wymaga tokenu, a skonfigurowany token SecretRef jest nierozwiązany, instalacja kończy się zamknięciem zamiast utrwalać zastępczy tekst jawny.
• Dla uwierzytelniania hasłem w gateway run preferuj OPENCLAW_GATEWAY_PASSWORD, --password-file albo wspierane przez SecretRef gateway.auth.password zamiast wbudowanego --password.
• W trybie uwierzytelniania wnioskowanego wyłącznie powłokowe OPENCLAW_GATEWAY_PASSWORD nie łagodzi wymagań instalacyjnych dotyczących tokenu; podczas instalowania zarządzanej usługi użyj trwałej konfiguracji (gateway.auth.password albo env w konfiguracji).
• Jeśli skonfigurowano zarówno gateway.auth.token, jak i gateway.auth.password, a gateway.auth.mode nie jest ustawione, instalacja jest blokowana do czasu jawnego ustawienia trybu.