openclaw/docs/concepts/presence.md

summary	read_when	title
How OpenClaw presence entries are produced, merged, and displayed	Debugging the Instances tab Investigating duplicate or stale instance rows Changing gateway WS connect or system-event beacons	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

When typing indicators are sent and how to tune them. Outbound streaming, chunking, and per-channel formatting. Gateway components and the WebSocket protocol that drives presence updates. The wire protocol for `connect`, `system-event`, and `system-presence`.