Gateway-Runbook

Verwenden Sie diese Seite für die Inbetriebnahme am ersten Tag und den Betrieb ab Tag 2 des Gateway-Dienstes.

5-Minuten-Start lokal

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

Runtime-Modell

• Ein dauerhaft laufender Prozess für Routing, Control Plane und Channel-Verbindungen.
• Einzelner multiplexter Port für:
  • WebSocket-Control/RPC
  • HTTP-APIs, OpenAI-kompatibel (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Control-UI und Hooks
• Standard-Bind-Modus: loopback.
• Auth ist standardmäßig erforderlich. Shared-Secret-Setups verwenden gateway.auth.token / gateway.auth.password (oder OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), und Reverse-Proxy-Setups außerhalb von loopback können gateway.auth.mode: "trusted-proxy" verwenden.

OpenAI-kompatible Endpunkte

OpenClaws wichtigste Kompatibilitätsoberfläche ist jetzt:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /v1/responses

Warum diese Auswahl wichtig ist:

• Die meisten Integrationen mit Open WebUI, LobeChat und LibreChat prüfen zuerst /v1/models.
• Viele RAG- und Memory-Pipelines erwarten /v1/embeddings.
• Agent-native Clients bevorzugen zunehmend /v1/responses.

Planungshinweis:

• /v1/models ist agent-first: Es gibt openclaw, openclaw/default und openclaw/<agentId> zurück.
• openclaw/default ist der stabile Alias, der immer dem konfigurierten Standard-Agent zugeordnet ist.
• Verwenden Sie x-openclaw-model, wenn Sie einen Backend-Provider-/Modell-Override wünschen; andernfalls bleibt das normale Modell- und Embedding-Setup des ausgewählten Agent maßgeblich.

Alle diese Endpunkte laufen auf dem Hauptport des Gateway und verwenden dieselbe vertrauenswürdige Operator-Auth-Grenze wie die übrige Gateway-HTTP-API.

Port- und Bind-Priorität

Installierte Gateway-Dienste speichern den aufgelösten --port in Supervisor-Metadaten. Nachdem Sie gateway.port geändert haben, führen Sie openclaw doctor --fix oder openclaw gateway install --force aus, damit launchd/systemd/schtasks den Prozess auf dem neuen Port startet.

Der Gateway-Start verwendet denselben effektiven Port und Bind, wenn er lokale Control-UI-Origins für Nicht-loopback-Binds initialisiert. Beispielsweise initialisiert --bind lan --port 3000 http://localhost:3000 und http://127.0.0.1:3000, bevor die Runtime-Validierung ausgeführt wird. Fügen Sie Remote-Browser-Origins, etwa HTTPS-Proxy-URLs, explizit zu gateway.controlUi.allowedOrigins hinzu.

Hot-Reload-Modi

Operator-Befehlssatz

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep dient zusätzlicher Diensterkennung (LaunchDaemons/systemd-System- Units/schtasks), nicht einer tieferen RPC-Health-Prüfung.

Mehrere Gateways (derselbe Host)

Die meisten Installationen sollten ein Gateway pro Maschine ausführen. Ein einzelnes Gateway kann mehrere Agents und Channels hosten.

Sie benötigen mehrere Gateways nur, wenn Sie bewusst Isolation oder einen Rescue-Bot wünschen.

Nützliche Prüfungen:

openclaw gateway status --deepopenclaw gateway probe

Zu erwarten:

• gateway status --deep kann Other gateway-like services detected (best effort) melden und Bereinigungshinweise ausgeben, wenn veraltete launchd/systemd/schtasks-Installationen noch vorhanden sind.
• gateway probe kann vor multiple reachable gateways warnen, wenn mehr als ein Ziel antwortet.
• Wenn das beabsichtigt ist, isolieren Sie Ports, Konfiguration/Status und Workspace-Roots pro Gateway.

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 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

Detaillierte Einrichtung: /gateway/multiple-gateways.

Remotezugriff

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

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

Verbinden Sie Clients anschließend lokal mit ws://127.0.0.1:18789.

Siehe: Remote Gateway, Authentifizierung, Tailscale.

Supervision und Dienstlebenszyklus

Verwenden Sie überwachte Ausführungen für produktionsähnliche Zuverlässigkeit.

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143KillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

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

Schneller Pfad für das Dev-Profil

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

Defaults umfassen isolierten Status/isolierte Konfiguration und den Basis-Gateway-Port 19001.

Protokoll-Kurzreferenz (Operator-Sicht)

• Der erste Client-Frame muss connect sein.
• Gateway gibt einen hello-ok-Snapshot zurück (presence, health, stateVersion, uptimeMs, Limits/Policy).
• hello-ok.features.methods / events sind eine konservative Discovery-Liste, kein generierter Dump jeder aufrufbaren Helper-Route.
• Anfragen: req(method, params) → res(ok/payload|error).
• Häufige Events umfassen connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, Lebenszyklus-Events für Pairing/Approval und shutdown.

Agent-Ausführungen sind zweistufig:

1. Sofortige Accepted-Bestätigung (status:"accepted")
2. Finale Completion-Antwort (status:"ok"|"error"), mit gestreamten agent-Events dazwischen.

Siehe vollständige Protokolldokumentation: Gateway-Protokoll.

Betriebsprüfungen

Liveness

• WS öffnen und connect senden.
• hello-ok-Antwort mit Snapshot erwarten.

Readiness

openclaw gateway statusopenclaw channels status --probeopenclaw health

Gap Recovery

Events werden nicht erneut abgespielt. Aktualisieren Sie bei Sequenzlücken den Status (health, system-presence), bevor Sie fortfahren.

Häufige Fehlersignaturen

Für vollständige Diagnoseleitern verwenden Sie Gateway-Fehlerbehebung.

Sicherheitsgarantien

• Gateway-Protokoll-Clients schlagen schnell fehl, wenn Gateway nicht verfügbar ist (kein impliziter Fallback auf einen direkten Kanal).
• Ungültige/nicht verbindende erste Frames werden abgewiesen und geschlossen.
• Ordnungsgemäßes Herunterfahren gibt vor dem Schließen des Sockets ein shutdown-Ereignis aus.

Verwandt:

• Fehlerbehebung
• Hintergrundprozess
• Konfiguration
• Integrität
• Doctor
• Authentifizierung

Verwandt

• Konfiguration
• Gateway-Fehlerbehebung
• Remote-Zugriff
• Geheimnisverwaltung