Gateway

Brückenprotokoll

Warum es sie gab

Sicherheitsgrenze: Die Bridge stellt eine kleine Zulassungsliste statt der vollständigen Gateway-API-Oberfläche bereit.
Pairing + Node-Identität: Die Node-Zulassung gehört dem Gateway und ist an ein Token pro Node gebunden.
Discovery-UX: Nodes können Gateways per Bonjour im LAN erkennen oder sich direkt über ein Tailnet verbinden.
Loopback-WS: Die vollständige WS-Steuerungsebene bleibt lokal, sofern sie nicht per SSH getunnelt wird.

Transport

TCP, ein JSON-Objekt pro Zeile (JSONL).
Optionales TLS (wenn bridge.tls.enabled true ist).
Der historische Standard-Listener-Port war 18790 (aktuelle Builds starten keine TCP-Bridge).

Wenn TLS aktiviert ist, enthalten Discovery-TXT-Einträge bridgeTls=1 plus bridgeTlsSha256 als nicht geheime Kennung. Beachten Sie, dass Bonjour-/mDNS-TXT-Einträge nicht authentifiziert sind; Clients dürfen den beworbenen Fingerprint ohne ausdrückliche Nutzerabsicht oder andere Out-of-Band-Verifizierung nicht als autoritativen Pin behandeln.

Handshake + Pairing

Der Client sendet hello mit Node-Metadaten + Token (falls bereits gepairt).
Wenn nicht gepairt, antwortet das Gateway mit error (NOT_PAIRED/UNAUTHORIZED).
Der Client sendet pair-request.
Das Gateway wartet auf Genehmigung und sendet dann pair-ok und hello-ok.

Historisch gab hello-ok serverName zurück; gehostete Plugin-Oberflächen werden jetzt über pluginSurfaceUrls bekanntgegeben. Canvas/A2UI verwendet pluginSurfaceUrls.canvas; der veraltete Alias canvasHostUrl ist nicht Teil des überarbeiteten Protokolls.

Frames

Client → Gateway:

req / res: Gateway-RPC mit begrenztem Scope (Chat, Sitzungen, Konfiguration, Zustand, Voicewake, skills.bins)
event: Node-Signale (Sprachtranskript, Agent-Anforderung, Chat-Abonnement, Exec-Lifecycle)

Gateway → Client:

invoke / invoke-res: Node-Befehle (canvas.*, camera.*, screen.record, location.get, sms.send)
event: Chat-Aktualisierungen für abonnierte Sitzungen
ping / pong: Keepalive

Die Legacy-Durchsetzung der Zulassungsliste befand sich in src/gateway/server-bridge.ts (entfernt).

Exec-Lifecycle-Ereignisse

Nodes können exec.finished-Ereignisse ausgeben, um abgeschlossene system.run-Aktivität sichtbar zu machen. Diese werden im Gateway auf Systemereignisse abgebildet. (Legacy-Nodes können weiterhin exec.started ausgeben.) Nodes können exec.denied für abgelehnte system.run-Versuche ausgeben; das Gateway akzeptiert das Ereignis als terminale Ablehnung und stellt kein Systemereignis ein und weckt keine Agent-Arbeit.

Payload-Felder (alle optional, sofern nicht angegeben):

sessionKey (erforderlich): Agent-Sitzung für Ereigniskorrelation und, für exec.finished, Systemereigniszustellung.
runId: eindeutige Exec-ID zur Gruppierung.
command: roher oder formatierter Befehlsstring.
exitCode, timedOut, success, output: Abschlussdetails (nur finished).
reason: Ablehnungsgrund (nur denied).

Historische Tailnet-Nutzung

Binden Sie die Bridge an eine Tailnet-IP: bridge.bind: "tailnet" in ~/.openclaw/openclaw.json (nur historisch; bridge.* ist nicht mehr gültig).
Clients verbinden sich über den MagicDNS-Namen oder die Tailnet-IP.
Bonjour überschreitet keine Netzwerkgrenzen; verwenden Sie bei Bedarf manuellen Host/Port oder Wide-Area-DNS-SD.

Versionierung

Die Bridge war implizit v1 (keine Min-/Max-Aushandlung). Dieser Abschnitt dient nur als historische Referenz; aktuelle Node-/Operator-Clients verwenden das WebSocket- Gateway-Protokoll.

Verwandt

Was this useful?