Agent Peer Lan

Connect two OpenClaw agents on the same LAN as peer collaborators. No VPN, no port forwarding over the internet, no third-party relay. Direct sessions_send between agents on a trusted local network. Use when: two OpenClaw agents on different LAN machines need to collaborate, delegate tasks, or share context. Triggers on: connect agents, peer agents, LAN agents, cross-machine agents, agent collaboration, local network peers.

Hypnotronic3@hypnotronic3

Install

openclaw skills install @hypnotronic3/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

text

Machine A (LAN IP)                    Machine B (LAN IP)
──────────────────────                 ──────────────────────
OpenClaw: :18789                       OpenClaw: :18789
     ↓                                       ↓
     └────── Direct LAN (trusted subnet) ──────┘
                    ↓
         sessions_send(sessionKey=...,
           gatewayUrl="http://<peer-ip>: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

Two machines on the same trusted LAN subnet
OpenClaw gateway running on both machines
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:

bash

openclaw gateway config

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

json

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

Then restart:

bash

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):

bash

# 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):

bash

# 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:

powershell

# 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:

bash

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

Windows:

powershell

ipconfig | findstr "IPv4"

macOS:

bash

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:

bash

curl http://<peer-lan-ip>: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:

markdown

# 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:

markdown

# 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:

json

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:

json

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:

json

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:

text

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:

text

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:

text

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:

Concern	Tailscale version	This LAN version
Gateway tokens	Shared in plaintext config files	Not stored in config; passed at runtime
Network exposure	Traffic routes through Tailscale servers	Stays on your LAN entirely
Third-party dependency	Requires Tailscale account and service	None
Internet required	Yes (for Tailscale coordination)	No
Attack surface	Tokens in files, gateway exposed via VPN	Gateway only on trusted subnet

Security best practices:

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

Troubleshooting

Problem	Solution
`Connection refused` from peer	Gateway not running or not bound to LAN IP
`Connection timed out`	Firewall blocking, or wrong subnet
`401 Unauthorized`	Need gateway auth token
`403 Forbidden`	Token is wrong or expired
Health check works but sessions_send fails	Check session key format and agent ID

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