Neura Market Logo

OpenClaw Presence: How Client Roster Entries Are Produced and Displayed

Learn how OpenClaw's presence feature produces, merges, and displays live connection metadata for the Gateway and user-visible clients. This page covers presence fields and where they appear.

Read this when

  • Debugging live status on the Control UI Devices page
  • Investigating duplicate or stale instance rows
  • Changing gateway WS connect or system-event beacons

OpenClaw's "presence" feature provides a lightweight, best-effort overview of:

  • the Gateway itself, and
  • user-visible clients connected to the Gateway (mac app, WebChat, nodes, etc.)

Live connection metadata is rendered through presence on the Control UI Devices page (located under Settings → Devices) and within the Instances tab of the macOS app.

This page describes the Gateway's client roster. To identify your most recently used Mac and direct 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 strongly recommended): a stable client identifier (typically connect.client.instanceId)
  • host: a human-readable host name
  • ip: a best-effort IP address
  • version: the client version string
  • deviceFamily / modelIdentifier: hardware hints
  • mode: ui, webchat, cli, backend, node, probe, test
  • lastInputSeconds: seconds elapsed since the last user input, if known
  • reason: a free-form string supplied by the client; the Gateway itself only emits self, connect, and disconnect
  • deviceId, roles, scopes: device identity and role or scope hints from the connect handshake
  • ts: the timestamp of the last update (milliseconds since epoch)

Producers (where presence comes from)

Multiple sources generate presence entries, which are then merged.

1) Gateway self entry

At startup, the Gateway always seeds a "self" entry so that UIs display the gateway host even before any clients have connected.

2) WebSocket connect

Every WebSocket client begins 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 connect only briefly. To prevent this churn from persisting for the full presence TTL, clients operating in cli, backend, or probe mode are not converted into presence entries. Test-mode clients remain tracked because test suites rely on them as substitutes for real clients.

3) system-event beacons

Clients can send richer periodic beacons through the system-event method. The macOS app uses this to report host name, IP, version, and liveness metadata. Physical input activity is not included in this generic beacon; the purpose-specific native node event described in Active computer presence handles that. The Mac tags these beacons with system-presence-clear-last-input; current Gateways use that backward-compatible marker to clear any input recency retained from an older app. The beacon also carries a fixed 30-day value so that older Gateways, which ignore the tag, overwrite exact recency instead of preserving it. No new activity is sampled for this compatibility value.

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 (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 last resort.

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

TTL and bounded size

Presence is intentionally short-lived:

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

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

Remote/tunnel caveat (loopback IPs)

When a client connects through an SSH tunnel or 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 clients detected as local (loopback) 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 first 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 the age of the last update.

Debugging tips

  • To view the raw list, call system-presence against the Gateway.
  • If duplicates appear:
    • ensure 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, How physical Mac input selects an active node and routes connection alerts.

  • Typing indicators, When typing indicators are sent and how to adjust them.

  • Streaming and chunking, Outgoing data streams, message fragmentation, and formatting applied to individual channels.

  • Gateway architecture, The building blocks of the gateway and the WebSocket mechanism responsible for delivering presence changes.

  • Gateway protocol, The communication protocol used by connect, system-event, and system-presence over the network.