Gateway

Erstellen eines Gateway-Clients

Verwenden Sie die veröffentlichten Gateway-Pakete, um Operator-Dashboards, WebChat-Clients und andere Drittanbieteranwendungen zu entwickeln. Dieser Leitfaden behandelt den Client-Lebenszyklus rund um den Wire-Vertrag: Authentifizierung, Fähigkeiten, Wiederherstellung nach erneuter Verbindung, Verlauf, Abonnements und Versionsupgrades.

Informationen zu Frame-Strukturen, Handshake, Fehlern und der vollständigen Methodenoberfläche finden Sie in der Gateway-Protokollspezifikation.

Pakete installieren

bash

npm install @openclaw/gateway-client @openclaw/gateway-protocol

@openclaw/gateway-protocol stellt Schemas, Laufzeit-Validatoren, TypeScript-Typen, Registrys für Client-Identitäten und Fähigkeiten, strukturierte Fehlerleser und Protokollversionskonstanten bereit. Das npm-Tarball enthält außerdem den generierten maschinenlesbaren Vertrag protocol.schema.json.
@openclaw/gateway-client ist die Referenzimplementierung für Verbindungen. Importieren Sie den Paketstamm für den Node-Client und @openclaw/gateway-client/browser für die browsersicheren Protokoll-, Geräteauthentifizierungs- und Wiederverbindungshelfer.

Der Node-Einstiegspunkt verwaltet seinen WebSocket-Transport selbst. Ein Browser-Host stellt einen WebSocket- Adapter sowie persistente Speicher- und Signierungs-Callbacks für die Geräteidentität und das Geräte-Token bereit.

Bereiche auswählen und Gerät koppeln

Ein vollständiger interaktiver Chat-Client, der auch Genehmigungsaufforderungen darstellt, sollte role: "operator" mit diesen Bereichen anfordern:

Bereich	Verwendung
`operator.read`	`chat.history`, `sessions.list`, `sessions.subscribe`, Modellstatus und schreibgeschützte Ereignisse
`operator.write`	`chat.send` und gewöhnliche Sitzungsänderungen
`operator.approvals`	Auflisten, Anzeigen und Auflösen von Ausführungs- oder Plugin-Genehmigungen

Fügen Sie operator.questions nur hinzu, wenn der Client interaktive Fragen verarbeitet, operator.pairing nur, wenn er gekoppelte Geräte oder Nodes verwaltet, und operator.admin nur für administrative Vorgänge wie config.patch. Die Referenz zu Operator-Bereichen definiert die vollständigen Regeln für Methoden und Genehmigungszeitpunkte.

Erstellen Sie kein Bearer-Token pro Client, indem Sie openclaw.json manuell bearbeiten. Konfigurieren Sie die gemeinsame Bootstrap-Authentifizierung des Gateways mit openclaw configure --section gateway oder den Optionen openclaw onboard --gateway-auth ... und lassen Sie dann durch die Gerätekopplung das Client-Token ausstellen:

Persistieren Sie eine Ed25519-Geräteidentität im Client.
Warten Sie auf connect.challenge, signieren Sie die an die Challenge gebundene Gerätenutzlast und senden Sie connect mit der angeforderten Operator-Rolle, den Bereichen und dem gemeinsamen Gateway-Token oder Passwort für die Bootstrap-Authentifizierung.
Wenn das Gateway strukturierte PAIRING_REQUIRED-Details zurückgibt, zeigen Sie die Anfrage- ID an und pausieren Sie oder versuchen Sie es gemäß error.details.recommendedNextStep erneut.
Prüfen Sie die Anfrage auf dem Gateway-Host mit openclaw devices list und genehmigen Sie anschließend genau diese aktuelle Anfrage mit openclaw devices approve <requestId>.
Stellen Sie die Verbindung erneut her und persistieren Sie hello-ok.auth.deviceToken mit der ausgehandelten Rolle und den Bereichen. Verwenden Sie dieses Geräte-Token für spätere Verbindungen.

Upgrades von Bereichen oder Rollen erzeugen eine neue ausstehende Kopplungsanfrage. Eine Token-Rotation kann den genehmigten Kopplungsvertrag nicht erweitern. Informationen zu Befehlen für Genehmigung, Rotation und Widerruf finden Sie in der Geräte-CLI.

Client-Fähigkeiten bekannt geben

connect.params.caps beschreibt optionales Verhalten, das der Client nutzen kann. Es gewährt keine Autorisierung. Importieren Sie Namen aus GATEWAY_CLIENT_CAPS, anstatt String-Literale zu duplizieren:

 const caps = [GATEWAY_CLIENT_CAPS.TOOL_EVENTS];

Die aktuelle Registry enthält approvals, exec-approvals, inline-widgets, run-tool-bindings, session-scoped-events, plugin-approvals, task-suggestions, terminal-offset-seq, tool-events und ui-commands. Geben Sie nur Fähigkeiten bekannt, die der Client tatsächlich implementiert.

Durch Fähigkeiten gesteuerte Agent-Tools sind eine separate Verwendung derselben Deklaration. Wenn ein Agent-Tool eine Client-Fähigkeit voraussetzt, lässt das Gateway dieses Tool weg, sofern der ursprüngliche Client nicht jede erforderliche Fähigkeit bekannt gegeben hat.

Zustand nach erneuter Verbindung wiederherstellen

Behandeln Sie jede erfolgreiche erneute Verbindung als neue Projektion über den dauerhaften Verlauf und den aktuellen In-Memory-Laufzustand:

