Użyj tej strony do uruchomienia usługi Gateway w dniu 1 oraz operacji w dniu 2.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Deep troubleshooting
Diagnostyka od objawu z dokładnymi sekwencjami poleceń i sygnaturami logów.
Configuration
Zadaniowy przewodnik konfiguracji + pełna dokumentacja konfiguracji.
Secrets management
Kontrakt SecretRef, zachowanie migawki środowiska uruchomieniowego oraz operacje migrate/reload.
Secrets plan contract
Dokładne reguły celu/ścieżki
secrets apply oraz zachowanie profilu uwierzytelniania tylko przez odwołania.5-minutowe uruchomienie lokalne
Verify service health
Runtime: running, Connectivity probe: ok oraz Capability: ... zgodne z oczekiwaniami. Użyj openclaw gateway status --require-rpc, gdy potrzebujesz dowodu RPC w zakresie odczytu, a nie tylko osiągalności.Przeładowanie konfiguracji Gateway obserwuje aktywną ścieżkę pliku konfiguracji (rozwiązaną z domyślnych ustawień profilu/stanu albo z
OPENCLAW_CONFIG_PATH, gdy jest ustawione).
Domyślny tryb 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 zgodnych z OpenAI (
/v1/models,/v1/embeddings,/v1/chat/completions,/v1/responses,/tools/invoke) - interfejsu sterowania 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(alboOPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD), a konfiguracje reverse proxy poza loopback mogą używaćgateway.auth.mode: "trusted-proxy".
Endpointy zgodne z OpenAI
Najważniejsza powierzchnia zgodności OpenClaw to teraz:GET /v1/modelsGET /v1/models/{id}POST /v1/embeddingsPOST /v1/chat/completionsPOST /v1/responses
- Większość integracji Open WebUI, LobeChat i LibreChat najpierw sprawdza
/v1/models. - Wiele potoków RAG i pamięci oczekuje
/v1/embeddings. - Klienci natywni dla agentów coraz częściej preferują
/v1/responses.
/v1/modelsjest ukierunkowane na agenty: zwracaopenclaw,openclaw/defaultiopenclaw/<agentId>.openclaw/defaultto 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 wybrany agent zachowuje kontrolę nad swoim zwykłym modelem i konfiguracją embeddingów.
Priorytet portu i wiązania
| Ustawienie | Kolejność rozwiązywania |
|---|---|
| Port Gateway | --port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789 |
| Tryb wiązania | CLI/override → gateway.bind → loopback |
--port w metadanych nadzorcy. Po zmianie gateway.port uruchom openclaw doctor --fix albo openclaw gateway install --force, aby launchd/systemd/schtasks uruchamiał proces na nowym porcie.
Uruchomienie Gateway używa tego samego efektywnego portu i wiązania, gdy inicjuje lokalne
źródła interfejsu sterowania dla wiązań poza loopback. Na przykład --bind lan --port 3000
inicjuje http://localhost:3000 i http://127.0.0.1:3000, zanim zostanie uruchomiona
walidacja środowiska uruchomieniowego. Dodaj jawnie wszelkie źródła zdalnych przeglądarek,
takie jak adresy URL proxy HTTPS, do gateway.controlUi.allowedOrigins.
Tryby gorącego przeładowania
gateway.reload.mode | Zachowanie |
|---|---|
off | Brak przeładowania konfiguracji |
hot | Zastosuj tylko zmiany bezpieczne na gorąco |
restart | Uruchom ponownie przy zmianach wymagających przeładowania |
hybrid (domyślnie) | Zastosuj na gorąco, gdy bezpieczne; uruchom ponownie, gdy wymagane |
Zestaw poleceń operatora
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 (ten sam host)
Większość instalacji powinna uruchamiać jeden Gateway na maszynę. Pojedynczy Gateway może obsługiwać wiele agentów i kanałów. Wiele Gateway jest potrzebnych tylko wtedy, gdy celowo chcesz izolacji albo bota ratunkowego. Przydatne kontrole:gateway status --deepmoże zgłosićOther gateway-like services detected (best effort)i wypisać wskazówki czyszczenia, gdy przestarzałe instalacje launchd/systemd/schtasks nadal istnieją.gateway probemoże ostrzec omultiple reachable gateways, gdy odpowiada więcej niż jeden cel.- Jeśli to celowe, izoluj porty, konfigurację/stan i katalogi główne obszarów roboczych dla każdego Gateway.
- Unikalny
gateway.port - Unikalny
OPENCLAW_CONFIG_PATH - Unikalny
OPENCLAW_STATE_DIR - Unikalny
agents.defaults.workspace
Dostęp zdalny
Preferowane: Tailscale/VPN. Awaryjnie: tunel SSH.ws://127.0.0.1:18789.
Zobacz: Zdalny Gateway, Uwierzytelnianie, Tailscale.
Nadzór i cykl życia usługi
Używaj nadzorowanych uruchomień dla niezawodności zbliżonej do produkcyjnej.- macOS (launchd)
- Linux (systemd user)
- Windows (native)
- Linux (system service)
openclaw gateway restart do ponownych uruchomień. Nie łącz openclaw gateway stop i openclaw gateway start jako zamiennika restartu.Na macOS gateway stop domyślnie używa launchctl bootout — usuwa to LaunchAgent z bieżącej sesji rozruchowej bez trwałego wyłączenia, więc automatyczne odzyskiwanie KeepAlive nadal działa po nieoczekiwanych awariach, a gateway start ponownie włącza usługę czysto. Aby trwale zatrzymać automatyczne ponowne uruchamianie między restartami systemu, przekaż --disable: openclaw gateway stop --disable.Etykiety LaunchAgent to ai.openclaw.gateway (domyślnie) albo ai.openclaw.<profile> (nazwany profil). openclaw doctor audytuje i naprawia rozjazdy konfiguracji usługi.Szybka ścieżka profilu deweloperskiego
19001.
Szybka referencja protokołu (widok operatora)
- Pierwsza ramka klienta musi być
connect. - Gateway zwraca migawkę
hello-ok(presence,health,stateVersion,uptimeMs, limity/polityka). hello-ok.features.methods/eventsto konserwatywna lista wykrywania, a nie wygenerowany zrzut każdej możliwej do wywołania trasy pomocniczej.- Żądania:
req(method, params)→res(ok/payload|error). - Typowe zdarzenia obejmują
connect.challenge,agent,chat,session.message,session.tool,sessions.changed,presence,tick,health,heartbeat, zdarzenia cyklu życia parowania/zatwierdzania orazshutdown.
- Natychmiastowe potwierdzenie przyjęcia (
status:"accepted") - Końcowa odpowiedź zakończenia (
status:"ok"|"error"), z przesyłanymi po drodze zdarzeniamiagent.
Kontrole operacyjne
Żywotność
- Otwórz WS i wyślij
connect. - Oczekuj odpowiedzi
hello-okz migawką.
Gotowość
Odzyskiwanie po lukach
Zdarzenia nie są odtwarzane. Przy lukach w sekwencji odśwież stan (health, system-presence) przed kontynuacją.
Typowe sygnatury awarii
| Sygnatura | Prawdopodobny problem |
|---|---|
refusing to bind gateway ... without auth | Powiązanie spoza pętli zwrotnej bez prawidłowej ścieżki uwierzytelniania Gateway |
another gateway instance is already listening / EADDRINUSE | Konflikt portu |
Gateway start blocked: set gateway.mode=local | Konfiguracja ustawiona na tryb zdalny albo w uszkodzonej konfiguracji brakuje znacznika trybu lokalnego |
unauthorized during connect | Niezgodność uwierzytelniania między klientem a Gateway |
Gwarancje bezpieczeństwa
- Klienci protokołu Gateway szybko kończą działanie, gdy Gateway jest niedostępny (bez niejawnego przełączania awaryjnego bezpośrednio na kanał).
- Nieprawidłowe pierwsze ramki lub pierwsze ramki bez połączenia są odrzucane i zamykane.
- Łagodne zamknięcie emituje zdarzenie
shutdownprzed zamknięciem gniazda.
Powiązane: