Brückenprotokoll

# Warum sie existierte

• Sicherheitsgrenze: Die Bridge stellt eine kleine Allowlist statt der vollständigen Gateway-API-Oberfläche bereit.
• Pairing + Node-Identität: Die Node-Zulassung liegt beim Gateway und ist an ein token pro Node gebunden.
• Discovery-UX: Nodes können Gateways über Bonjour im LAN erkennen oder sich direkt über ein Tailnet verbinden.
• Loopback-WS: Die vollständige WS-Steuerungsebene bleibt lokal, sofern sie nicht über 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-Records bridgeTls=1 plus bridgeTlsSha256 als nicht geheimen Hinweis. Beachten Sie, dass Bonjour-/mDNS-TXT-Records nicht authentifiziert sind; Clients dürfen den angekündigten Fingerprint ohne ausdrückliche Benutzerabsicht oder andere Out-of-Band-Verifizierung nicht als autoritatives Pinning behandeln.

# Handshake + Pairing

1. Der Client sendet hello mit Node-Metadaten + token (falls bereits gekoppelt).
2. Wenn nicht gekoppelt, antwortet das Gateway mit error (NOT_PAIRED/UNAUTHORIZED).
3. Der Client sendet pair-request.
4. Das Gateway wartet auf die Freigabe und sendet dann pair-ok und hello-ok.

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

# Frames

Client → Gateway:

• req / res: begrenztes Gateway-RPC (Chat, Sitzungen, Konfiguration, Zustand, Voicewake, skills.bins)
• event: Node-Signale (Sprachtranskript, Agent-Anfrage, Chat-Abonnement, Exec-Lebenszyklus)

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-Allowlist-Durchsetzung lag in src/gateway/server-bridge.ts (entfernt).

# Exec-Lebenszyklusereignisse

Nodes können exec.finished- oder exec.denied-Ereignisse ausgeben, um system.run-Aktivität sichtbar zu machen. Diese werden im Gateway Systemereignissen zugeordnet. (Legacy-Nodes können weiterhin exec.started ausgeben.)

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

• sessionKey (erforderlich): Agent-Sitzung, die das Systemereignis erhalten soll.
• runId: eindeutige Exec-ID für die Gruppierung.
• command: rohe oder formatierte Befehlszeichenfolge.
• 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 funktioniert nicht netzwerkübergreifend; 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

• Gateway-Protokoll
• Nodes