Agent Peer Lan

Agent Peer via LAN

Two OpenClaw agents on the same trusted local network — connected directly. No VPN, no public IP exposure, no relay server. sessions_send between them as if they're on the same machine.

What You Get

Machine A (LAN IP)                    Machine B (LAN IP)
──────────────────────                 ──────────────────────
OpenClaw: :18789                       OpenClaw: :18789
     ↓                                       ↓
     └────── Direct LAN (trusted subnet) ──────┘
                    ↓
         sessions_send(sessionKey=...,
           gatewayUrl="http://:18789")

Both agents can send messages, share context, and delegate work directly — staying entirely on the local network.

Why This Instead of Tailscale?

• No third-party service — your traffic never leaves your LAN
• No gateway tokens shared over the internet — the biggest security issue with the Tailscale version
• No VPN dependency — works even if your internet is down
• Lower latency — direct LAN connection, no VPN overhead
• Simpler setup — just configure bind addresses and test connectivity

Prerequisites

1. Two machines on the same trusted LAN subnet
2. OpenClaw gateway running on both machines
3. Both gateways reachable from each other on the LAN

Step 1 — Configure Gateway Bind Address

By default, OpenClaw binds to localhost (127.0.0.1), which means only the local machine can reach it. To allow the other machine on the LAN, bind to the LAN interface.

On each machine, update the gateway config:

openclaw gateway config

Set gateway.bind to 0.0.0.0 (all interfaces) or your specific LAN IP:

{
  "gateway": {
    "bind": "0.0.0.0",
    "port": 18789
  }
}

Then restart:

openclaw gateway restart

Important: Firewall

If your machine runs a firewall, allow inbound connections on the gateway port from the trusted subnet only:

Linux (ufw):

# Replace 192.168.1.0/24 with your trusted subnet
sudo ufw allow from 192.168.1.0/24 to any port 18789

Linux (iptables):

# Replace 192.168.1.0/24 with your trusted subnet
sudo iptables -A INPUT -s 192.168.1.0/24 -p tcp --dport 18789 -j ACCEPT

Windows:

# Replace 192.168.1.0/24 with your trusted subnet
New-NetFirewallRule -DisplayName "OpenClaw Gateway" -Direction Inbound -LocalPort 18789 -Protocol TCP -Action Allow -RemoteAddress 192.168.1.0/24

Step 2 — Discover LAN IPs

On each machine, find its LAN IP:

Linux:

ip addr show | grep "inet " | grep -v 127.0.0.1

Windows:

ipconfig | findstr "IPv4"

macOS:

ifconfig | grep "inet " | grep -v 127.0.0.1

Note down the IP on the trusted subnet for each machine (e.g., 192.168.1.10 and 192.168.1.20).

Step 3 — Test Connectivity

From each machine, test that the other's gateway is reachable:

curl http://:18789/health --connect-timeout 5

You should get {"ok":true,"status":"live"}. If not:

• Check the gateway is running on the peer (openclaw gateway status)
• Check the gateway is bound to 0.0.0.0 or the LAN IP (not just localhost)
• Check firewall rules allow the port from the trusted subnet
• Check you're on the same subnet (can you ping the other machine?)

Step 4 — Create Peer Configuration

On each machine, create peer-agent/peer-config.md in the OpenClaw workspace:

Machine A config:

# Peer Agent Configuration

## My Details
- **Name:** ServerAgent
- **Machine:** linux-server
- **LAN IP:** 192.168.1.10
- **Gateway URL:** http://192.168.1.10:18789
- **Agent ID:** main

## My Peer
- **Name:** PCAgent
- **Machine:** desktop-pc
- **LAN IP:** 192.168.1.20
- **Gateway URL:** http://192.168.1.20:18789
- **Agent ID:** main

Machine B config:

# Peer Agent Configuration

## My Details
- **Name:** PCAgent
- **Machine:** desktop-pc
- **LAN IP:** 192.168.1.20
- **Gateway URL:** http://192.168.1.20:18789
- **Agent ID:** main

## My Peer
- **Name:** ServerAgent
- **Machine:** linux-server
- **LAN IP:** 192.168.1.10
- **Gateway URL:** http://192.168.1.10:18789
- **Agent ID:** main

Do NOT store gateway auth tokens in this file. Pass them at runtime or store them in environment variables.

Step 5 — Send Messages Between Agents

Use sessions_send with the peer's gateway URL:

sessions_send(
  sessionKey="agent:main:dashboard:...",
  agentId="main",
  message="Hey, can you check the server disk usage?",
  gatewayUrl="http://192.168.1.10:18789"
)

If the peer gateway requires auth, include the token:

sessions_send(
  sessionKey="agent:main:dashboard:...",
  agentId="main",
  message="Hey, can you check the server disk usage?",
  gatewayUrl="http://192.168.1.10:18789",
  gatewayToken="peer-gateway-token-here"
)

Step 6 — Spawn Tasks on the Peer

You can also spawn isolated work on the peer using sessions_spawn with the peer's gateway:

sessions_spawn(
  task="Check disk usage on the server and report if any disk is above 80%",
  taskName="disk-check",
  mode="run",
  runtime="subagent",
  gatewayUrl="http://192.168.1.10:18789",
  gatewayToken="peer-gateway-token-here"
)

Collaboration Patterns

Pattern 1: Morning Handoff

Each agent sends the other a status update:

sessions_send(
  message="Server healthy, disk at 68%, all services running. No new alerts.",
  gatewayUrl="http://192.168.1.10:18789"
)

Pattern 2: Task Delegation

Delegate work to the agent best positioned to handle it:

sessions_send(
  message="Can you check the smart home integration? Some devices seem offline.",
  gatewayUrl="http://192.168.1.10:18789"
)

Pattern 3: Cross-Verification

Two agents verify each other's findings:

sessions_send(
  message="I'm seeing high CPU on your end. Can you confirm and check which process is causing it?",
  gatewayUrl="http://192.168.1.10:18789"
)

Security Model

What this skill does differently from the Tailscale version:

Security best practices:

1. Bind to trusted subnet only — use 0.0.0.0 only if your LAN is firewalled; better to bind to the specific LAN IP
2. Firewall the gateway port — only allow connections from trusted subnet IPs
3. Never store gateway tokens in config files — pass them as environment variables or at runtime
4. Use a separate subnet for trusted devices — don't expose the gateway on the IoT subnet
5. Rotate tokens if compromised — openclaw gateway config to change the auth token

Troubleshooting

Reference Files

• references/network-setup.md — detailed network configuration for common setups
• references/troubleshooting.md — connectivity, firewall, and auth troubleshooting
• scripts/peer_config.py — interactive config generator