Gateway-Betriebshandbuch

Verwenden Sie diese Seite für den erstmaligen Start und den laufenden Betrieb des Gateway-Dienstes.

Lokaler Start in 5 Minuten

openclaw gateway --port 18789# Debug-/Trace-Ausgaben werden auf stdio gespiegeltopenclaw gateway --port 18789 --verbose# Listener am ausgewählten Port zwangsweise beenden, dann startenopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

Laufzeitmodell

• Ein ständig aktiver Prozess für Routing, Steuerungsebene und Kanalverbindungen.
• Ein einzelner multiplexierter Port für:
  • WebSocket-Steuerung/RPC
  • HTTP-APIs (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • HTTP-Routen von Plugins, etwa das optionale /api/v1/admin/rpc
  • Control UI und Hooks
• Standard-Bindungsmodus: loopback. Innerhalb einer erkannten Container-Umgebung ist der effektive Standardwert auto (wird für Portweiterleitungen zu 0.0.0.0 aufgelöst), sofern Tailscale Serve/Funnel nicht aktiv ist; in diesem Fall wird stets loopback erzwungen.
• Authentifizierung ist standardmäßig erforderlich. Einrichtungen mit gemeinsamem Geheimnis verwenden gateway.auth.token / gateway.auth.password (oder OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), und Reverse-Proxy-Einrichtungen ohne Loopback können gateway.auth.mode: "trusted-proxy" verwenden.

OpenAI-kompatible Endpunkte

Die wirkungsvollste Kompatibilitätsschnittstelle von OpenClaw:

• 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 Speicher-Pipelines erwarten /v1/embeddings.
• Agentenorientierte Clients bevorzugen zunehmend /v1/responses.

/v1/models ist agentenorientiert: Der Endpunkt gibt für jeden konfigurierten Agenten openclaw, openclaw/default und openclaw/<agentId> zurück. openclaw/default ist der stabile Alias, der stets dem konfigurierten Standardagenten zugeordnet ist. Senden Sie x-openclaw-model, wenn Sie Provider und Modell des Backends überschreiben möchten; andernfalls bleibt die normale Modell- und Embedding-Konfiguration des ausgewählten Agenten maßgeblich.

Alle diese Endpunkte laufen auf dem Hauptport des Gateways und verwenden dieselbe vertrauenswürdige Authentifizierungsgrenze für Operatoren wie die übrige HTTP-API des Gateways.

Admin-HTTP-RPC (POST /api/v1/admin/rpc) ist eine separate, standardmäßig deaktivierte Plugin-Route für Host-Werkzeuge, die WebSocket-RPC nicht verwenden können. Siehe Admin-HTTP-RPC.

Rangfolge von Port und Bindung

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

Beim Start des Gateways werden derselbe effektive Port und dieselbe Bindung verwendet, um bei Bindungen ohne Loopback lokale Ursprünge für die Control UI vorzubelegen. Beispielsweise legt --bind lan --port 3000 vor der Laufzeitvalidierung http://localhost:3000 und http://127.0.0.1:3000 an. Fügen Sie alle Ursprünge entfernter Browser, etwa HTTPS-Proxy-URLs, explizit zu gateway.controlUi.allowedOrigins hinzu.

Hot-Reload-Modi

Operator-Befehlssatz

openclaw gateway statusopenclaw gateway status --deep   # fügt eine Dienstprüfung auf Systemebene hinzuopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep dient zur zusätzlichen Diensterkennung (LaunchDaemons/systemd-Systemeinheiten/schtasks), nicht für eine eingehendere RPC-Zustandsprüfung.

Mehrere Gateways (auf demselben Host)

Bei den meisten Installationen sollte ein Gateway pro Computer ausgeführt werden. Ein einzelnes Gateway kann mehrere Agenten und Kanäle hosten. Mehrere Gateways benötigen Sie nur, wenn Sie gezielt eine Isolation oder einen Rettungs-Bot wünschen.

Nützliche Prüfungen:

openclaw gateway status --deepopenclaw gateway probe

Was Sie erwarten können:

• gateway status --deep kann Other gateway-like services detected (best effort) melden und Bereinigungshinweise ausgeben, wenn noch veraltete launchd-/systemd-/schtasks-Installationen vorhanden sind.
• gateway probe kann vor multiple reachable gateway identities warnen, wenn verschiedene Gateways antworten oder OpenClaw nicht nachweisen kann, dass die erreichbaren Ziele dasselbe Gateway sind. Ein SSH-Tunnel, eine Proxy-URL oder eine konfigurierte Remote-URL zum selben Gateway stellt ein Gateway mit mehreren Transportwegen dar, selbst wenn sich die Transportports unterscheiden.
• Wenn dies beabsichtigt ist, isolieren Sie Ports, Konfiguration/Zustand und Workspace-Stammverzeichnisse für jedes Gateway.

Checkliste pro Instanz:

• Eindeutiger Wert für gateway.port
• Eindeutiger Wert für OPENCLAW_CONFIG_PATH
• Eindeutiger Wert für OPENCLAW_STATE_DIR
• Eindeutiger Wert für 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

Ausführliche Einrichtung: /gateway/multiple-gateways.

Remote-Zugriff

Bevorzugt: Tailscale/VPN. Ausweichlösung: SSH-Tunnel.

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

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

Siehe: Remote-Gateway, Authentifizierung, Tailscale.

Überwachung und Dienstlebenszyklus

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

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 $(whoami)

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=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

Fehler aufgrund ungültiger Konfigurationen führen zum Beenden mit Code 78. Linux-systemd-Einheiten verwenden RestartPreventExitStatus=78, um weitere Neustarts zu verhindern, bis die Konfiguration korrigiert wurde. launchd und die Windows-Aufgabenplanung verfügen über keine entsprechende Regel zum Stoppen abhängig vom Beendigungscode. Daher speichert das Gateway zusätzlich den Verlauf schneller unsauberer Starts und unterdrückt nach wiederholten Startfehlern den automatischen Start von Kanal-/Provider-Konten. In diesem sicheren Modus startet die Steuerungsebene weiterhin zur Überprüfung und Reparatur, Hot Reloads der Konfiguration und secrets.reload verweigern automatische Kanalneustarts, und eine explizite Operator-Anfrage über channels.start kann die Unterdrückung außer Kraft setzen.

Schnellstart für das Entwicklungsprofil

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

Zu den Standardwerten gehören isolierte Zustands-/Konfigurationsdaten und der Gateway-Basisport 19001.

Protokoll-Kurzreferenz (Operatoransicht)

• Der erste Client-Frame muss connect sein.
• Der Gateway gibt einen hello-ok-Frame mit einem snapshot (presence, health, stateVersion, uptimeMs) sowie policy-Limits (maxPayload, maxBufferedBytes, tickIntervalMs) zurück.
• hello-ok.features.methods / events sind eine konservative Liste zur Ermittlung verfügbarer Funktionen und kein generierter Dump aller aufrufbaren Hilfsrouten.
• Anfragen: req(method, params) → res(ok/payload|error).
• Zu den häufigen Ereignissen gehören connect.challenge, agent, chat, session.message, session.operation, session.tool, das optional aktivierbare session.approval, sessions.changed, presence, tick, health, heartbeat, Ereignisse im Lebenszyklus von Kopplung/Genehmigung und shutdown.

Agent-Ausführungen erfolgen in zwei Phasen:

1. Sofortige Annahmebestätigung (status:"accepted")
2. Abschließende Fertigstellungsantwort (status:"ok"|"error"), dazwischen werden agent-Ereignisse gestreamt.

Die vollständige Protokolldokumentation finden Sie unter Gateway-Protokoll.

Betriebsprüfungen

Erreichbarkeit

• Öffnen Sie eine WS-Verbindung und senden Sie connect.
• Erwarten Sie eine hello-ok-Antwort mit einem Snapshot.

Bereitschaft

openclaw gateway statusopenclaw channels status --probeopenclaw health

Wiederherstellung bei Lücken

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

Häufige Fehlermeldungen

Vollständige Diagnoseabläufe finden Sie unter Gateway-Fehlerbehebung.

Sicherheitsgarantien

• Gateway-Protokollclients brechen sofort mit einem Fehler ab, wenn der Gateway nicht verfügbar ist (kein impliziter Fallback auf einen direkten Kanal).
• Ungültige erste Frames sowie erste Frames, die keine Verbindungsherstellung anfordern, werden abgelehnt und geschlossen.
• Beim ordnungsgemäßen Herunterfahren wird vor dem Schließen des Sockets ein shutdown-Ereignis ausgegeben.

Verwandte Themen

• Konfiguration
• Gateway-Fehlerbehebung
• Hintergrundprozess
• Systemzustand
• Doctor
• Authentifizierung
• Remotezugriff
• Verwaltung von Geheimnissen