Gateway

• Domyślnie Gateway odmawia uruchomienia, chyba że w ~/.OmeniaClaw/OmeniaClaw.json ustawiono gateway.mode=local. Użyj --allow-unconfigured do doraźnych/deweloperskich uruchomień.
• Oczekuje się, że OmeniaClaw onboard --mode local i OmeniaClaw setup zapiszą gateway.mode=local. Jeśli plik istnieje, ale brakuje gateway.mode, traktuj to jako uszkodzoną lub nadpisaną konfigurację i napraw ją, zamiast domyślnie zakładać tryb lokalny.
• Jeśli plik istnieje, a brakuje gateway.mode, Gateway traktuje to jako podejrzane uszkodzenie konfiguracji i odmawia „odgadnięcia local” za Ciebie.
• Bindowanie poza loopback bez uwierzytelnienia jest blokowane (bariera bezpieczeństwa).
• SIGUSR1 wyzwala restart wewnątrz procesu, gdy jest autoryzowany (commands.restart jest domyślnie włączone; ustaw commands.restart: false, aby zablokować ręczny restart, podczas gdy stosowanie/aktualizowanie narzędzia i konfiguracji gatewaya pozostają dozwolone).
• Handlery SIGINT/SIGTERM zatrzymują proces gatewaya, ale nie przywracają żadnego niestandardowego stanu terminala. Jeśli opakowujesz CLI za pomocą TUI lub wejścia w trybie raw, przywróć terminal przed zakończeniem.

• Rekordy przechowują metadane operacyjne: nazwy zdarzeń, liczniki, rozmiary w bajtach, odczyty pamięci, stan kolejki/sesji, nazwy kanałów/Plugin oraz zredagowane podsumowania sesji. Nie przechowują 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 wyłączania i błędach uruchomienia po restarcie OmeniaClaw zapisuje tę samą migawkę diagnostyczną do ~/.OmeniaClaw/logs/stability/OmeniaClaw-stability-*.json, gdy rejestrator ma zdarzenia. Sprawdź najnowszy pakiet za pomocą OmeniaClaw gateway stability --bundle latest; --limit, --type i --since-seq mają także zastosowanie do wyjścia pakietu.

• gateway status pozostaje dostępne do diagnostyki nawet wtedy, gdy lokalna konfiguracja CLI jest nieobecna lub nieprawidłowa.
• Domyślne gateway status potwierdza stan usługi, połączenie WebSocket i możliwość uwierzytelniania widoczną w momencie uzgadniania. Nie potwierdza operacji odczytu/zapisu/administracyjnych.
• Sondowania diagnostyczne nie modyfikują uwierzytelniania urządzenia przy pierwszym użyciu: używają ponownie istniejącego buforowanego tokenu 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 w celu sprawdzenia statusu.
• gateway status rozwiązuje skonfigurowane auth SecretRefs na potrzeby uwierzytelniania sondowania, gdy to możliwe.
• Jeśli wymagany auth SecretRef nie zostanie rozwiązany w tej ścieżce polecenia, gateway status --json zgłasza rpc.authWarning, gdy łączność/uwierzytelnianie sondowania zawiedzie; przekaż jawnie --token/--password albo najpierw rozwiąż źródło sekretu.
• Jeśli sondowanie się powiedzie, ostrzeżenia o nierozwiązanych auth-ref są ukrywane, 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 wykrytych zostanie wiele usług podobnych do Gateway, wyjście 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ę poprawnie na potrzeby restartu przez zewnętrznego nadzorcę.
• --deep uruchamia walidację konfiguracji w trybie świadomym Plugin (pluginValidation: "full") i pokazuje ostrzeżenia manifestu skonfigurowanego Plugin (na przykład brak metadanych konfiguracji kanału), aby kontrole dymne instalacji i aktualizacji je wykrywały. Domyślne gateway status zachowuje szybką ścieżkę tylko do odczytu, która pomija walidację Plugin.
• Wyjście dla człowieka zawiera rozwiązaną ścieżkę dziennika plikowego oraz migawkę ścieżek konfiguracji/ważności CLI względem usługi, aby pomóc diagnozować rozjazd profilu lub katalogu stanu.

