lobsterlan

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.

install

source · Clone the upstream repo

git clone https://github.com/danielithomas/lobsterlan

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/danielithomas/lobsterlan "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skill" ~/.claude/skills/danielithomas-lobsterlan-lobsterlan && rm -rf "$T"

manifest: skill/SKILL.md

source content

LobsterLAN — Agent-to-Agent Communication

Talk to other OpenClaw agents on your LAN.

Setup

Copy

config/peers.example.json

config/peers.json

Fill in peer hostnames, ports, and tokens
Ensure target agents have the required APIs enabled (see below)
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:

Network: LAN-only (firewall blocks external access to gateway port)
Gateway token: Bearer auth on every request
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)