Gateway-Runbook

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

Lokaler Start in 5 Minuten

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

Laufzeitmodell

• Ein immer 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, z. B. optional /api/v1/admin/rpc
  • Control UI und Hooks
• Standard-Bind-Modus: loopback.
• Auth ist standardmäßig erforderlich. Setups mit gemeinsamem Secret verwenden gateway.auth.token / gateway.auth.password (oder OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), und Reverse-Proxy-Setups ohne loopback können gateway.auth.mode: "trusted-proxy" verwenden.

OpenAI-kompatible Endpunkte

Die wirkungsvollste Kompatibilitätsflä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 für 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-Agenten zugeordnet ist.
• Verwenden Sie x-openclaw-model, wenn Sie einen Backend-Provider-/Modell-Override wünschen; andernfalls bleibt die normale Modell- und Embedding-Einrichtung des ausgewählten Agenten maßgeblich.

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

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

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 lokale Control-UI-Origins für Nicht-loopback-Binds gesetzt werden. Beispielsweise 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-Origins, z. B. 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 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 mehrere Gateways nur, wenn Sie absichtlich Isolation oder einen Rescue-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 unterschiedliche Gateways antworten oder wenn OpenClaw nicht nachweisen kann, dass erreichbare Ziele dasselbe Gateway sind. Ein SSH-Tunnel, eine Proxy-URL oder eine konfigurierte Remote-URL zum selben Gateway ist ein Gateway mit mehreren Transporten, auch wenn sich die Transport-Ports unterscheiden.
• Wenn dies beabsichtigt ist, isolieren Sie Ports, Konfiguration/State 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.

Remote-Zugriff

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 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

Schneller Pfad für das Dev-Profil

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

Die Standards umfassen isolierten State/isolierte Konfiguration und den Basis-Gateway-Port 19001.

Kurzreferenz zum Protokoll (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 Erkennungsliste, kein generierter Dump jeder aufrufbaren Helper-Route.
• Anfragen: req(method, params) → res(ok/payload|error).
• Häufige Events sind unter anderem connect.challenge, agent, chat, session.message, session.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, Events zum Pairing-/Approval-Lebenszyklus und shutdown.

Agent-Ausführungen sind zweistufig:

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

Siehe vollständige Protokolldokumentation: Gateway-Protokoll.

Betriebliche Prüfungen

Liveness

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

Readiness

openclaw gateway statusopenclaw channels status --probeopenclaw health

Wiederherstellung bei Lücken

Events werden nicht erneut abgespielt. Aktualisieren Sie bei Sequenzlücken den State (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 der Gateway nicht verfügbar ist (kein impliziter Fallback auf Direct-Channel).
• Ungültige bzw. Nicht-Verbindungs-First-Frames werden abgelehnt und geschlossen.
• Ein ordnungsgemäßes Herunterfahren sendet das Ereignis shutdown, bevor der Socket geschlossen wird.

Verwandt:

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

Verwandt

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