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...

Security Scan

The skill's files and instructions are coherent with its stated purpose (connecting two OpenClaw agents over Tailscale), but there are a few metadata and sensitive-data handling details you should be aware of before using it.

Purpose & Capability

The skill's behavior (use of Tailscale and OpenClaw gateway settings) matches the description. One minor inconsistency: registry metadata lists no required binaries/env but the instructions and included script clearly expect the 'tailscale' binary and the 'openclaw' gateway CLI/config to be present.

Instruction Scope

SKILL.md stays within peer-networking purpose but explicitly instructs binding the gateway to 0.0.0.0 and exchanging gateway tokens/auth keys. The included docs/scripts guide storing gateway tokens and peer tokens in plaintext files (peer-agent/peer-config.md and shared-log.md), and the Python helper attempts to auto-read local OpenClaw config paths and run 'tailscale ip -4'. These are in-scope for setup but involve reading and persisting sensitive config data.

Install Mechanism

No install spec included (instruction-only). Install steps recommend standard platform installers or tailscale's official install script (tailscale.com). No downloads from untrusted personal servers in the skill itself.

Credentials

The skill does not declare environment variables, but it instructs exchanging and storing sensitive secrets: Tailscale auth keys, OpenClaw gateway tokens, and agent IDs. The helper script may read user config files (~/.openclaw/config.json) to auto-detect gateway info. Requesting and persisting those secrets is functionally necessary for peer operation but increases risk if files are shared, backed up, or published.

Persistence & Privilege

always is false and the skill does not request elevated or always-on privileges. It writes a single peer-agent/peer-config.md in the working directory (expected). Autonomous agent invocation (sessions_send) is enabled by default — standard for skills — so consider what agents are allowed to send to peers.

Assessment

This skill appears to do what it says: it helps two OpenClaw gateways talk over a Tailscale VPN. Before installing/using it, make sure you (1) trust the peer you will share auth keys and gateway tokens with — those tokens grant direct access to your gateway, (2) never paste auth keys or gateway tokens into public places; prefer short-lived/revocable Tailscale auth keys and rotate gateway tokens after testing, (3) be cautious about storing tokens in plaintext files (peer-agent/peer-config.md or shared logs) — keep these files out of version control and cloud backups, (4) prefer using Tailscale ACLs or per-device ACLs to limit access, (5) avoid binding the gateway to 0.0.0.0 unless necessary; consider binding to the Tailscale IP specifically, and enable gateway.auth, and (6) review the included script (scripts/peer_config.py) before running — it will attempt to run 'tailscale ip -4' and read common OpenClaw config paths to auto-detect info. If you want higher assurance, ask the author to: declare required binaries (tailscale, openclaw) in metadata, avoid writing tokens to disk by prompting to copy/paste only into ephemeral prompts, and document the exact security implications of exchanging tokens.

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

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)

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

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

openclaw gateway status

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

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

Apply and restart:

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:

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

Machine B tells Machine A:

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

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

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

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:

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:

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

Pattern 3: Code/Review Request

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

Pattern 4: Delegation

"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