Lobsterlan

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:

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)