Tracking Your OpenClaw Instances with Presence

I have spent too much time wondering if my backend nodes are actually connected or if a remote client is just hanging. It is frustrating when you cannot see the state of your distributed setup at a glance or verify which version of a tool is running where.

OpenClaw solves this with “presence.” It is a lightweight, best-effort view of the Gateway and everything connected to it. I use it to keep an eye on my macOS app instances and ensure my nodes are communicating correctly.

What You’ll Need

• An OpenClaw Gateway
• Connected clients (such as the macOS app, WebChat, or CLI)
• A WebSocket connection for real-time updates

Quick Start

You can see your active instances in about five minutes by following these steps:

1. Start the Gateway: The Gateway automatically creates a “self” entry at startup. You will see the gateway host in your UI before any clients even connect.
2. Connect a Client: Open the macOS app or a WebChat instance. When the WebSocket handshake succeeds, the Gateway adds a presence entry.
3. Send a Beacon: If you are using the macOS app, it sends system-event beacons. These provide extra details like your host name and lastInputSeconds.
4. View the List: Call the system-presence method against the Gateway to see the raw data, or check the Instances tab in the macOS app.

The Gateway keeps this list small and fresh. It prunes entries older than 5 minutes and caps the total list at 200 entries.

How Presence Merging Works

The Gateway stores entries in an in-memory map. To avoid seeing the same laptop or node listed multiple times, OpenClaw uses a presence key.

I recommend using a stable instanceId (found in connect.client.instanceId). This ID survives restarts and ensures your instance stays as a single row. These keys are case-insensitive. If a client reconnects without a stable ID, you might see duplicates.

Troubleshooting

Why is my CLI command not showing up?

The CLI often connects for short, one-off commands. To prevent the Instances list from getting crowded with temporary connections, the Gateway ignores any client where client.mode === "cli".

Why do I see duplicate rows for the same device?

This usually happens if the instanceId is missing or unstable. You should:

• Confirm your clients send a stable client.instanceId during the handshake.
• Ensure your periodic beacons use that same instanceId.
• Check if the connection entry is missing the ID entirely.

My IP address shows as 127.0.0.1

If you connect over an SSH tunnel or a local port forward, the Gateway sees a loopback address. To prevent overwriting a correct IP reported by the client, the Gateway ignores loopback remote addresses.

My instance disappeared

Entries are ephemeral. If an update is older than 5 minutes, the Gateway prunes it. If you have more than 200 instances, the oldest ones are dropped first to save memory.

For more help setting up your environment, check out the AI Setup Assistant.

What’s Next

• System Event Method Details
• Handshake Configuration
• Gateway Node Roles
• macOS App Interface Guide