Gateway-Betriebshandbuch

Verwenden Sie diese Seite für die erstmalige Inbetriebnahme und den laufenden Betrieb des Gateway-Dienstes.

Lokale Inbetriebnahme in 5 Minuten

openclaw gateway --port 18789# Debug-/Trace-Ausgaben werden nach 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 dauerhaft aktiver Prozess für Routing, Steuerungsebene und Kanalverbindungen.
• Ein einzelner multiplexter Port für:
  • WebSocket-Steuerung/RPC
  • HTTP-APIs (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Plugin-HTTP-Routen, beispielsweise das optionale /api/v1/admin/rpc
  • Control UI und Hooks
• Standard-Bindungsmodus: loopback. Innerhalb einer erkannten Container-Umgebung ist der effektive Standard auto (wird für die Portweiterleitung in 0.0.0.0 aufgelöst), sofern Tailscale Serve/Funnel nicht aktiv ist; dies erzwingt stets loopback.
• Authentifizierung ist standardmäßig erforderlich. Konfigurationen mit gemeinsamem Secret verwenden gateway.auth.token / gateway.auth.password (oder OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD); Reverse-Proxy-Konfigurationen außerhalb von Loopback können gateway.auth.mode: "trusted-proxy" verwenden.

OpenAI-kompatible Endpunkte

OpenClaws Kompatibilitätsoberfläche mit der größten Hebelwirkung:

• 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.
• Für Agenten entwickelte Clients bevorzugen zunehmend /v1/responses.

/v1/models ist auf Agenten ausgerichtet: Es 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 wird. Senden Sie x-openclaw-model, wenn Sie den Provider oder das Modell im Backend überschreiben möchten; andernfalls bleibt die normale Modell- und Embedding-Konfiguration des ausgewählten Agenten maßgeblich.

Alle diese Endpunkte werden über den Hauptport des Gateways ausgeführt und verwenden dieselbe vertrauenswürdige Authentifizierungsgrenze für Bediener wie die übrige Gateway-HTTP-API.

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.

Priorität von Port und Bindung

Installierte Gateway-Dienste speichern das aufgelöste --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 verwendet das Gateway denselben effektiven Port und dieselbe Bindung, wenn es lokale Ursprünge der Control UI für Bindungen außerhalb von Loopback vorbelegt. Beispielsweise belegt --bind lan --port 3000 vor der Laufzeitvalidierung http://localhost:3000 und http://127.0.0.1:3000 vor. Fügen Sie alle Ursprünge entfernter Browser, etwa HTTPS-Proxy-URLs, ausdrücklich zu gateway.controlUi.allowedOrigins hinzu.

Hot-Reload-Modi

Befehlssatz für Bediener

openclaw gateway statusopenclaw gateway status --deep   # ergänzt eine systemweite Dienstsucheopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep dient der zusätzlichen Dienstsuche (LaunchDaemons/systemd-System-Units/schtasks), nicht einer tiefergehenden RPC-Zustandsprüfung.

Mehrere Gateways (auf demselben Host)

Die meisten Installationen sollten ein Gateway pro Rechner ausführen. Ein einzelnes Gateway kann mehrere Agenten und Kanäle bereitstellen. Mehrere Gateways sind nur erforderlich, wenn Sie bewusst eine Isolierung oder einen Rettungs-Bot wünschen.

Nützliche Prüfungen:

openclaw gateway status --deepopenclaw gateway probe

Zu erwartendes Verhalten:

• 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 unterschiedliche Gateways antworten oder OpenClaw nicht nachweisen kann, dass erreichbare Ziele dasselbe Gateway sind. Ein SSH-Tunnel, eine Proxy-URL oder eine konfigurierte Remote-URL zu demselben Gateway ist ein Gateway mit mehreren Transportwegen, 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:

• Eindeutiges gateway.port
• Eindeutiges 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 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 überwachte Ausführungen für eine 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 $(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 einer ungültigen Konfiguration beenden den Prozess mit Code 78. Linux-systemd-Units verwenden RestartPreventExitStatus=78, um weitere Starts zu verhindern, bis die Konfiguration korrigiert wurde. launchd und die Windows-Aufgabenplanung besitzen keine entsprechende Regel zum Anhalten bei einem bestimmten Exit-Code. 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 abgesicherten Modus startet die Steuerungsebene weiterhin zur Prüfung und Reparatur; Hot-Reloads der Konfiguration und secrets.reload verweigern automatische Kanalneustarts, und eine ausdrückliche channels.start-Anforderung durch den Bediener kann die Unterdrückung außer Kraft setzen.

Schnellstart mit Entwicklungsprofil

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

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

Protokoll-Kurzreferenz (Bedieneransicht)

• Der erste Client-Frame muss connect sein.
• Der Gateway gibt einen hello-ok-Frame mit einem snapshot (presence, health, stateVersion, uptimeMs) sowie policy-Grenzwerten (maxPayload, maxBufferedBytes, tickIntervalMs) zurück.
• hello-ok.features.methods / events sind eine konservative Ermittlungsliste und keine generierte Auflistung aller aufrufbaren Hilfsrouten.
• Anfragen: req(method, params) → res(ok/payload|error).
• Zu den gängigen Ereignissen gehören connect.challenge, agent, chat, session.message, session.operation, session.tool, das optional aktivierbare session.approval, sessions.changed, presence, tick, health, heartbeat, Lebenszyklusereignisse für Kopplung/Genehmigung und shutdown.

Agent-Ausführungen erfolgen in zwei Phasen:

1. Sofortige Annahmebestätigung (status:"accepted")
2. Abschließende Antwort nach Abschluss (status:"ok"|"error"), dazwischen mit gestreamten agent-Ereignissen.

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 einer Momentaufnahme.

Bereitschaft

openclaw gateway statusopenclaw channels status --probeopenclaw health

Wiederherstellung nach Lücken

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

Häufige Fehlersignaturen

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

Sicherheitsgarantien

• Gateway-Protokollclients brechen sofort ab, wenn der Gateway nicht verfügbar ist (kein impliziter Fallback auf einen direkten Kanal).
• Ungültige erste Frames beziehungsweise erste Frames, die keine Verbindungsanforderung enthalten, 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
• Remote-Zugriff
• Geheimnisverwaltung