Bridge Protocol (Legacy Node-Transport)

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

Wenn du einen Operator- oder Node-Client entwickelst, nutze das Gateway Protocol.

Hinweis: Aktuelle OpenClaw-Builds enthalten keinen TCP Bridge Listener mehr. Dieses Dokument dient nur noch als historische Referenz. Die alten bridge.* Config-Keys sind nicht mehr Teil des Config-Schemas.

Warum es beide gibt

  • Sicherheitsgrenze: Die Bridge stellt nur eine kleine Allowlist bereit, nicht die gesamte Gateway API.
  • Pairing + Node-Identität: Die Node-Zulassung wird vom Gateway verwaltet und ist an einen Node-spezifischen Token gebunden.
  • Discovery UX: Nodes können Gateways per Bonjour im LAN finden oder sich direkt über ein Tailnet verbinden.
  • Loopback WS: Die vollständige WS Control Plane bleibt lokal, es sei denn, sie wird per SSH getunnelt.

Transport

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

Bei aktiviertem TLS enthalten die Discovery TXT Records bridgeTls=1 sowie bridgeTlsSha256, damit Nodes das Zertifikat pinnen können.

Handshake + Pairing

  1. Der Client sendet hello mit Node-Metadaten + Token (falls bereits gepairt).
  2. Falls nicht gepairt, antwortet das Gateway mit error (NOT_PAIRED/UNAUTHORIZED).
  3. Der Client sendet pair-request.
  4. Das 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 Transcript, 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

Die alte Allowlist-Durchsetzung 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äten anzuzeigen. Diese werden im Gateway auf System Events gemappt. (Legacy Nodes senden möglicherweise noch exec.started.)

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

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

Tailnet-Nutzung

  • Binde die Bridge an eine Tailnet-IP: bridge.bind: "tailnet" in ~/.openclaw/openclaw.json.
  • Clients verbinden sich über MagicDNS-Namen oder Tailnet-IP.
  • Bonjour funktioniert nicht netzwerkübergreifend. Nutze bei Bedarf manuelle Host/Port-Angaben oder Wide-Area DNS-SD.

Versionierung

Das Bridge Protocol ist derzeit implizit v1 (keine Min/Max-Aushandlung). Abwärtskompatibilität wird erwartet. Füge ein Bridge Protocol Version-Feld hinzu, bevor du Breaking Changes einführst.