Présence

La « présence » d’OpenClaw est une vue légère et au mieux des possibilités de :

• le Gateway lui-même, et
• les clients visibles par l’utilisateur connectés au Gateway (application Mac, WebChat, nœuds, etc.)

La présence affiche les métadonnées de connexion en direct sur la page Appareils de l’interface de contrôle et dans l’onglet Instances de l’application macOS.

Cette page décrit la liste des clients du Gateway. Pour détecter le Mac que vous avez utilisé le plus récemment et y acheminer les alertes des nœuds, consultez Présence de l’ordinateur actif.

Champs de présence (éléments affichés)

Les entrées de présence sont des objets structurés comportant des champs tels que :

• instanceId (facultatif, mais fortement recommandé) : identité stable du client (généralement connect.client.instanceId)
• host : nom d’hôte lisible
• ip : adresse IP déterminée au mieux
• version : chaîne de version du client
• deviceFamily / modelIdentifier : indications sur le matériel
• mode : ui, webchat, cli, backend, node, probe, test
• lastInputSeconds : nombre de secondes écoulées depuis la dernière saisie de l’utilisateur, si connu
• reason : chaîne libre fournie par le client ; le Gateway lui-même n’émet que self, connect et disconnect
• deviceId, roles, scopes : indications sur l’identité de l’appareil, son rôle et ses portées, issues de la négociation de connexion
• ts : horodatage de la dernière mise à jour (ms depuis l’époque Unix)

Producteurs (origine de la présence)

Les entrées de présence sont produites par plusieurs sources, puis fusionnées.

1) Entrée propre au Gateway

Le Gateway initialise toujours une entrée « self » au démarrage afin que les interfaces affichent l’hôte du Gateway, même avant la connexion du moindre client.

2) Connexion WebSocket

Chaque client WS commence par une requête connect. Une fois la négociation réussie, le Gateway insère ou met à jour une entrée de présence pour cette connexion.

Pourquoi les connexions éphémères du plan de contrôle ne sont pas affichées

Les commandes CLI, les clients RPC du backend et les sondes se connectent souvent brièvement. Afin d’éviter de conserver ces changements pendant toute la durée de vie de la présence, les clients en mode cli, backend ou probe ne sont pas transformés en entrées de présence. Les clients en mode test restent suivis, car les suites de tests les utilisent comme substituts de clients réels.

3) Balises system-event

Les clients peuvent envoyer périodiquement des balises plus détaillées au moyen de la méthode system-event. L’application Mac l’utilise pour communiquer le nom d’hôte, l’adresse IP et lastInputSeconds.

4) Connexions de nœuds (rôle : node)

Lorsqu’un nœud se connecte via le WebSocket du Gateway avec role: node, le Gateway insère ou met à jour une entrée de présence pour ce nœud (selon le même processus que pour les autres clients WS).

Règles de fusion et de déduplication (importance de instanceId)

Les entrées de présence sont stockées dans une seule table en mémoire, indexée sans distinction de casse par le premier identifiant disponible, dans cet ordre : identifiant d’un appareil appairé, connect.client.instanceId, puis, en dernier recours, identifiant propre à la connexion.

Les clients éphémères du plan de contrôle sont totalement exclus du suivi (voir ci-dessus) ; leurs identifiants de connexion ne deviennent donc jamais des clés. Pour tous les autres clients, le recours à l’identifiant de connexion implique qu’un client qui se reconnecte sans instanceId stable apparaît sous forme de ligne dupliquée.

Durée de vie et taille limitée

La présence est volontairement éphémère :

• Durée de vie : les entrées datant de plus de 5 minutes sont supprimées
• Nombre maximal d’entrées : 200 (les plus anciennes sont supprimées en premier)

Cela permet de maintenir la liste à jour et d’éviter une croissance illimitée de l’utilisation de la mémoire.

Limitation des connexions distantes/tunnels (adresses IP de bouclage)

Lorsqu’un client se connecte via un tunnel SSH ou une redirection de port locale, le Gateway peut voir l’adresse distante comme 127.0.0.1. Pour éviter d’enregistrer cette adresse de tunnel comme adresse IP du client, le traitement de la connexion omet entièrement ip pour les clients détectés comme locaux (bouclage), au lieu d’inscrire l’adresse de bouclage dans l’entrée.

Consommateurs

Page Appareils de l’interface de contrôle

La page Appareils associe system-presence aux enregistrements persistants d’appairage et de nœuds. Elle épingle en premier la balise propre au Gateway et utilise les identifiants d’appareil ou d’instance correspondants pour les métadonnées en direct de plateforme, de version, de modèle et d’ancienneté de la dernière saisie.

Onglet Instances de macOS

L’application macOS affiche la sortie de system-presence et applique un petit indicateur d’état (Actif/Inactif/Obsolète) selon l’ancienneté de la dernière mise à jour.

Conseils de débogage

• Pour afficher la liste brute, appelez system-presence sur le Gateway.
• Si vous voyez des doublons :
  • vérifiez que les clients envoient un client.instanceId stable lors de la négociation
  • vérifiez que les balises périodiques utilisent le même instanceId
  • vérifiez si l’entrée dérivée de la connexion ne contient pas instanceId (les doublons sont alors attendus)

Pages connexes