lobsterlan

name	lobsterlan
version	1.0.1
description	Communicate with other OpenClaw agents on your local network. Use when you need to ask another agent a question (sync), delegate a task (async), or check if a peer agent is reachable. Supports both synchronous chat completions and asynchronous webhook-based task delegation. Requires peers.json config with peer addresses and tokens.

Cleanup Review

python scripts/_cleanup.py is an optional cleanup helper for the LobsterLAN — Agent-to-Agent Communication skill. It may recursively remove ~/.cache/skill_tmp, ~/.skill_state. Show the exact paths first, explain whether they are skill-private temporary paths or user state, and run the cleanup only after the user confirms.

LobsterLAN — Agent-to-Agent Communication

Talk to other OpenClaw agents on your LAN.

Setup

1. Copy config/peers.example.json to config/peers.json
2. Fill in peer hostnames, ports, and tokens
3. Ensure target agents have the required APIs enabled (see below)
4. Set up a secure transport (see Network Transport below)

Required Config on Target Agent

For sync ask (chat completions):

// Target agent's openclaw.json — keep bind as "loopback"!
{
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": { "enabled": true }
      }
    }
  }
}

⚠️ Do NOT set gateway.bind to "lan" — OpenClaw will refuse to start if the gateway is exposed on a non-loopback address without TLS. Use a secure transport instead (see below).

For async delegate (webhooks):

{
  "hooks": {
    "enabled": true,
    "token": "a-secure-shared-secret"
  }
}

Network Transport

OpenClaw gateways default to bind: loopback and will not start with plaintext on non-loopback addresses. You need a secure transport layer for cross-host communication:

Approach	Complexity	Best For
SSH Tunnel ⭐	Low	Home LANs, simple setups
Reverse Proxy (TLS)	Medium	Environments with existing Caddy/nginx
Tailscale Serve	Medium	Multi-site or remote agents

For simple LANs, SSH tunneling is recommended. Both gateways stay on loopback, the SSH tunnel provides encryption, and no gateway config changes are needed.

SSH Tunnel Example

Forward a local port to the remote agent's loopback gateway:

ssh -N -L 18790:127.0.0.1:18790 user@remote-agent-host

Then in peers.json, point the peer to 127.0.0.1:18790 (the local tunnel endpoint).

For persistence, use a systemd user service with Restart=always. See the full setup guide in docs/setup.md.

Commands

Ask (synchronous — wait for reply)

scripts/lobsterlan.sh ask scotty "What is the CPU temperature?"

Use for quick questions where you need the answer now.

Delegate (async — fire and forget)

scripts/lobsterlan.sh delegate scotty "Generate 5 zen wallpapers and push to the file share"

Use for long-running tasks. The peer processes independently.

Status check

scripts/lobsterlan.sh status scotty

List peers

scripts/lobsterlan.sh peers

Agent Usage (from within OpenClaw)

Run via exec tool:

cd ~/.openclaw/workspace/skills/lobsterlan && scripts/lobsterlan.sh ask scotty "status report"

Security

Three layers protect communication:

1. Network: LAN-only (firewall blocks external access to gateway port)
2. Gateway token: Bearer auth on every request
3. Agent ID header (optional): X-LobsterLAN-Agent sent with self-ID

The gateway token is the real security boundary. The agent ID header is defense-in-depth for environments where you want explicit identity verification.

Environment Variables

• LOBSTERLAN_CONFIG — path to peers.json (default: ../config/peers.json relative to script)