Naming System

ClawNexus assigns human-readable names to every discovered OpenClaw instance, making it simple to connect, monitor, and orchestrate agents without memorizing IP addresses or UUIDs.

How Names Are Assigned

When ClawNexus discovers an instance via any of the four discovery chains, it assigns a short alias based on the hostname reported by the instance. If the hostname is not available or conflicts with an existing entry, ClawNexus auto-generates a name from the pattern agent-XXXX.

You can rename any instance at any time:

clawnexus rename agent-a3f2 home
# [Registry] Renamed agent-a3f2 → home

.claw Name Format

All instance names follow the .claw convention internally. When you type home, ClawNexus resolves it as home.claw within the local namespace — similar to how .local works with mDNS.

home→home.claw @ 192.168.1.10:7473

raspi→raspi.claw @ 192.168.1.42:7473

office→office.claw @ 203.0.113.5:7473 (relay)

Registry File Format

The instance registry is stored at ~/.clawnexus/registry.json. It is a plain JSON file — human-readable and easy to version-control.

{
  "home": {
    "host": "192.168.1.10",
    "port": 7473,
    "status": "online",
    "discovered": "mdns",
    "lastSeen": "2026-03-31T10:24:00Z"
  },
  "raspi": {
    "host": "192.168.1.42",
    "port": 7473,
    "status": "online",
    "discovered": "udp",
    "lastSeen": "2026-03-31T10:24:01Z"
  },
  "office": {
    "host": "203.0.113.5",
    "port": 7473,
    "status": "relay",
    "discovered": "manual",
    "lastSeen": "2026-03-31T10:23:55Z"
  }
}

The discovered field records which chain found the instance (mdns, udp, scan, or manual). Instances added manually via clawnexus add are marked manual.

Name Persistence

Names survive daemon restarts. Once an instance is in the registry, its alias persists until explicitly removed with clawnexus remove <name>. If the same IP is re-discovered later, ClawNexus matches it to the existing alias rather than creating a duplicate entry.

clawnexus remove raspi
# [Registry] Removed: raspi

clawnexus list
# NAME     HOST           STATUS
# home     192.168.1.10   online
# office   203.0.113.5    relay

Using Names to Connect

Once named, instances are addressable by alias in all ClawNexus commands. For cross-network connectivity, ClawNexus automatically routes through the encrypted relay when direct IP access is unavailable.

clawnexus connect home
# [Connect] home.claw → 192.168.1.10:7473 (direct)

clawnexus connect office
# [Connect] office.claw → 203.0.113.5:7473 (relay)

← Discovery Chains Encrypted Relay →