OpenClaw Presence Overview

OpenClaw's "presence" feature offers a lightweight, best-effort snapshot of:

the Gateway process itself, and
user-visible clients linked to the Gateway (mac app, WebChat, nodes, and similar)

Live connection details appear on the Devices page in the Control UI, located under Settings → Devices, as well as in the Instances tab of the macOS app.

This section focuses on the Gateway's client roster. For identifying the Mac you last used and directing node alerts to it, refer to Active computer presence.

Presence fields (what shows up)

Presence entries are structured objects containing fields such as:

instanceId (optional but highly advised): a stable client identifier (typically connect.client.instanceId)
host: a readable host name
ip: a best-effort IP address
version: the client's version string
deviceFamily / modelIdentifier: hardware-related hints
timeZone: the client-reported IANA time zone (for example Europe/Vienna); browsers supply this during connection, and it remains relevant when the connecting IP is loopback, tunneled, or behind CGNAT
mode: ui, webchat, cli, backend, node, probe, test
lastInputSeconds: seconds elapsed since the last user input, when available
reason: an arbitrary client-supplied string; the Gateway itself only sends self, connect, and disconnect
deviceId, roles, scopes: device identity and role/scope hints derived from the connect handshake
ts: the timestamp of the last update (milliseconds since epoch)

Producers (where presence comes from)

Presence entries come from several sources and are merged together.

1) Gateway self entry

At startup, the Gateway always creates a "self" entry, ensuring UIs display the gateway host even before any client connects.

2) WebSocket connect

Every WebSocket client initiates with a connect request. Once the handshake succeeds, the Gateway upserts a presence entry for that connection.

Why ephemeral control-plane connections do not show up

CLI commands, backend RPC clients, and probes often establish short-lived connections. To prevent this churn from lingering for the full presence TTL, clients operating in cli, backend, or probe mode are not converted into presence entries. Test-mode clients remain tracked, since test suites rely on them as substitutes for real clients.

3) `system-event` beacons

Clients can send more detailed periodic beacons through the system-event method. The mac app leverages this to report host name, IP, version, and liveness details. Physical input activity is excluded from this generic beacon; that responsibility belongs to the purpose-specific native node event described in Active computer presence. The Mac labels these beacons with system-presence-clear-last-input; current Gateways use this backward-compatible marker to discard any input recency previously stored from an older app. The beacon also includes a fixed 30-day value, so older Gateways that ignore the marker overwrite exact recency rather than preserving it. No new activity is sampled for this compatibility value.

4) Node connects (role: node)

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

Merge + dedupe rules (why `instanceId` matters)

Presence entries reside 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 final fallback.

Ephemeral control-plane clients are completely excluded from tracking (as noted above), so their connection ids never become keys. For all other clients, the connection id fallback means a client that reconnects without a stable instanceId appears as a duplicate row.

TTL and bounded size

Presence is deliberately short-lived:

TTL: entries older than 5 minutes get pruned
Max entries: 200 (oldest removed first)

This approach keeps the list current and prevents unbounded memory consumption.

Remote/tunnel caveat (loopback IPs)

When a client connects through an SSH tunnel or local port forward, the Gateway might observe 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

Control UI Devices page

The Devices page combines system-presence with durable pairing and node records. It pins the Gateway self beacon at the top and uses matching device or instance ids for live platform, version, model, and input-recency metadata.

macOS Instances tab

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

Debugging tips

To view the raw list, invoke system-presence against the Gateway.
If duplicates appear:
- verify clients send a stable client.instanceId during the handshake
- confirm periodic beacons use the same instanceId
- check whether the connection-derived entry is missing instanceId (duplicates are expected)

Active computer presence, The way physical Mac input picks an active node and directs connection alerts.
Typing indicators, The conditions under which typing indicators are transmitted, plus guidance for adjusting them.
Streaming and chunking, Handling of outbound streams, chunk sizes, and formatting that varies by channel.
Gateway architecture, The building blocks of the gateway and the WebSocket protocol responsible for presence updates.
Gateway protocol, The on-the-wire format used for connect, system-event, and system-presence.