Procedura operacyjna Gateway

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

# 5-minutowe uruchomienie lokalne

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

openclaw gateway status
openclaw status
openclaw logs --follow

openclaw channels status --probe

# Model środowiska uruchomieniowego

• Jeden stale działający proces do routingu, płaszczyzny sterowania i połączeń kanałów.
• Jeden multipleksowany port dla:
  • sterowania/RPC przez WebSocket
  • interfejsów API HTTP, zgodnych z OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Control UI i hooków
• Domyślny tryb bindowania: loopback.
• Uwierzytelnianie jest domyślnie wymagane. Konfiguracje ze współdzielonym sekretem używają gateway.auth.token / gateway.auth.password (albo OPENCLAW_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/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 zorientowany najpierw na agentów: zwraca openclaw, openclaw/default i openclaw/<agentId>.
• openclaw/default to stabilny alias, który zawsze mapuje na skonfigurowanego agenta domyślnego.
• Użyj x-openclaw-model, gdy chcesz nadpisać backendowego dostawcę/model; w przeciwnym razie kontrolę zachowuje normalny model i konfiguracja embeddingów wybranego agenta.

Wszystkie te endpointy działają na głównym porcie Gateway i używają tej samej zaufanej granicy uwierzytelniania operatora co reszta interfejsu HTTP API Gateway.

# Priorytet portu i bindowania

Zainstalowane usługi gateway zapisują rozstrzygnięty --port w metadanych nadzorcy. Po zmianie gateway.port uruchom openclaw doctor --fix albo openclaw gateway install --force, aby launchd/systemd/schtasks uruchamiały proces na nowym porcie.

Uruchomienie Gateway używa tego samego efektywnego portu i bindowania, gdy zasila lokalne źródła Control UI dla bindów poza loopback. Na przykład --bind lan --port 3000 zasila http://localhost:3000 i http://127.0.0.1:3000 przed uruchomieniem walidacji środowiska uruchomieniowego. Jawnie dodaj wszystkie zdalne źródła przeglądarki, takie jak adresy URL proxy HTTPS, do gateway.controlUi.allowedOrigins.

# Tryby gorącego przeładowania

# 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ć wiele agentów i kanałów.

Potrzebujesz wielu gatewayów tylko wtedy, gdy celowo chcesz izolacji albo bota ratunkowego.

Przydatne kontrole:

openclaw gateway status --deep
openclaw gateway probe

Czego oczekiwać:

• 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 gateways, gdy odpowiada więcej niż jeden cel.
• Jeśli to zamierzone, odizoluj porty, konfigurację/stan i katalogi główne obszarów roboczych dla każdego gateway.

Lista kontrolna dla 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. Opcja awaryjna: tunel SSH.

ssh -N -L 18789:127.0.0.1:18789 user@host

Następnie podłącz klientów lokalnie do 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.

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway[-<profile>].service

# Szybka ścieżka profilu deweloperskiego

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

Domyślne wartości obejmują odizolowany stan/konfigurację i bazowy port gateway 19001.

# Szybka dokumentacja 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 / events to konserwatywna 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.tool, sessions.changed, presence, tick, health, heartbeat, zdarzenia cyklu życia parowania/zatwierdzania oraz shutdown.

Uruchomienia agentów są dwuetapowe:

1. Natychmiastowe potwierdzenie przyjęcia (status:"accepted")
2. Końcowa odpowiedź ukończenia (status:"ok"|"error"), z przesyłanymi strumieniowo zdarzeniami agent pomiędzy.

Zobacz pełną dokumentację protokołu: Protokół Gateway.

# Kontrole operacyjne

# Żywotność

• 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. Przy lukach sekwencji odśwież stan (health, system-presence) przed kontynuowaniem.

# Typowe sygnatury awarii

Pełne sekwencje diagnostyczne znajdziesz w Rozwiązywaniu problemów z Gateway.

# Gwarancje bezpieczeństwa

• Klienci protokołu Gateway zgłaszają błąd od razu, gdy Gateway jest niedostępny (bez niejawnego przełączania awaryjnego na kanał bezpośredni).
• Nieprawidłowe pierwsze ramki albo pierwsze ramki inne niż connect są odrzucane i zamykane.
• Kontrolowane zamykanie emituje zdarzenie shutdown przed zamknięciem gniazda.

Powiązane:

• Rozwiązywanie problemów
• Proces w tle
• Konfiguracja
• Stan
• Doctor
• Uwierzytelnianie

# Powiązane

• Konfiguracja
• Rozwiązywanie problemów z Gateway
• Dostęp zdalny
• Zarządzanie sekretami