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

Ausführliche Fehlerbehebung

Symptombasierte Diagnose mit genauen Befehlsfolgen und Log-Signaturen.

Konfiguration

Aufgabenorientierte Einrichtungsanleitung und vollständige Konfigurationsreferenz.

Secret-Verwaltung

SecretRef-Vertrag, Verhalten von Laufzeit-Snapshots sowie Migrations- und Neuladevorgänge.

Vertrag für den Secrets-Plan

Genaue secrets apply-Ziel-/Pfadregeln und Verhalten von Authentifizierungsprofilen, die ausschließlich Referenzen enthalten.

​
Lokale Inbetriebnahme in 5 Minuten

1

Gateway starten

2

Dienstzustand überprüfen

Gesunder Ausgangszustand: Runtime: running, Connectivity probe: ok und eine Ihren Erwartungen entsprechende Capability-Zeile. Verwenden Sie openclaw gateway status --require-rpc als RPC-Nachweis für den Lesezugriff, nicht nur für die Erreichbarkeit.
3

Kanalbereitschaft validieren

Bei erreichbarem Gateway führt dies Live-Kanalprüfungen pro Konto und optionale Audits aus. Ist das Gateway nicht erreichbar, greift die CLI auf rein konfigurationsbasierte Kanalzusammenfassungen zurück.
Das Neuladen der Gateway-Konfiguration überwacht den Pfad der aktiven Konfigurationsdatei, der aus den Profil-/Zustandsvorgaben oder, falls festgelegt, aus OPENCLAW_CONFIG_PATH aufgelöst wird. Der Standardmodus ist gateway.reload.mode="hybrid". Nach dem ersten erfolgreichen Laden stellt der laufende Prozess den aktiven Konfigurations-Snapshot im Arbeitsspeicher bereit; ein erfolgreiches Neuladen ersetzt diesen Snapshot atomar.

​
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

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:
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:
Ausführliche Einrichtung: /gateway/multiple-gateways.

​
Remote-Zugriff

Bevorzugt: Tailscale/VPN. Ausweichlösung: SSH-Tunnel.
Verbinden Sie Clients anschließend lokal mit ws://127.0.0.1:18789.
SSH-Tunnel umgehen die Gateway-Authentifizierung nicht. Bei der Authentifizierung mit gemeinsamem Secret müssen Clients auch über den Tunnel weiterhin token/password senden. Bei identitätstragenden Modi muss die Anfrage weiterhin den entsprechenden Authentifizierungspfad erfüllen.
Siehe: Remote-Gateway, Authentifizierung, Tailscale.

​
Überwachung und Dienstlebenszyklus

Verwenden Sie überwachte Ausführungen für eine produktionsähnliche Zuverlässigkeit.
Verwenden Sie openclaw gateway restart für Neustarts. Verketten Sie openclaw gateway stop und openclaw gateway start nicht als Ersatz für einen Neustart.Unter macOS verwendet gateway stop standardmäßig launchctl bootout. Dadurch wird der LaunchAgent aus der aktuellen Startsitzung entfernt, ohne eine Deaktivierung dauerhaft zu speichern. Die automatische Wiederherstellung durch KeepAlive funktioniert somit weiterhin nach unerwarteten Abstürzen, und gateway start aktiviert den Dienst wieder ordnungsgemäß. Um den automatischen Neustart über Systemneustarts hinweg dauerhaft zu unterdrücken, übergeben Sie --disable: openclaw gateway stop --disable.LaunchAgent-Bezeichnungen sind ai.openclaw.gateway (Standard) oder ai.openclaw.<profile> (benanntes Profil). openclaw doctor prüft und behebt Abweichungen der Dienstkonfiguration.
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

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

​
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