Presence

OpenClaw “presence” is a lightweight, best-effort view of:

• the Gateway itself, and
• clients connected to the Gateway (mac app, WebChat, CLI, etc.)

Presence is used primarily to render the macOS app’s Instances tab and to provide quick operator visibility.

​

Presence fields (what shows up)

Presence entries are structured objects with fields like:

• instanceId (optional but strongly recommended): stable client identity (usually connect.client.instanceId)
• host: human-friendly host name
• ip: best-effort IP address
• version: client version string
• deviceFamily / modelIdentifier: hardware hints
• mode: ui, webchat, cli, backend, node, probe, test
• lastInputSeconds: seconds since last user input, if known
• reason: free-form client-supplied string; the Gateway itself only emits self, connect, and disconnect
• deviceId, roles, scopes: device identity and role/scope hints from the connect handshake
• ts: last update timestamp (ms since epoch)

​

Producers (where presence comes from)

Presence entries are produced by multiple sources and merged.

​

1) Gateway self entry

The Gateway always seeds a “self” entry at startup so UIs show the gateway host even before any clients connect.

​

2) WebSocket connect

Every WS client begins with a connect request. On successful handshake the Gateway upserts a presence entry for that connection.

​

Why one-off CLI commands do not show up

The CLI often connects for short, one-off commands. To avoid spamming the Instances list, client.mode === "cli" is not turned into a presence entry.

​

3) system-event beacons

Clients can send richer periodic beacons via the system-event method. The mac app uses this to report host name, IP, and lastInputSeconds.

​

4) Node connects (role: node)

When a node connects over the Gateway WebSocket with role: node, the Gateway upserts a presence entry for that node (same flow as other WS clients).

​

Merge + dedupe rules (why instanceId matters)

Presence entries are stored in a single in-memory map, keyed case-insensitively by the first available of, in order: a paired device id, connect.client.instanceId, or the per-connection id as a last resort. CLI clients are excluded from tracking entirely (see above), so their connection id never becomes a key. For every other client, the connection id fallback means a client that reconnects without a stable instanceId shows up as a duplicate row.

​

TTL and bounded size

Presence is intentionally ephemeral:

• TTL: entries older than 5 minutes are pruned
• Max entries: 200 (oldest dropped first)

This keeps the list fresh and avoids unbounded memory growth.

​

Remote/tunnel caveat (loopback IPs)

When a client connects over an SSH tunnel / local port forward, the Gateway may see the remote address as 127.0.0.1. To avoid recording that tunnel address as the client’s IP, connect handling omits ip entirely for detected-local (loopback) clients rather than writing the loopback address into the entry.

​

Consumers

​

macOS Instances tab

The macOS app renders the output of system-presence and applies a small status indicator (Active/Idle/Stale) based on the age of the last update.

​

Debugging tips

• To see the raw list, call system-presence against the Gateway.
• If you see duplicates:
  • confirm clients send a stable client.instanceId in the handshake
  • confirm periodic beacons use the same instanceId
  • check whether the connection-derived entry is missing instanceId (duplicates are expected)

​

Related