LobsterLAN — Agent-to-Agent Communication

---

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.

---

# 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