Protocole de pont

Pourquoi il existait

Limite de sécurité : le pont expose une petite liste d’autorisation (allowlist) au lieu de la surface complète de l’API du gateway.
Jumelage + identité du nœud : l’admission du nœud est gérée par le gateway et liée à un jeton par nœud.
UX de découverte : les nœuds peuvent découvrir les gateways via Bonjour sur le réseau local, ou se connecter directement via un tailnet.
Bouclage WS : le plan de contrôle WS complet reste local sauf s’il est tunnellisé via SSH.

Transport

TCP, un objet JSON par ligne (JSONL).
TLS facultatif (lorsque bridge.tls.enabled est vrai).
Historiquement, le port d’écoute par défaut était 18790 (les versions actuelles ne démarrent pas de pont TCP).

Lorsque le TLS est activé, les enregistrements TXT de découverte incluent bridgeTls=1 plus bridgeTlsSha256 comme indice non secret. Notez que les enregistrements TXT Bonjour/mDNS ne sont pas authentifiés ; les clients ne doivent pas traiter l’empreinte digitale annoncée comme un épinglage (pin) faisant autorité sans une intention explicite de l’utilisateur ou une autre vérification hors bande.

Poignée de main + jumelage

Le client envoie hello avec les métadonnées du nœud + le jeton (si déjà jumelé).
S’il n’est pas jumelé, le gateway répond error (NOT_PAIRED/UNAUTHORIZED).
Le client envoie pair-request.
Le Gateway attend l’approbation, puis envoie pair-ok et hello-ok.

Historiquement, hello-ok renvoyait serverName; les surfaces de plugins hébergés sont maintenant annoncées via pluginSurfaceUrlsCanvas. Canvas/A2UI utilise pluginSurfaceUrls.canvas; l’alias obsolète canvasHostUrl ne fait pas partie du protocole refactorisé.

Trames

Client → Gateway :

req / resRPC : RPC passerelle avec portée (chat, sessions, config, santé, voicewake, skills.bins)
event : signaux de nœud (transcription vocale, requête d’agent, abonnement chat, cycle de vie exec)

Gateway → Client :

invoke / invoke-res : commandes de nœud (canvas.*, camera.*, screen.record, location.get, sms.send)
event : mises à jour de chat pour les sessions abonnées
ping / pong : keepalive

L’application héritée de la liste d’autorisation résidait dans src/gateway/server-bridge.ts (supprimé).

Événements de cycle de vie de l’exécution

Les nœuds peuvent émettre des événements exec.finished pour signaler l’activité system.run terminée. Ces événements sont mappés à des événements système dans la passerelle. (Les nœuds hérités peuvent encore émettre exec.started.) Les nœuds peuvent émettre exec.denied pour les tentatives system.run refusées ; la passerelle accepte l’événement comme un refus définitif et ne met pas en file d’attente un événement système ni ne réveille le travail de l’agent.

Champs de payload (tous optionnels sauf indication contraire) :

sessionKey (requis) : session de l’agent pour la corrélation des événements et, pour exec.finished, la livraison des événements système.
runId : identifiant d’exécution unique pour le regroupement.
command : chaîne de commande brute ou formatée.
exitCode, timedOut, success, output : détails de l’achèvement (terminé uniquement).
reason : motif du refus (refusé uniquement).

Utilisation historique du tailnet

Lier le pont à une IP de tailnet : bridge.bind: "tailnet" dans ~/.openclaw/openclaw.json (historique uniquement ; bridge.* n’est plus valide).
Les clients se connectent via le nom MagicDNS ou l’IP du tailnet.
Bonjour ne traverse pas les réseaux ; utilisez un hôte/port manuel ou un DNS-SD étendu si nécessaire.

Versionnage

Le pont était en v1 implicite (sans négociation min/max). Cette section est une référence historique uniquement ; les clients nœuds/opérateurs actuels utilisent le WebSocket Protocole Gateway.