Gateway-Runbook

Diese Seite dient als Anleitung für den Tag-1-Start und Tag-2-Betrieb des Gateway-Service.

• Tiefgehende Fehlerbehebung — Symptombasierte Diagnosen mit exakten Befehlsketten und Log-Signaturen.
• Konfiguration — Aufgabenorientierter Setup-Guide + vollständige Konfigurationsreferenz.
• Secrets Management — SecretRef-Vertrag, Runtime-Snapshot-Verhalten und Migrieren/Neuladen.
• Secrets Plan Contract — Exakte secrets apply Target/Path-Regeln und Ref-Only-Auth-Profil-Verhalten.

5-Minuten-Lokalstart

Schritt 1: Gateway starten

openclaw gateway --port 18789
# Debug/Trace auf stdio spiegeln
openclaw gateway --port 18789 --verbose
# Listener am gewählten Port erzwingen beenden, dann starten
openclaw gateway --force

Schritt 2: Service-Gesundheit prüfen

openclaw gateway status
openclaw status
openclaw logs --follow

Gesunde Baseline: Runtime: running und RPC probe: ok.

Schritt 3: Kanal-Bereitschaft validieren

openclaw channels status --probe

Hinweis: Gateway-Konfigurations-Reload überwacht den aktiven Konfigurationspfad (aufgelöst aus Profil/State-Standards oder OPENCLAW_CONFIG_PATH wenn gesetzt). Standardmodus ist gateway.reload.mode="hybrid".

Laufzeitmodell

• Ein dauerhaft laufender Prozess für Routing, Control Plane und Kanal-Verbindungen.
• Ein einzelner gemultiplexter Port für:
  • WebSocket-Control/RPC
  • HTTP-APIs (OpenAI-kompatibel, Responses, Tools-Invoke)
  • Control UI und Hooks
• Standard-Bindungsmodus: loopback.
• Auth ist standardmäßig erforderlich (gateway.auth.token / gateway.auth.password, oder OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).

Port- und Bind-Priorität

Hot-Reload-Modi

Operator-Befehlssatz

openclaw gateway status
openclaw gateway status --deep
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

Fernzugriff

Bevorzugt: Tailscale/VPN. Fallback: SSH-Tunnel.

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

Verbinde dann Clients lokal mit ws://127.0.0.1:18789.

Warnung: Wenn Gateway-Auth konfiguriert ist, müssen Clients auch über SSH-Tunnel Auth (token/password) senden.

Siehe: Remote Gateway, Authentifizierung, Tailscale.

Supervision und Service-Lebenszyklus

Verwende überwachte Runs für produktionsähnliche Zuverlässigkeit.

macOS (launchd)

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

LaunchAgent-Labels sind ai.openclaw.gateway (Standard) oder ai.openclaw.<profil> (benanntes Profil). openclaw doctor auditiert und repariert Service-Konfigurations-Drift.

Linux (systemd user)

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

Für Persistenz nach dem Logout aktiviere Lingering:

sudo loginctl enable-linger <user>

Linux (System-Service)

Verwende eine System-Unit für Multi-User/Always-On-Hosts.

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

Mehrere Gateways auf einem Host

Die meisten Setups sollten ein Gateway betreiben. Verwende mehrere nur für strikte Isolation/Redundanz (z. B. ein Rescue-Profil).

Checkliste pro Instanz:

• Eindeutiger gateway.port
• Eindeutiger OPENCLAW_CONFIG_PATH
• Eindeutiger OPENCLAW_STATE_DIR
• Eindeutiger agents.defaults.workspace

Beispiel:

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

Siehe: Mehrere Gateways.

Dev-Profil Schnellpfad

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

Standards umfassen isolierten State/Config und Basis-Gateway-Port 19001.

Protokoll-Kurzreferenz (Operator-Sicht)

• Erster Client-Frame muss connect sein.
• Gateway gibt hello-ok-Snapshot zurück (presence, health, stateVersion, uptimeMs, Limits/Policy).
• Requests: req(method, params) → res(ok/payload|error).
• Gängige Events: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.

Agent-Runs sind zweistufig:

1. Sofortiger Accepted-Ack (status:"accepted")
2. Finale Completion-Response (status:"ok"|"error"), mit gestreamten agent-Events dazwischen.

Vollständige Protokoll-Dokumentation: Gateway-Protokoll.

Betriebsprüfungen

Liveness

• Öffne WS und sende connect.
• Erwarte hello-ok-Antwort mit Snapshot.

Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

Gap Recovery

Events werden nicht erneut abgespielt. Bei Sequenzlücken aktualisiere den State (health, system-presence) vor dem Fortfahren.

Häufige Fehlersignaturen

Für vollständige Diagnose-Leitern verwende Gateway-Fehlerbehebung.

Sicherheitsgarantien

• Gateway-Protokoll-Clients brechen schnell ab, wenn das Gateway nicht verfügbar ist (kein impliziter Direct-Channel-Fallback).
• Ungültige/Nicht-Connect-Erst-Frames werden abgelehnt und geschlossen.
• Graceful Shutdown sendet ein shutdown-Event vor dem Socket-Close.

Verwandte Seiten:

• Fehlerbehebung
• Hintergrundprozess
• Konfiguration
• Gesundheitschecks
• Doctor
• Authentifizierung