Gateway-Integrationen für externe Apps

Externe Anwendungen kommunizieren mit OpenClaw über das Gateway-Protokoll: WebSocket- Transport sowie RPC-Methoden. Verwenden Sie es, wenn ein Skript, Dashboard, CI-Auftrag, eine IDE- Erweiterung oder ein anderer Prozess Agent-Ausführungen starten, Ereignisse streamen, auf Ergebnisse warten, Arbeit abbrechen oder Gateway-Ressourcen untersuchen soll.

Was heute verfügbar ist

Empfohlener Ablauf

1. Führen Sie ein Gateway aus oder ermitteln Sie eines.
2. Stellen Sie über das Gateway-Protokoll eine Verbindung her.
3. Rufen Sie dokumentierte RPC-Methoden aus der Gateway-RPC-Referenz auf.
4. Fixieren Sie die OpenClaw-Version, gegen die Sie testen.
5. Prüfen Sie beim Upgrade von OpenClaw die RPC-Referenz erneut.

Beginnen Sie für Agent-Ausführungen mit dem RPC agent und kombinieren Sie ihn für ein abschließendes Ergebnis mit agent.wait. Verwenden Sie für dauerhaften Konversationszustand die Methoden sessions.*. Abonnieren Sie bei UI-Integrationen Gateway-Ereignisse und stellen Sie nur die Ereignisfamilien dar, die Ihre Anwendung versteht.

Kooperative Host-Suspendierung

Hosting-Controller, die einen laufenden Prozess einfrieren oder als Snapshot sichern, können den hostneutralen Suspendierungs-Handshake verwenden:

1. Nehmen Sie keinen weiteren vom Host gesteuerten externen Eingangsdatenverkehr an.
2. Rufen Sie gateway.suspend.prepare mit einer stabilen, eindeutigen requestId auf.
3. Wenn die Antwort busy lautet, lassen Sie den Prozess weiterlaufen und versuchen Sie es später erneut.
4. Wenn sie ready lautet, speichern Sie die zurückgegebene suspensionId und frieren Sie den Prozess vor expiresAtMs ein oder erstellen Sie einen Snapshot.
5. Rufen Sie nach dem Reaktivieren oder wenn die Suspendierung verworfen wird gateway.suspend.resume mit dieser suspensionId über den bestehenden WebSocket- oder Admin-HTTP-Steuerungspfad auf.

Ein vorbereitetes Gateway lehnt neue WebSocket-Handshakes ab. Ein WebSocket-Controller muss seine authentifizierte Verbindung während des Host-Vorgangs geöffnet halten. Wenn dies nicht gewährleistet werden kann, aktivieren und verwenden Sie vor der Vorbereitung das Admin-HTTP-RPC-Plugin. Wenn der Steuerungspfad verloren geht, warten Sie vor der Wiederverbindung, bis die zweiminütige Lease abgelaufen ist; nach Ablauf wird die Annahme automatisch wieder geöffnet.

Der RPC-Vertrag lautet:

• gateway.suspend.prepare — operator.admin; Parameter { "requestId": "stable-host-operation-id" }
• gateway.suspend.status — operator.read; Parameter { "suspensionId": "id-from-prepare" }
• gateway.suspend.resume — operator.admin; Parameter { "suspensionId": "id-from-prepare" }

IDs werden von umgebenden Leerzeichen bereinigt, müssen ein Zeichen enthalten, das kein Leerzeichen ist, und sind auf 128 Zeichen begrenzt. Ein Vorbereitungsergebnis bei Auslastung enthält status: "busy", reason, retryAfterMs, activeCount und blockers. Ein Bereitschaftsergebnis hat diese Struktur:

{  "status": "ready",  "suspensionId": "2c3f...",  "expiresAtMs": 1770000000000,  "activeCount": 0,  "blockers": []}

Der Status gibt {"status":"running"} oder ein Bereitschaftsergebnis mit expiresAtMs zurück. Die Wiederaufnahme gibt {"ok":true,"status":"running","resumed":true} zurück; eine Wiederholung nach erfolgreicher Wiederaufnahme gibt resumed: false zurück.

Eine konkurrierende Anforderungs-ID oder ein vorübergehender Fehler bei der Wiederaufnahme des Schedulers gibt den wiederholbaren Fehler UNAVAILABLE mit retryAfterMs zurück. Während der Scheduler-Wiederherstellung geben Vorbereitung, Status und Wiederaufnahme jeweils diesen Fehler zurück, das Gateway bleibt nicht bereit und schlägt im geschlossenen Zustand fehl, und der Host darf es nicht einfrieren oder als Snapshot sichern. OpenClaw wiederholt die Scheduler-Wiederherstellung automatisch und öffnet die Annahme erst wieder, nachdem die Wiederherstellung erfolgreich war. Eine nicht übereinstimmende Wiederaufnahme-ID gibt INVALID_REQUEST zurück. Die Vorbereitung verwendet das Schreibbudget der Gateway- Steuerungsebene von drei Versuchen pro Minute; beachten Sie die zurückgegebene Wiederholungsverzögerung. WebSocket-Clients werden nach Gerät und IP gruppiert. Admin-HTTP- Controller werden nach der aufgelösten Client-IP gruppiert, sodass Controller hinter demselben Proxy ein Budget gemeinsam nutzen können.

