Skip to main content

​
Runbook usługi Gateway

Użyj tej strony do uruchomienia w dniu 1 oraz operacji w dniu 2 usługi Gateway.

Deep troubleshooting

Diagnostyka zaczynająca się od objawów z dokładnymi sekwencjami poleceń i sygnaturami logów.

Configuration

Przewodnik konfiguracji zorientowany na zadania + pełna referencja konfiguracji.

​
5-minutowe uruchomienie lokalne

1

Start the Gateway

2

Verify service health

Zdrowa baza: Runtime: running i RPC probe: ok.
3

Validate channel readiness

Przeładowanie konfiguracji Gateway obserwuje aktywną ścieżkę pliku konfiguracyjnego (rozwiązaną na podstawie domyślnych ustawień profilu/stanu lub OPENCLAW_CONFIG_PATH, gdy ustawione). Tryb domyślny: gateway.reload.mode="hybrid" (bezpieczne zmiany stosowane „na gorąco”, restart przy krytycznych).

​
Model runtime

  • Jeden zawsze działający proces do routingu, control plane i połączeń kanałów.
  • Multipleks jednego portu.
    • WebSocket control/RPC
    • OpenResponses (HTTP): /v1/responses.
    • Control UI i hooki
  • Domyślny tryb bindowania: loopback.
  • Uwierzytelnianie Gateway jest domyślnie wymagane: ustaw gateway.auth.token (lub OPENCLAW_GATEWAY_TOKEN) albo gateway.auth.password.

​
Port i priorytet bindowania

​
Tryby hot reload

​
Zestaw poleceń operatora

​
Zdalny dostęp

Preferowane Tailscale/VPN; w przeciwnym razie tunel SSH: Zapasowo: tunel SSH.
Następnie klienci łączą się z ws://127.0.0.1:18789 przez tunel.
Jeśli skonfigurowano token, klienci muszą dołączyć go w connect.params.auth.token, nawet przez tunel.
Zobacz: Remote Gateway, Authentication, Tailscale.

​
Nadzór i cykl życia usługi

Używaj uruchomień nadzorowanych dla niezawodności na poziomie produkcyjnym.
Etykiety LaunchAgent to ai.openclaw.gateway (domyślnie) lub ai.openclaw.<profile>, gdy uruchamiasz nazwany profil. openclaw doctor sprawdza i naprawia rozbieżności w konfiguracji usługi.

​
Wiele gatewayów (ten sam host)

W większości konfiguracji należy uruchomić jedną bramę Gateway. Używaj wielu Gatewayów tylko dla redundancji lub ścisłej izolacji (np. bot ratunkowy). Lista kontrolna per instancję:
  • unikatowy gateway.port
  • unikatowy OPENCLAW_CONFIG_PATH
  • unikatowy OPENCLAW_STATE_DIR
  • unikatowy agents.defaults.workspace
Przykład:
Zobacz Multiple gateways.

​
Szybka ścieżka dla profilu deweloperskiego

Ustawienia domyślne obejmują izolowany stan/konfigurację oraz bazowy port bramy 19001.

​
Protokół (widok operatora)

  • Pierwsza ramka klienta musi mieć typ connect.
  • Gateway zwraca migawkę hello-ok (presence, health, stateVersion, uptimeMs, limits/policy).
  • Żądania: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
  • Typowe zdarzenia: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.
Uruchomienia agenta są dwuetapowe:
  1. Natychmiastowe potwierdzenie przyjęcia (status:"accepted")
  2. Odpowiedzi agent są dwuetapowe: najpierw potwierdzenie res {runId,status:"accepted"}, a następnie końcowe res {runId,status:"ok"|"error",summary} po zakończeniu wykonania; strumieniowane wyjście dociera jako event:"agent".
Pełna dokumentacja: Gateway protocol oraz Bridge protocol (legacy).

​
Kontrole operacyjne

​
Żywotność

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

​
Gotowość

​
Odzyskiwanie po przerwie

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

​
Typowe sygnatury błędów

Aby uzyskać pełne ścieżki diagnostyczne, użyj Gateway Troubleshooting.

​
Gwarancje bezpieczeństwa

  • Klienci protokołu Gateway szybko przerywają działanie, gdy Gateway jest niedostępny (brak domyślnego przełączenia na kanał bezpośredni).
  • Ramki inne niż pierwsza ramka połączenia lub niepoprawny JSON są odrzucane, a gniazdo jest zamykane.
  • Łagodne zamknięcie: emituj zdarzenie shutdown przed zamknięciem; klienci muszą obsłużyć zamknięcie + ponowne połączenie.
Powiązane: