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:

• text

  Copy

  instanceId
  (optional but strongly recommended): stable client identity (usually
  text

  Copy

  connect.client.instanceId
  )
• text

  Copy

  host
  : human‑friendly host name
• text

  Copy

  ip
  : best‑effort IP address
• text

  Copy

  version
  : client version string
• text

  Copy

  deviceFamily
  /
  text

  Copy

  modelIdentifier
  : hardware hints
• text

  Copy

  mode
  :
  text

  Copy

  ui
  ,
  text

  Copy

  webchat
  ,
  text

  Copy

  cli
  ,
  text

  Copy

  backend
  ,
  text

  Copy

  probe
  ,
  text

  Copy

  test
  ,
  text

  Copy

  node
  , ...
• text

  Copy

  lastInputSeconds
  : “seconds since last user input” (if known)
• text

  Copy

  reason
  :
  text

  Copy

  self
  ,
  text

  Copy

  connect
  ,
  text

  Copy

  node-connected
  ,
  text

  Copy

  periodic
  , ...
• text

  Copy

  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

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,

is not turned into a presence entry.

3)

text

Copy

system-event

beacons

Clients can send richer periodic beacons via the

method. The mac app uses this to report host name, IP, and .

4) Node connects (role: node)

When a node connects over the Gateway WebSocket with

, the Gateway upserts a presence entry for that node (same flow as other WS clients).

Merge + dedupe rules (why

text

Copy

instanceId

matters)

Presence entries are stored in a single in‑memory map:

• Entries are keyed by a presence key.
• The best key is a stable
  text

  Copy

  instanceId
  (from
  text

  Copy

  connect.client.instanceId
  ) that survives restarts.
• Keys are case‑insensitive.

If a client reconnects without a stable

, it may show 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

. To avoid overwriting a good client‑reported IP, loopback remote addresses are ignored.

Consumers

macOS Instances tab

The macOS app renders the output of

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
  text

  Copy

  system-presence
  against the Gateway.
• If you see duplicates:
  • confirm clients send a stable
    text

    Copy

    client.instanceId
    in the handshake
  • confirm periodic beacons use the same
    text

    Copy

    instanceId
  • check whether the connection‑derived entry is missing
    text

    Copy

    instanceId
    (duplicates are expected)

Related

• Typing indicators
• Streaming and chunking