Bridge-Protokoll (Legacy-Node-Transport)

Das Bridge-Protokoll ist ein Legacy-Node-Transport (TCP JSONL). Neue Node-Clients sollten stattdessen das einheitliche Gateway-WebSocket-Protokoll verwenden.

Wenn du einen Operator oder Node-Client entwickelst, verwende das Gateway-Protokoll.

Hinweis: Aktuelle OpenClaw-Builds enthalten keinen TCP-Bridge-Listener mehr; dieses Dokument dient als historische Referenz. Legacy-bridge.*-Konfigurationsschlüssel sind nicht mehr Teil des Konfigurations-Schemas.

Warum es beides gibt

Sicherheitsgrenze: Die Bridge stellt nur eine kleine Allowlist bereit statt der gesamten Gateway-API-Oberfläche.
Pairing + Node-Identität: Die Node-Aufnahme wird vom Gateway verwaltet und ist an ein pro-Node-Token gebunden.
Discovery-UX: Nodes können Gateways via Bonjour im LAN finden oder sich direkt über ein Tailnet verbinden.
Loopback-WS: Die vollständige WS-Control-Plane 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 Legacy-Standard-Listener-Port war 18790 (aktuelle Builds starten keinen TCP-Bridge).

Bei aktiviertem TLS enthalten Discovery-TXT-Records bridgeTls=1 sowie bridgeTlsSha256 als nicht-geheimen Hinweis. Bonjour/mDNS-TXT-Records sind jedoch nicht authentifiziert; Clients dürfen den angekündigten Fingerprint nicht als verbindlichen Pin behandeln, ohne explizite Benutzerabsicht oder andere Out-of-Band-Verifizierung.

Handshake + Pairing

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

hello-ok gibt serverName zurück und kann canvasHostUrl enthalten.

Frames

Client → Gateway:

req / res: Scoped Gateway RPC (Chat, Sessions, Config, Health, Voicewake, Skills.bins)
event: Node-Signale (Voice-Transkript, Agent-Request, Chat-Subscribe, Exec-Lifecycle)

Gateway → Client:

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

Das Legacy-Allowlist-Enforcement befand sich in src/gateway/server-bridge.ts (entfernt).

Exec-Lifecycle-Events

Nodes können exec.finished- oder exec.denied-Events senden, um system.run-Aktivität sichtbar zu machen. Diese werden im Gateway auf System-Events abgebildet. (Legacy-Nodes senden möglicherweise noch exec.started.)

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

sessionKey (erforderlich): Agent-Session, die das System-Event erhalten soll.
runId: eindeutige Exec-ID zur Gruppierung.
command: roher oder formatierter Befehlsstring.
exitCode, timedOut, success, output: Abschlussdetails (nur finished).
reason: Ablehnungsgrund (nur denied).

Tailnet-Nutzung

Binde die Bridge an eine Tailnet-IP: bridge.bind: "tailnet" in ~/.openclaw/openclaw.json.
Clients verbinden sich über MagicDNS-Name oder Tailnet-IP.
Bonjour funktioniert nicht netzwerkübergreifend; verwende manuelle Host/Port-Angabe oder Wide-Area DNS‑SD wenn nötig.

Versionierung

Bridge nutzt aktuell implizit v1 (keine min/max-Verhandlung). Rückwärtskompatibilität wird erwartet; ein Bridge-Protokoll-Versionsfeld sollte vor Breaking Changes hinzugefügt werden.