Protocole de pont
Pourquoi il existait
Section intitulée « 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
Section intitulée « Transport »- TCP, un objet JSON par ligne (JSONL).
- TLS facultatif (lorsque
bridge.tls.enabledest 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
Section intitulée « Poignée de main + jumelage »- Le client envoie
helloavec 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-okethello-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é.
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éesping/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
Section intitulée « Événements de cycle de vie de l’exécution »Les nœuds peuvent émettre des événements exec.finished ou exec.denied pour exposer l’activité system.run.
Ceux-ci sont mappés aux événements système dans la passerelle. (Les nœuds hérités peuvent encore émettre exec.started.)
Champs de payload (tous optionnels sauf indication contraire) :
sessionKey(requis) : session agent pour recevoir l’événement système.runId: id exec unique pour le regroupement.command: chaîne de commande brute ou formatée.exitCode,timedOut,success,output: détails de finition (terminé uniquement).reason: motif du refus (refusé uniquement).
Utilisation historique du tailnet
Section intitulée « Utilisation historique du tailnet »- Lier le pont à une IP 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
Section intitulée « Versionnage »Le pont était en v1 implicite (sans négociation min/max). Cette section est une référence historique uniquement ; les clients nœud/opérateur actuels utilisent le WebSocket Gateway Protocol.