Aanwezigheid¶

OpenClaw “presence” is een lichtgewicht, best‑effort overzicht van:

• de Gateway zelf, en
• clients die met de Gateway zijn verbonden (mac-app, WebChat, CLI, enz.)

Presence wordt voornamelijk gebruikt om het tabblad Instances van de macOS‑app te renderen en om snelle zichtbaarheid voor operators te bieden.

Presence-velden (wat wordt weergegeven)¶

Presencevermeldingen zijn gestructureerde objecten met velden zoals:

• instanceId (optioneel maar sterk aanbevolen): stabiele clientidentiteit (meestal connect.client.instanceId)
• host: mensvriendelijke hostnaam
• ip: best‑effort IP-adres
• version: clientversiestring
• deviceFamily / modelIdentifier: hardware-indicaties
• mode: ui, webchat, cli, backend, probe, test, node, ...
• lastInputSeconds: “seconden sinds laatste gebruikersinvoer” (indien bekend)
• reason: self, connect, node-connected, periodic, ...
• ts: tijdstempel van laatste update (ms sinds epoch)

Producenten (waar presence vandaan komt)¶

Presencevermeldingen worden door meerdere bronnen geproduceerd en samengevoegd.

1. Gateway-eigen vermelding¶

De Gateway initialiseert bij het opstarten altijd een “self”-vermelding, zodat UI’s de gateway-host tonen, zelfs voordat clients verbinding maken.

2. WebSocket-connectie¶

Elke WS-client begint met een connect-verzoek. Bij een succesvolle handshake voegt de Gateway een presencevermelding toe of werkt deze bij voor die verbinding.

Waarom eenmalige CLI-opdrachten niet verschijnen¶

De CLI maakt vaak verbinding voor korte, eenmalige opdrachten. Om te voorkomen dat de Instances-lijst wordt gespamd, wordt client.mode === "cli" niet omgezet in een presencevermelding.

3. system-event-beacons¶

Clients kunnen rijkere periodieke beacons sturen via de methode system-event. De mac-app gebruikt dit om hostnaam, IP en lastInputSeconds te rapporteren.

4. Node-verbindingen (rol: node)¶

Wanneer een node verbinding maakt via de Gateway WebSocket met role: node, voegt de Gateway een presencevermelding toe of werkt deze bij voor die node (zelfde stroom als andere WS-clients).

Samenvoegen + deduplicatie (waarom instanceId ertoe doet)¶

Presencevermeldingen worden opgeslagen in één in‑memory map:

• Vermeldingen worden gesleuteld op een presence-sleutel.
• De beste sleutel is een stabiele instanceId (van connect.client.instanceId) die herstarts overleeft.
• Sleutels zijn niet hoofdlettergevoelig.

Als een client opnieuw verbindt zonder een stabiele instanceId, kan deze als een dubbele rij verschijnen.

TTL en begrensde grootte¶

Presence is bewust vluchtig:

• TTL: vermeldingen ouder dan 5 minuten worden opgeschoond
• Max. vermeldingen: 200 (oudste worden eerst verwijderd)

Dit houdt de lijst actueel en voorkomt onbeperkte geheugen­groei.

Remote/tunnel‑kanttekening (loopback-IP’s)¶

Wanneer een client verbinding maakt via een SSH-tunnel / lokale portforward, kan de Gateway het externe adres zien als 127.0.0.1. Om te voorkomen dat een goed door de client gerapporteerd IP wordt overschreven, worden loopback-externe adressen genegeerd.

Consumenten¶

macOS-tabblad Instances¶

De macOS‑app rendert de uitvoer van system-presence en past een kleine statusindicator toe (Actief/Idle/Verouderd) op basis van de leeftijd van de laatste update.

Debuggingtips¶

• Om de ruwe lijst te zien, roep system-presence aan tegen de Gateway.
• Als je duplicaten ziet:
• bevestig dat clients een stabiele client.instanceId in de handshake sturen
• bevestig dat periodieke beacons dezelfde instanceId gebruiken
• controleer of de van de verbinding afgeleide vermelding instanceId mist (duplicaten zijn dan te verwachten)