Przejdź do głównej treści
Użyj tej strony do uruchomienia usługi Gateway w dniu 1 oraz operacji w dniu 2.

Głębokie rozwiązywanie problemów

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

Konfiguracja

Zadaniowy przewodnik konfiguracji + pełne odniesienie konfiguracji.

Zarządzanie sekretami

Kontrakt SecretRef, zachowanie migawki środowiska uruchomieniowego oraz operacje migracji/przeładowania.

Kontrakt planu sekretów

Dokładne reguły celu/ścieżki secrets apply oraz zachowanie profilu auth tylko z referencjami.

​
5-minutowe lokalne uruchomienie

1

Uruchom Gateway

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force
2

Zweryfikuj kondycję usługi

openclaw gateway status
openclaw status
openclaw logs --follow
Zdrowa baza: Runtime: running, Connectivity probe: ok oraz Capability: ... zgodne z oczekiwaniami. Użyj openclaw gateway status --require-rpc, gdy potrzebujesz dowodu RPC z zakresem odczytu, a nie tylko osiągalności.
3

Sprawdź gotowość kanałów

openclaw channels status --probe
Przy osiągalnym Gateway uruchamia to aktywne sondy kanałów dla każdego konta oraz opcjonalne audyty. Jeśli Gateway jest nieosiągalny, CLI przełącza się na podsumowania kanałów wyłącznie z konfiguracji zamiast wyniku aktywnej sondy.
Przeładowanie konfiguracji Gateway obserwuje ścieżkę aktywnego pliku konfiguracji (rozwiązaną z domyślnych ustawień profilu/stanu albo z OPENCLAW_CONFIG_PATH, gdy jest ustawione). Tryb domyślny to gateway.reload.mode="hybrid". Po pierwszym udanym wczytaniu działający proces obsługuje aktywną migawkę konfiguracji w pamięci; udane przeładowanie atomowo podmienia tę migawkę.

