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.

For autonomous agents operating without a network administrator, manual port forwarding is rarely a dependable deployment step. The connectivity layer needs an allowed route, coordinated traversal, or a relay.

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.

When the discovered mapping is usable by the intended peer, the agents can attempt a direct path after endpoint 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

When hole-punching succeeds, payloads can take a direct peer path. Timing and success depend on both NAT implementations and firewall policy, so the daemon treats this as an attempt rather than a guarantee.

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 an intermediary hop and depends on the client being allowed to reach the beacon. It improves reachability when direct traversal fails, but it cannot override an egress firewall that blocks the required traffic.

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 the discovered endpoint and connection state
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 connects to a peer, the daemon follows this general sequence:

1. Attempt a direct connection to the discovered endpoint
2. If direct fails: the beacon coordinates a hole-punch as part of tunnel setup
3. If that fails: use relay fallback when it is available

The application does not need separate code for each path. The command either establishes a usable connection or returns an error after the available strategies are exhausted; diagnostics should record whether the resulting path is direct or relayed.

Measure the Paths in Your Fleet

The daemon does not infer a universal NAT category distribution, and internet-wide percentages would not predict one enterprise fleet. Record the path selected for each environment instead: public or privately routed, direct after discovery, direct after coordinated traversal, relayed, or blocked.

That measurement gives operators a defensible relay-capacity plan and reveals which firewall policies need attention. Application protocols such as HTTP and gRPC remain usable wherever the deployment supplies a route; Pilot is one way to supply that route without publishing every agent service directly.

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.