Stellen Sie sessions.subscribe und das sessions.messages.subscribe-Abonnement der ausgewählten Sitzung erneut her.
Rufen Sie chat.history für den ausgewählten sessionKey auf und ersetzen Sie lokal persistierte Zeilen durch die zurückgegebene messages-Projektion.
Wenn inFlightRun vorhanden ist, übernehmen Sie dessen runId, gepuffertes text und optionales plan. Übernehmen Sie den Lauf auch dann, wenn text leer ist.
Lesen Sie sessionInfo.hasActiveRun und sessionInfo.activeRunIds. Bevorzugen Sie die exakte Zugehörigkeit in activeRunIds, wenn Sie entscheiden, ob ein beibehaltener Lauf weiterhin die Streaming-Benutzeroberfläche besitzt. Ein wahrer Wert für hasActiveRun ohne aufgeführte ID kann eine andere aktive Laufzeitprojektion darstellen.
Gleichen Sie nachfolgende agent-Ereignisse anhand von payload.runId und payload.seq ab. Verwalten Sie die höchste akzeptierte Sequenz für jeden Lauf unabhängig, ignorieren Sie eine bereits gesehene oder niedrigere Sequenz und behandeln Sie eine vorwärts gerichtete Lücke als Grund, den maßgeblichen Verlauf neu zu laden.

Der äußere Ereignis-Frame verfügt außerdem über ein optionales seq, das Ereignisse in der aktuellen WebSocket-Verbindung ordnet. Bei einer neuen Verbindung wird es zurückgesetzt. Das seq innerhalb der Nutzlast eines agent-Ereignisses wird pro Lauf zugewiesen und ordnet die Lebenszyklus-, Assistenten-, Plan-, Tool- und sonstigen Stream-Ereignisse dieses Laufs.

Verlaufsmetadaten und stabile Anker verwenden

Von chat.history zurückgegebene Zeilen können einen __openclaw-Metadatenumschlag enthalten:

id ist die Identität des Transkripteintrags. Verwenden Sie sie für verankerte Verlaufsanfragen, jedoch nicht als eindeutigen Schlüssel für Anzeigezeilen.
seq ist die positive Sequenz des Transkriptdatensatzes. Ein gespeicherter Datensatz kann in mehr als eine Anzeigezeile projiziert werden; halten Sie daher zusammengehörige Zeilen mit demselben id und derselben Sequenz zusammen.
kind kennzeichnet synthetische Zeilen. Eine Compaction-Grenze verwendet kind: "compaction" und kann tokensBefore und tokensAfter enthalten, wenn ein passender Checkpoint diese Metriken aufgezeichnet hat.

Blättern Sie mit den Werten hasMore und nextOffset der Antwort rückwärts. Numerische Offsets beschreiben die aktuelle Transkriptprojektion; persistieren Sie sie daher nicht als langfristige Lesezeichen über Zurücksetzungen oder Compaction hinweg. Persistieren Sie stattdessen __openclaw.id. Um den Bereich um eine bekannte Zeile wiederherzustellen, rufen Sie chat.history mit messageId und dem sessionId auf, das diesen Wert zurückgegeben hat. Das Gateway kann diesen Anker aus dem Verlauf des Zurücksetzungsarchivs auflösen; verankerte Antworten lassen numerische Metadaten zur Seitennavigation absichtlich weg.

Nutzung abonnieren statt abfragen

Laden Sie den anfänglichen Katalog mit sessions.list und rufen Sie anschließend sessions.subscribe einmal pro Verbindung auf. Führen Sie sessions.changed-Ereignisse anhand von sessionKey zusammen. Nutzlasten zu Sitzungsänderungen können Live-Werte für inputTokens, outputTokens, totalTokens, totalTokensFresh, contextTokens, estimatedCostUsd, Einstellungen zur Antwortnutzung und den Zustand aktiver Läufe enthalten.

Einige Änderungsbenachrichtigungen sind lediglich Invalidierungssignale. Wenn ein Ereignis die Zeilenfelder auslässt, die Ihre Ansicht benötigt, aktualisieren Sie sessions.list. Fragen Sie usage.cost oder sessions.usage nicht regelmäßig ab, um eine Live-Sitzungsliste aktuell zu halten; verwenden Sie diese Methoden nur für bei Bedarf erstellte aggregierte oder detaillierte Berichte.

Ausführungsgenehmigungen nachladen

Ein Client mit operator.approvals sollte seinen Ereignis-Listener installieren, sobald hello-ok abgeschlossen ist, und anschließend exec.approval.list aufrufen, um Anfragen nachzuladen, die vor der Verbindung eingegangen sind. Gleichen Sie die Liste und die Live-Ereignisse exec.approval.requested / exec.approval.resolved anhand der Genehmigungs-ID ab, damit ein Übergang, der zeitgleich mit der Listenanfrage erfolgt, weder verloren geht noch wiederhergestellt wird.

Protokollversionen verfolgen

Die aktuelle Wire-Version ist 4. Allgemeine Operator- und WebChat-Clients müssen die exakt aktuelle Version mit minProtocol: 4 und maxProtocol: 4 aushandeln. Nur authentifizierte Node-Clients und leichtgewichtige Prüfroutinen verfügen über das N-1-Akzeptanzfenster, derzeit von Protokoll 3 bis 4.

Protokolländerungen sind zunächst additiv. protocol.schema.json enthält since- Metadaten zum Release-Stand und Metadaten zu erforderlichen Bereichen für Kernmethoden, aber eine Erhöhung der Wire-Version ist weiterhin ein explizit inkompatibles Ereignis für Drittanbieter-Clients. Fixieren Sie die getesteten Paketversionen, aktualisieren Sie Client und Gateway gemeinsam, wenn sich die Wire- Version ändert, und prüfen Sie vor jedem Upgrade das OpenClaw-Änderungsprotokoll.