​
Model środowiska uruchomieniowego

  • Jeden stale działający proces do routingu, płaszczyzny sterowania i połączeń kanałów.
  • Pojedynczy multipleksowany port dla:
    • Sterowania/RPC przez WebSocket
    • API HTTP (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • Tras HTTP Plugin, takich jak opcjonalne /api/v1/admin/rpc
    • Control UI i hooków
  • Domyślny tryb wiązania: 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 reverse proxy poza local loopback mogą używać gateway.auth.mode: "trusted-proxy".

​
Punkty końcowe zgodne z OpenAI

Najważniejsza powierzchnia zgodności OpenClaw to teraz:
  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses
Dlaczego ten zestaw ma znaczenie:
  • Większość integracji Open WebUI, LobeChat i LibreChat najpierw sonduje /v1/models.
  • Wiele potoków RAG i pamięci oczekuje /v1/embeddings.
  • Klienci natywni dla agentów coraz częściej preferują /v1/responses.
Uwaga planistyczna:
  • /v1/models jest ukierunkowany na agentów: zwraca openclaw, openclaw/default i openclaw/<agentId>.
  • openclaw/default to stabilny alias, który zawsze mapuje się na skonfigurowanego agenta domyślnego.
  • Użyj x-openclaw-model, gdy chcesz nadpisać dostawcę/model backendu; w przeciwnym razie kontrolę zachowuje normalna konfiguracja modelu i embeddingów wybranego agenta.
Wszystkie te punkty działają na głównym porcie Gateway i używają tej samej granicy uwierzytelniania zaufanego operatora co pozostała część API HTTP Gateway. Administracyjne RPC HTTP (POST /api/v1/admin/rpc) to osobna, domyślnie wyłączona trasa Plugin dla narzędzi hosta, które nie mogą używać RPC przez WebSocket. Zobacz Administracyjne RPC HTTP.

​
Priorytet portu i wiązania

UstawienieKolejność rozwiązywania
Port Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Tryb wiązaniaCLI/override → gateway.bind → loopback
Zainstalowane usługi gateway zapisują rozwiązane --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. Uruchamianie Gateway używa tego samego efektywnego portu i wiązania, gdy zasila lokalne źródła Control UI dla wiązań poza local loopback. Na przykład --bind lan --port 3000 zasila http://localhost:3000 i http://127.0.0.1:3000, zanim uruchomi się walidacja środowiska uruchomieniowego. Dodaj jawnie wszelkie źródła zdalnych przeglądarek, takie jak adresy URL proxy HTTPS, do gateway.controlUi.allowedOrigins.

​
Tryby hot reload

gateway.reload.modeZachowanie
offBrak przeładowania konfiguracji
hotStosuje tylko zmiany bezpieczne dla hot reload
restartRestartuje przy zmianach wymagających przeładowania
hybrid (domyślnie)Stosuje hot-apply, gdy jest bezpiecznie; restartuje, gdy jest to wymagane

​
Zestaw poleceń operatora

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor
gateway status --deep służy do dodatkowego wykrywania usług (LaunchDaemons/jednostki systemowe systemd/schtasks), a nie do głębszej sondy kondycji RPC.

​
Wiele gatewayów (ten sam host)

Większość instalacji powinna uruchamiać jeden gateway na maszynę. Pojedynczy gateway może obsługiwać wielu agentów i wiele kanałów. Potrzebujesz wielu gatewayów tylko wtedy, gdy celowo chcesz izolacji lub bota ratunkowego. Przydatne kontrole: 
openclaw gateway status --deep
openclaw gateway probe
Czego się spodziewać:
  • gateway status --deep może zgłosić Other gateway-like services detected (best effort) i wypisać wskazówki czyszczenia, gdy nadal istnieją przestarzałe instalacje launchd/systemd/schtasks.
  • gateway probe może ostrzec o multiple reachable gateway identities, gdy odpowiadają różne gatewaye albo gdy OpenClaw nie może udowodnić, że osiągalne cele są tym samym Gateway. Tunel SSH, URL proxy lub skonfigurowany zdalny URL do tego samego Gateway to jeden gateway z wieloma transportami, nawet gdy porty transportu się różnią.
  • Jeśli jest to zamierzone, odizoluj porty, konfigurację/stan oraz katalogi główne przestrzeni roboczych dla każdego Gateway.
Lista kontrolna dla każdej instancji:
  • Unikalny gateway.port
  • Unikalny OPENCLAW_CONFIG_PATH
  • Unikalny OPENCLAW_STATE_DIR
  • Unikalny agents.defaults.workspace
Przykład: 
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
Szczegółowa konfiguracja: /gateway/multiple-gateways.

​
Dostęp zdalny

Preferowane: Tailscale/VPN. Rozwiązanie awaryjne: tunel SSH. 
ssh -N -L 18789:127.0.0.1:18789 user@host
Następnie podłączaj klientów lokalnie do ws://127.0.0.1:18789.
Tunele SSH nie omijają uwierzytelniania Gateway. W przypadku uwierzytelniania współdzielonym sekretem klienci nadal muszą wysyłać token/password, nawet przez tunel. W trybach przenoszących tożsamość żądanie nadal musi spełnić wymagania tej ścieżki uwierzytelniania.
Zobacz: Zdalny Gateway, Uwierzytelnianie, Tailscale.

​
Nadzór i cykl życia usługi

Używaj nadzorowanych uruchomień, aby uzyskać niezawodność podobną do produkcyjnej. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
Używaj openclaw gateway restart do ponownych uruchomień. Nie łącz openclaw gateway stop i openclaw gateway start jako zamiennika ponownego uruchomienia.W macOS gateway stop domyślnie używa launchctl bootout — usuwa to LaunchAgent z bieżącej sesji rozruchowej bez trwałego wyłączania, więc automatyczne odzyskiwanie KeepAlive nadal działa po nieoczekiwanych awariach, a gateway start ponownie włącza usługę w czysty sposób. Aby trwale zablokować automatyczne ponowne uruchamianie między restartami systemu, przekaż --disable: openclaw gateway stop --disable.Etykiety LaunchAgent to ai.openclaw.gateway (domyślna) lub ai.openclaw.<profile> (nazwany profil). openclaw doctor audytuje i naprawia rozjazdy konfiguracji usługi.

​
Szybka ścieżka profilu deweloperskiego

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
Wartości domyślne obejmują odizolowany stan/konfigurację oraz bazowy port Gateway 19001.

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

  • Pierwszą ramką klienta musi być connect.
  • Gateway zwraca migawkę hello-ok (presence, health, stateVersion, uptimeMs, limity/polityka).
  • hello-ok.features.methods / events to zachowawcza lista wykrywania, a nie wygenerowany zrzut każdej wywoływalnej trasy pomocniczej.
  • Żądania: req(method, params) → res(ok/payload|error).
  • Typowe zdarzenia obejmują connect.challenge, agent, chat, session.message, session.operation, session.tool, 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ź zakończenia (status:"ok"|"error"), z przesyłanymi strumieniowo zdarzeniami agent pomiędzy.
Zobacz pełną dokumentację protokołu: Protokół Gateway.

​
Kontrole operacyjne

​
Aktywność

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

​
Gotowość

openclaw gateway status
openclaw channels status --probe
openclaw health

​
Odzyskiwanie po lukach

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

​
Typowe sygnatury awarii

SygnaturaPrawdopodobny problem
refusing to bind gateway ... without authWiązanie inne niż loopback bez prawidłowej ścieżki uwierzytelniania Gateway
another gateway instance is already listening / EADDRINUSEKonflikt portu
Gateway start blocked: set gateway.mode=localKonfiguracja ustawiona na tryb zdalny albo w uszkodzonej konfiguracji brakuje znacznika trybu lokalnego
unauthorized podczas łączeniaNiezgodność uwierzytelniania między klientem a Gateway
Pełne ścieżki diagnostyczne znajdziesz w sekcji Rozwiązywanie problemów z Gateway.

​
Gwarancje bezpieczeństwa

  • Klienci protokołu Gateway szybko kończą działanie, gdy Gateway jest niedostępny (bez niejawnego powrotu do kanału bezpośredniego).
  • Nieprawidłowe pierwsze ramki lub pierwsze ramki bez połączenia są odrzucane i zamykane.
  • Płynne zamknięcie emituje zdarzenie shutdown przed zamknięciem gniazda.
Powiązane:

​
Powiązane