Das Bridge-Protokoll (Legacy Node Transport)

Die Arbeit mit verschiedenen Netzwerkprotokollen kann frustrierend sein, besonders wenn du versuchst, ältere Komponenten in ein modernes System zu integrieren. Oft stellt sich die Frage, warum bestimmte Altlasten noch existieren und wie sie mit dem aktuellen Stand der Technik zusammenhängen.

Wenn du ein System wartest, das auf bewährten Strukturen basiert, musst du verstehen, wie die Datenübertragung im Hintergrund abläuft. Das Bridge-Protokoll ist ein solcher Legacy-Transport, der früher für die Kommunikation zwischen Nodes verwendet wurde, bevor der Wechsel auf WebSockets erfolgte.

Voraussetzungen

• OpenClaw (Legacy-Build)
• TCP-Netzwerkzugriff
• Ein Node-Token
• Tailnet-Zugang (optional)

Schnellstart

Wenn du eine Verbindung über das Bridge-Protokoll aufbauen willst, folgst du diesem Pfad:

1. Baue eine TCP-Verbindung zum Gateway auf (Standardport war 18790).
2. Sende einen hello-Frame als JSON-Objekt mit deinen Node-Metadaten und dem Token.
3. Falls der Node noch nicht verbunden ist, sende einen pair-request.
4. Warte auf die Antwort-Frames pair-ok und hello-ok vom Gateway.

Transport und Sicherheit

Das Protokoll basiert auf TCP und verwendet JSONL (JSON Lines), wobei jedes JSON-Objekt in einer eigenen Zeile steht.

• Port: Der Standardport für den Listener war 18790. Beachte aber, dass aktuelle OpenClaw-Builds diesen TCP-Listener nicht mehr starten.
• TLS: Sicherheit ist über bridge.tls.enabled: true möglich. In diesem Fall enthalten die Discovery-TXT-Records bridgeTls=1 und bridgeTlsSha256, damit Nodes das Zertifikat pinnen können.

Die Bridge fungiert als Sicherheitsgrenze. Sie gibt nur eine kleine Allowlist frei, statt die gesamte Gateway API-Oberfläche offenzulegen. Die Identität der Nodes wird über Tokens verwaltet, die am Gateway hinterlegt sind.

Frames und Kommunikation

Der Datenaustausch erfolgt über spezifische Frames in beide Richtungen.

Client → Gateway:

• req / res: Scoped Gateway RPC (z. B. für Chat, Sessions, Config oder Health).
• event: Signale vom Node (z. B. Voice Transcript oder Agent-Anfragen).

Gateway → Client:

• invoke / invoke-res: Befehle an den Node (z. B. camera.*, location.get oder sms.send).
• event: Chat-Updates für abonnierte Sessions.
• ping / pong: Keepalive-Checks der Verbindung.

Nodes können zudem exec.finished oder exec.denied Events senden, um Aktivitäten von system.run zu melden. Diese enthalten Felder wie sessionKey, exitCode oder output.

Tailnet und Discovery

Du kannst die Bridge an eine Tailnet-IP binden, indem du in der Datei ~/.openclaw/openclaw.json den Wert bridge.bind: "tailnet" setzt. Clients verbinden sich dann über den MagicDNS-Namen oder die direkte Tailnet-IP.

Wichtig zu wissen: Bonjour funktioniert nicht netzwerkübergreifend. Für Verbindungen außerhalb des lokalen Netzwerks musst du Host und Port manuell angeben oder Wide-Area DNS-SD verwenden.

Fehlerbehebung

• Fehler NOT_PAIRED oder UNAUTHORIZED: Das Gateway erkennt deinen Node nicht. Du musst einen pair-request senden und auf die manuelle Freigabe warten.
• Verbindung wird abgelehnt: Prüfe deinen OpenClaw-Build. Neuere Versionen enthalten den TCP-Bridge-Listener nicht mehr und unterstützen die bridge.* Konfigurationsschlüssel nicht mehr im Schema.

AI Setup Assistant

Nächste Schritte

• Gateway Protokoll
• Node Client Guide