Who's There? Understanding OpenClaw Presence

In the world of distributed AI agents, knowing who is online and what they are doing is crucial. Whether you're running a single Gateway on your laptop or orchestrating a fleet of nodes across different servers, visibility is key. Enter OpenClaw Presence.

Presence is a lightweight, real-time system within OpenClaw that gives you a "best-effort" view of your Gateway and all connected clients. It's the heartbeat of your agent ecosystem, answering the simple yet vital question: "Who is connected right now?"

What is Presence?

At its core, Presence is a dynamic registry maintained by the Gateway. It tracks:

• The Gateway itself (so you always see the host).
• Connected clients, such as the macOS app, WebChat, and other nodes.

This data is primarily used to populate the Instances tab in the OpenClaw macOS app, giving operators quick visibility into the state of their network.

How It Works

Presence isn't magic; it's a collection of signals merged into a coherent picture. Here's how the sausage is made:

1. The Producers

Presence entries come from several sources:

• Gateway Self-Entry: At startup, the Gateway seeds a "self" entry. This ensures that even with zero clients, you see the Gateway host in your list.
• WebSocket Connections: Every time a client connects via WebSocket, the Gateway creates or updates a presence entry.
• System-Event Beacons: Clients can send richer, periodic beacons. For example, the macOS app reports its host name, IP address, and even "last input seconds" (to show if a user is active).
• Node Connections: When a node connects with role: node, it's treated just like any other client, instantly appearing in your presence list.

Note: To keep things clean, one-off CLI commands (which connect briefly) are intentionally excluded from Presence to avoid spamming your list.

2. The Data

Each presence entry is a structured object containing useful metadata:

• instanceId: A stable identity for the client (crucial for deduplication).
• host & ip: The human-friendly hostname and best-effort IP address.
• mode: What kind of client is this? (ui, webchat, node, backend, etc.)
• lastInputSeconds: How long since the user interacted with this client?
• version: The client's software version.

3. Merging & Deduplication

The Gateway uses the instanceId as a stable key to merge updates. If a client disconnects and reconnects with the same instanceId, the existing entry is updated rather than duplicated. This is why having a stable identity is so important for long-running nodes and apps.

Ephemeral by Design

Presence is designed to be self-cleaning. It follows two main rules to prevent memory bloat:

1. TTL (Time To Live): Entries that haven't been updated in 5 minutes are automatically pruned.
2. Bounded Size: The list is capped at 200 entries. If it grows beyond that, the oldest entries are dropped.

This ensures that your view of the network remains fresh and relevant.

Why Should You Care?

For casual users, Presence is a nice-to-have status indicator. But for power users and developers, it's a powerful observability tool:

• Troubleshooting: Is your node actually connected? Check Presence. If it's not there, the WebSocket handshake likely failed.
• Activity Monitoring: Use lastInputSeconds to see if a specific workstation is active or idle.
• Duplicate Detection: Seeing the same node twice? You might have a configuration issue where the client isn't sending a stable instanceId.

Pro Tip: Debugging Presence

Want to see the raw data? You can query the Gateway directly. Use the system-presence command (or inspect the WebSocket frames if you're feeling adventurous) to see the full JSON objects for every connected entity. This can be invaluable when debugging connection issues or verifying that your custom client is reporting the correct metadata.

---

OpenClaw Presence is a small but mighty feature that brings transparency to your agent network. By understanding how it works, you can better monitor, debug, and manage your digital workforce.