Die Vorbereitung dient ausschließlich der Ablehnung: OpenClaw schließt die Annahme neuer Root-/Sitzungs-/Befehlsvorgänge, pausiert automatische Cron-Ticks und prüft laufende Arbeit synchron. Wenn etwas aktiv ist, nimmt es den Scheduler wieder auf und öffnet die Annahme erneut, bevor busy zurückgegeben wird; diese Arbeit wird weder unterbrochen noch abgearbeitet. Eine Bereitschafts-Lease gilt zwei Minuten. Durch Wiederholen von prepare mit derselben requestId wird sie verlängert; nach Ablauf wird der Scheduler wieder aufgenommen, bevor die Annahme erneut geöffnet wird. Eine Neustartausgabe, die während einer Bereitschafts-Lease fällig wird, wartet, bis die Lease wieder aufgenommen wird; bei einem laufenden Neustart gibt die Vorbereitung busy zurück.

Während der Bereitschaft bleibt /healthz aktiv und /readyz gibt 503 zurück. Lokale oder authentifizierte Bereitschaftsantworten enthalten gateway-draining; nicht authentifizierte Remote-Prüfungen erhalten nur { "ready": false }. Die HTTP-Zustandsprüfung, Suspendierungsmethoden auf bestehenden WebSocket-Verbindungen und eine bereits aktivierte Admin-HTTP-RPC-Route bleiben verfügbar. Andere RPCs geben den wiederholbaren Fehler UNAVAILABLE zurück. Integrierte HTTP-Routen für Benutzerarbeit und gewöhnliche Plugin-HTTP-Routen, einschließlich OpenAI-kompatibler APIs, Werkzeug-/Sitzungsvorgänge, Node-Überwachungen und konfigurierter Hooks, geben 503 mit error.code: "gateway_unavailable" zurück. Neue Plugin-eigene WebSocket-Upgrades geben ebenfalls 503 zurück; dies betrifft die Zuständigkeit für Upgrades, nicht Arbeit, die später über einen bereits hergestellten Plugin-Socket ausgeführt wird.

Dieser Handshake speichert keine eingehenden Nachrichten dauerhaft, stoppt keine Kanal- Transporte von Drittanbietern und steuert nicht die Hosting-Plattform. Der Host muss seinen Eingangsdatenverkehr vor der Vorbereitung abschirmen und bleibt für das Aufwecken, die Snapshot-Erstellung beziehungsweise das Einfrieren und das Stoppen verantwortlich. activeCount ist die Gesamtanzahl der nachverfolgten Arbeiten, während blockers die von null abweichenden Kategorieanzahlen und begrenzten Aufgabendetails enthält. Dies ist keine allgemeine Barriere für den Ruhezustand des Prozesses. Ein background-exec-Blockierer ist nur aggregiert: Befehlstext, Prozess-IDs, Ausgabe sowie Sitzungs- oder Bereichskennungen werden niemals über das Protokoll übertragen. Kanalzustand, Wartung, Cache-Aktualisierung, bestehende Plugin-WebSocket-Sitzungen und nicht registrierte Plugin-eigene Hintergrundarbeit können aktiv bleiben. Die Hosting-Plattform muss den vollständigen Prozessbaum und sein Dateisystem konsistent einfrieren oder als Snapshot sichern; bei nicht registrierter Arbeit kann durch diesen ersten Vertrag kein Leerlauf nachgewiesen werden.

Anwendungscode und Plugin-Code

Verwenden Sie Gateway-RPC, wenn sich der Code außerhalb von OpenClaw befindet:

• Node-Skripte, die Agent-Ausführungen starten oder beobachten
• CI-Aufträge, die ein Gateway aufrufen
• Dashboards und Administrationsoberflächen
• IDE-Erweiterungen
• externe Brücken, die nicht zu Kanal-Plugins werden müssen
• Integrationstests mit simulierten oder echten Gateway-Transporten

Verwenden Sie das Plugin SDK, wenn Code innerhalb von OpenClaw ausgeführt wird:

• Provider-Plugins
• Kanal-Plugins
• Werkzeug- oder Lebenszyklus-Hooks
• Agent-Harness-Plugins
• vertrauenswürdige Laufzeit-Hilfsprogramme

Externe Anwendungen sollten openclaw/plugin-sdk/* nicht importieren; diese Unterpfade sind für Plugins bestimmt, die von OpenClaw geladen werden.

Verwandte Themen

• Erstellen eines Gateway-Clients
• Einbetten von OpenClaw
• Gateway-Protokoll
• Gateway-RPC-Referenz
• CLI-Agent-Befehl
• CLI-Nachrichtenbefehl
• Agent-Schleife
• Agent-Laufzeitumgebungen
• Sitzungen
• Hintergrundaufgaben
• ACP-Agenten
• Übersicht über das Plugin SDK