Gateway-Runbook

Verwenden Sie diese Seite für den Start am Tag 1 und den Betrieb am Tag 2 des Gateway-Dienstes.

# 5-Minuten-Start lokal

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

# Laufzeitmodell

• Ein ständig laufender Prozess für Routing, Control Plane und Kanalverbindungen.
• Ein einzelner multiplexierter 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-Bindungsmodus: loopback.
• Auth ist standardmäßig erforderlich. Shared-Secret-Setups verwenden gateway.auth.token / gateway.auth.password (oder OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), und Non-loopback- Reverse-Proxy-Setups können gateway.auth.mode: "trusted-proxy" verwenden.

# OpenAI-kompatible Endpunkte

Die wirkungsvollste Kompatibilitätsoberfläche von OpenClaw 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 ein Backend-Provider-/Modell-Override möchten; andernfalls bleibt die normale Modell- und Embedding-Konfiguration des ausgewählten Agent maßgeblich.

Alle diese Endpunkte laufen auf dem Haupt-Gateway-Port und verwenden dieselbe Auth-Grenze für vertrauenswürdige Operatoren wie der Rest der Gateway-HTTP-API.

# Port- und Bindungspriorität

Installierte Gateway-Dienste speichern das aufgelöste --port in Supervisor-Metadaten. Führen Sie nach einer Änderung von gateway.port openclaw doctor --fix oder openclaw gateway install --force aus, damit launchd/systemd/schtasks den Prozess am neuen Port startet.

Der Gateway-Start verwendet denselben effektiven Port und dieselbe Bindung, wenn lokale Control-UI-Ursprünge für Non-loopback-Bindungen gesetzt werden. Zum Beispiel setzt --bind lan --port 3000 http://localhost:3000 und http://127.0.0.1:3000, bevor die Laufzeitvalidierung ausgeführt wird. Fügen Sie alle Remote-Browser-Ursprünge, etwa HTTPS-Proxy-URLs, explizit zu gateway.controlUi.allowedOrigins hinzu.

# Hot-Reload-Modi

# Operator-Befehlssatz

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 ist für zusätzliche Diensterkennung (LaunchDaemons/systemd-System- Units/schtasks) gedacht, nicht für eine tiefere RPC-Zustandsprüfung.

# Mehrere Gateways (gleicher Host)

Die meisten Installationen sollten ein Gateway pro Maschine ausführen. Ein einzelnes Gateway kann mehrere Agenten und Kanäle hosten.

Sie benötigen nur dann mehrere Gateways, wenn Sie bewusst Isolation oder einen Rettungs-Bot möchten.

Nützliche Prüfungen:

openclaw gateway status --deep
openclaw gateway probe

Was Sie erwarten können:

• 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 dies beabsichtigt ist, isolieren Sie Ports, Konfiguration/Status und Workspace-Roots pro Gateway.

Checkliste pro Instanz:

• Eindeutiges gateway.port
• Eindeutiger OPENCLAW_CONFIG_PATH
• Eindeutiges OPENCLAW_STATE_DIR
• Eindeutiges 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

Detaillierte Einrichtung: /gateway/multiple-gateways.

# Remote-Zugriff

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

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

Verbinden Sie Clients dann lokal mit ws://127.0.0.1:18789.

Siehe: Remote Gateway, Authentifizierung, Tailscale.

# Überwachung und Dienstlebenszyklus

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

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

# Schneller Pfad für das Dev-Profil

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

Defaults umfassen isolierte Status-/Konfigurationsdaten 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 Hilfsroute.
• Anfragen: req(method, params) → res(ok/payload|error).
• Häufige Ereignisse umfassen connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, Pairing-/Approval-Lebenszyklusereignisse und shutdown.

Agent-Läufe sind zweistufig:

1. Sofortige akzeptierte Bestätigung (status:"accepted")
2. Abschließende Abschlussantwort (status:"ok"|"error"), mit gestreamten agent-Ereignissen dazwischen.

Siehe vollständige Protokolldokumentation: Gateway-Protokoll.

# Betriebsprüfungen

# Liveness

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

# Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

# Gap-Recovery

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

# Häufige Fehlersignaturen

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

# Sicherheitsgarantien

• Gateway-Protokollclients schlagen schnell fehl, wenn Gateway nicht verfügbar ist (kein impliziter Fallback auf direkte Kanäle).
• Ungültige erste Frames oder erste Frames ohne Verbindungsaufbau werden abgelehnt und geschlossen.
• Ein ordnungsgemäßes Herunterfahren gibt das Ereignis shutdown aus, bevor der Socket geschlossen wird.

Verwandt:

• Fehlerbehebung
• Hintergrundprozess
• Konfiguration
• Status
• Doctor
• Authentifizierung

# Verwandt

• Konfiguration
• Gateway-Fehlerbehebung
• Remote-Zugriff
• Secrets-Verwaltung