Agent Peer via Tailscale

Connect two OpenClaw agents running on different machines as peer collaborators via Tailscale VPN. Enables direct sessions_send communication between agents on separate hosts with no public IP, no port forwarding, and no middle server. Use when: (1) two OpenClaw agents on different machines need to collaborate on projects, (2) mentor/peer agent wants to send tips and insights to another agent in real-time, (3) setting up a peer network of OpenClaw agents, (4) two agents need to share session context or delegate work to each other. Triggers on: connect two agents, peer agents, Tailscale VPN, cross-machine agents, agent collaboration VPN, OpenClaw peer network.

Two OpenClaw agents on different machines — connected as peers over Tailscale VPN. No public IP, no port forwarding, no relay server. Direct sessions_send between them as if on the same LAN.

What You Get

text

Machine A (You)                         Machine B (Friend)
──────────────                          ───────────────
OpenClaw: :8080                         OpenClaw: :8080
Tailscale: 100.x.x.x                    Tailscale: 100.x.x.x
     ↓                                          ↓
     └────────── Tailscale VPN (encrypted) ──────┘
                    ↓
         sessions_send(sessionKey=...,
           gatewayUrl="http://100.x.x.x:8080")

Both agents can send messages, session context, tips, and task delegations directly to each other.

Prerequisites

1. OpenClaw gateway running on both machines (local gateway, not node mode)
2. Tailscale installed on both machines (free account at tailscale.com)
3. Both machines on the same Tailscale network (one creates the network, shares auth key)
4. Gateway bound to Tailscale interface (not localhost only)

Step 1 — Install and Configure Tailscale

On Machine A (the host)

bash

# Download and install Tailscale
winget install Tailscale.Tailscale   # Windows
# or: brew install tailscale         # macOS
# or: curl -fsSL https://tailscale.com/install.sh | sh  # Linux

# Start Tailscale and authenticate
tailscale up --accept-routes

# Note the Tailscale IP (write this down for Machine B)
tailscale ip -4

On Machine B (join the network)

bash

# Install Tailscale the same way
# Then join using the auth key from Machine A's Tailscale admin console
tailscale up --accept-routes --authkey=<authkey-from-machine-a>

# Note your Tailscale IP
tailscale ip -4

Both machines now have IPs like 100.x.x.x on a private encrypted network.

Step 2 — Configure OpenClaw Gateway for Tailscale

By default, OpenClaw binds to localhost. You need it to bind to all interfaces so the peer can reach it over Tailscale.

Check your gateway config:

bash

openclaw gateway status

Set gateway.bind to 0.0.0.0 (all interfaces) or specifically the Tailscale IP:

json

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

Apply and restart:

text

openclaw gateway restart

Security note: Binding to 0.0.0.0 exposes your gateway on all network interfaces. Tailscale traffic is encrypted peer-to-peer, but make sure you have a strong gateway token/password set. Consider gateway.auth to require token authentication.

Step 3 — Exchange Gateway URLs

Once both gateways are reachable over Tailscale, exchange the peer gateway URLs:

Machine A tells Machine B:

text

Gateway URL: http://<Machine-A-Tailscale-IP>:8080
Gateway token: <your-gateway-token>

Machine B tells Machine A:

text

Gateway URL: http://<Machine-B-Tailscale-IP>:8080
Gateway token: <their-gateway-token>

Step 4 — Create Peer Config File

On each machine, create a peer configuration at peer-agent/peer-config.md:

Your config (Machine A):

markdown

# My Peer Configuration

My Tailscale IP: <your-tailscale-ip>
My Gateway URL: http://<your-tailscale-ip>:8080
My Gateway Token: <your-token>

# Peer (Machine B)
Peer Name: <friend's-name>
Peer Tailscale IP: <their-tailscale-ip>
Peer Gateway URL: http://<their-tailscale-ip>:8080
Peer Gateway Token: <their-token>

# How to reach my agent
# Use sessions_send with the gatewayUrl pointing to my gateway above.
# My agentId for direct targeting: <your-agent-id>

Step 5 — Test the Connection

From Machine A, test reaching Machine B's gateway:

bash

# Ping the peer's gateway over Tailscale
curl http://<peer-tailscale-ip>:8080/health --connect-timeout 5

You should get a health response. If not, check that the peer's gateway is bound to 0.0.0.0 and their firewall allows incoming on port 8080 from the Tailscale network.

Step 6 — Send Messages Between Agents

Once connectivity is confirmed, use sessions_send with gatewayUrl pointing to the peer:

json

sessions_send(
  sessionKey="<peer-session-key>",
  agentId="<peer-agent-id>",
  message="Hey, need your take on something — I'm stuck on...",
  gatewayUrl="http://<peer-tailscale-ip>:8080",
  gatewayToken="<peer-gateway-token>"
)

Daily Collaboration Patterns

Pattern 1: Morning Handoff

Each morning, each agent sends the other a brief status update:

text

sessions_send(
  message="Morning! Here's where I'm at: [project status]. Blockers: [if any]. 
   Any insights on [specific problem]?",
  gatewayUrl="http://<peer-ip>:8080",
  gatewayToken="<peer-token>"
)

Pattern 2: Quick Insight

When one agent learns something useful:

text

"Something I learned today that might help you: [insight]"

Pattern 3: Code/Review Request

text

"Can you review my approach to [task]? Here it is: [description]. 
 Is there a better pattern I'm missing?"

Pattern 4: Delegation

text

"I've got a task that's more your specialty — want to delegate this to you? [task details].
 Let me know if you have capacity."

Reference Files

• references/tailscale-setup.md — detailed Tailscale install, network setup, auth key sharing
• references/peer-communication.md — message format, frequency, session management
• references/troubleshooting.md — NAT, firewall, connection issues
• scripts/peer_config.py — interactive config generator for the peer setup

Security Notes

• Tailscale is encrypted end-to-end — no one on the internet can see the traffic
• Gateway token is required — don't share your gateway token in plain text over an unsecured channel; use a private message or password manager
• Only share with people you trust — the peer can send messages that execute as your agent
• Revoke auth keys from the Tailscale admin console if the friendship ends
• Consider gateway.access — restrict which sessions can be targeted from peers