• W instalacjach Linux systemd kontrole dryfu uwierzytelniania usługi odczytują wartości Environment= i EnvironmentFile= z jednostki (w tym %h, ścieżki w cudzysłowach, wiele plików i opcjonalne pliki -).
• Kontrole dryfu rozwiązują gateway.auth.token SecretRefs przy użyciu scalonego środowiska wykonawczego (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 brak ustawionego trybu, gdy 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 sondowanie mogło potwierdzić w zakresie uwierzytelniania. Jest to oddzielne od osiągalności.
• Read probe: ok oznacza, że wywołania RPC szczegółów 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 kolejne diagnostyki odczytu przekroczyły limit czasu lub się nie powiodły. To także zdegradowana osiągalność, a nie nieosiągalny Gateway.
• Podobnie jak gateway status, sondowanie używa ponownie istniejącego buforowanego uwierzytelniania urządzenia, ale nie tworzy pierwszej tożsamości urządzenia ani stanu parowania.
• Kod wyjścia 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 diagnostyki RPC szczegółów.
• capability: najlepsza możliwość zaobserwowana wśród osiągalnych celów (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope lub unknown).
• primaryTargetId: najlepszy cel traktowany jako aktywny zwycięzca w tej kolejności: jawny URL, tunel SSH, skonfigurowany zdalny cel, a potem local loopback.
• warnings[]: rekordy ostrzeżeń best-effort z code, message i opcjonalnym targetIds.
• network: podpowiedzi URL local loopback/tailnet wyprowadzone z bieżącej konfiguracji i sieci hosta.
• discovery.timeoutMs i discovery.count: rzeczywisty budżet/wynik wykrywania użyty dla tego przebiegu sondowania.

Dla każdego celu (targets[].connect):

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

Dla każdego 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 sondowań.
• multiple_gateways: osiągalny był więcej niż jeden cel; to nietypowe, chyba że celowo uruchamiasz izolowane profile, takie jak bot ratunkowy.
• auth_secretref_unresolved: skonfigurowany auth SecretRef nie mógł zostać rozwiązany dla celu, który się nie powiódł.
• probe_scope_limited: połączenie WebSocket się powiodło, ale sondowanie odczytu było ograniczone przez brak 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 ponownie uruchomić usługę zarządzaną. Nie łącz gateway stop i gateway start jako zamiennika ponownego uruchomienia.
• W systemie macOS gateway stop domyślnie używa launchctl bootout, co usuwa LaunchAgent z bieżącej sesji rozruchowej bez trwałego 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 wyciszyć KeepAlive i RunAtLoad, tak aby gateway nie uruchamiał się ponownie aż do następnego jawnego gateway start; użyj tego, gdy ręczne zatrzymanie ma przetrwać ponowne uruchomienia systemu.
• gateway restart --safe prosi działający Gateway o wstępne sprawdzenie aktywnej pracy OmeniaClaw i odroczenie ponownego uruchomienia 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 przed ponownym uruchomieniem dla tego ponownego uruchomienia. Same liczby oznaczają milisekundy; akceptowane są jednostki takie jak s, m i h. --wait 0 czeka bezterminowo.
• gateway restart --safe --skip-deferral wykonuje bezpieczne ponowne uruchomienie świadome OmeniaClaw, ale pomija bramkę odroczenia, więc Gateway emituje ponowne uruchomienie natychmiast nawet wtedy, gdy zgłoszono blokady. Awaryjne wyjście operatora dla odroczeń zablokowanych uruchomień zadań; wymaga --safe.
• gateway restart --force pomija opróżnianie aktywnej pracy i uruchamia ponownie natychmiast. Użyj tego, gdy operator już sprawdził wymienione blokady zadań i chce przywrócić gateway od razu.
• Polecenia cyklu życia akceptują --json do skryptów.

• Gdy token auth wymaga tokenu, a gateway.auth.token jest zarządzany przez SecretRef, gateway install sprawdza, czy SecretRef da się rozwiązać, ale nie utrwala rozwiązanego tokenu w metadanych środowiska usługi.
• Jeśli token auth wymaga tokenu, a skonfigurowany token SecretRef jest nierozwiązany, instalacja kończy się niepowodzeniem w trybie zamkniętym zamiast utrwalać zastępczy tekst jawny.
• Dla password auth w gateway run preferuj OmeniaClaw_GATEWAY_PASSWORD, --password-file lub gateway.auth.password oparte na SecretRef zamiast wbudowanego --password.
• W trybie auth wnioskowanym wyłącznie powłokowe OmeniaClaw_GATEWAY_PASSWORD nie rozluźnia wymagań instalacyjnych dotyczących tokenu; użyj trwałej konfiguracji (gateway.auth.password lub konfiguracji env) podczas instalowania usługi zarządzanej.
• Jeśli skonfigurowane są 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.