OpenClaw Agents Behind NAT: Zero Config

Why NAT Breaks Agent Communication

Network Address Translation (NAT) sits between most devices and the internet. A home router might have one public IP (e.g., 203.0.113.5) shared by 20 devices with private IPs (192.168.1.x). When a device sends an outbound packet, the router creates a mapping: private IP + port → public IP + translated port. Responses to that translated port are forwarded back to the private device.

The problem: unsolicited inbound traffic has no mapping. If Agent B tries to send a packet to Agent A's public IP, the router does not know which private device should receive it. The packet is dropped silently.

This is why 88% of real-world networks cannot accept inbound connections without explicit port forwarding or a relay. For autonomous agents operating without human administrators, manual port forwarding is not an option. The agent needs to traverse NAT automatically.

Three-Tier Traversal

Pilot Protocol uses a three-tier strategy that handles every NAT type automatically. The agent does not choose a strategy -- the daemon tries a direct connection first (using its STUN-discovered endpoint), then escalates to beacon-coordinated hole-punching, and finally to relay. It does not classify the NAT type up front; it simply retries down the ladder until one tier works.

Tier 1: Direct (Full Cone NAT)

Full Cone NAT creates a mapping that any external host can use. Once the agent sends a STUN request, the resulting public endpoint works for all peers. This is the simplest case and requires no additional coordination.

Approximately 35% of the OpenClaw agents had Full Cone NAT. These agents connected directly to peers after STUN discovery.

Tier 2: Hole-Punching (Restricted/Port-Restricted NAT)

Restricted NAT only forwards packets from hosts the device has previously sent to. Port-Restricted NAT adds the constraint that the source port must also match. To connect two agents behind these NAT types, both need to send packets to each other simultaneously -- creating mappings in both routers that allow the return traffic through.

Pilot Protocol's beacon server coordinates this:

1. Agent A sends a MsgPunchRequest to the beacon: "I want to connect to Agent B"
2. The beacon sends a MsgPunchCommand to both agents: "Send a packet to each other's STUN-discovered endpoint NOW"
3. Both agents send simultaneous UDP packets to each other's public endpoints
4. Both routers see outbound traffic and create mappings
5. The next packets arrive and match the mappings -- connection established

Hole-punching typically succeeds within 1-2 seconds and produces a direct peer-to-peer connection with no relay overhead. Approximately 40% of OpenClaw agents used hole-punching.

Tier 3: Relay (Symmetric NAT)

Symmetric NAT assigns a different external port for every destination. STUN discovers one port, but that port only works for the STUN server. Packets to any other destination get a different port. Hole-punching cannot work because neither agent can predict the other's external port.

For Symmetric NAT, traffic is relayed through the beacon server:

# Relay message format
# [0x05][senderNodeID(4)][destNodeID(4)][payload...]

# Agent A sends to beacon, beacon forwards to Agent B
# Agent B's response goes through beacon back to Agent A

Relay adds latency (two extra hops through the beacon) but works through any NAT type, any firewall, any network configuration. Approximately 12% of OpenClaw agents required relay. The remaining 13% were on networks with no NAT (cloud VMs with public IPs using the -endpoint flag).

From the Agent's Perspective

Here is what the OpenClaw agent sees. No NAT configuration, no networking knowledge required:

# Start daemon (NAT traversal happens automatically)
pilot-daemon

# Check status -- NAT type is detected automatically
pilotctl daemon status --json
# {"address":"1:0001.0A3F.7B21",
#  "endpoint":"203.0.113.5:45782","encrypted":true,...}

# Connect to a peer (traversal strategy chosen automatically)
pilotctl send 1:0001.0B22.4E19 1002 --data "Hello from behind NAT"
# Works. The agent doesn't know or care how.

The pilotctl status output shows the STUN-discovered endpoint, but the agent does not need to act on this information. It is diagnostic data for humans. The daemon handles everything internally.

When the agent calls pilotctl send to a peer, the daemon's DialConnection function tries the following sequence:

1. 3 direct connection attempts (works for Full Cone NAT and public IPs)
2. If direct fails: the beacon coordinates a hole-punch as part of tunnel setup
3. If that fails: switch to relay mode automatically (4 relay attempts; 7 total dial attempts)

The agent never sees this retry logic. The send command either succeeds or returns an error after all strategies are exhausted. In practice, connection succeeds over 99% of the time -- relay is the universal fallback.

Typical NAT Distribution

The daemon does not classify NAT types itself, so it can't report a live breakdown. But published NAT research gives a representative picture of what networks in the wild look like (individual surveys vary):

By a representative distribution like this, only about half of agents can accept unsolicited inbound connections (public IP + Full Cone). The rest are invisible to any protocol that requires inbound connectivity -- including standard HTTP APIs, gRPC servers, and A2A Agent Cards.

This is a core reason autonomous agents reach for Pilot Protocol: a large share of them cannot serve HTTP from behind their NAT at all, so an HTTP-based agent protocol simply isn't an option for them.

IPv6 and the Future

IPv6 eliminates NAT for devices with globally-routable addresses. Some of the OpenClaw agents ran on IPv6 networks where every device has a public address. For these agents, STUN still runs (to discover the external address) but hole-punching and relay are never needed.

Pilot Protocol's beacon supports both IPv4 and IPv6 STUN. The daemon auto-detects the network stack and uses the appropriate protocol. As IPv6 adoption grows, the proportion of agents requiring hole-punching or relay will decrease, but the traversal stack remains available as a fallback for the IPv4 networks that will persist for years.

For the complete NAT traversal specification, including the packet formats, timing parameters, and keepalive intervals, see the NAT traversal deep dive.