OpenClaw Agent Mesh

Provide a minimal but real agent-to-agent communication layer for OpenClaw instances.
Use the bundled scripts to initialize identity, scan a local network range, exchange contact requests, approve peers, and send signed direct messages.
Require explicit acceptance before trusted communication begins.

V1 scope

Implement only these capabilities:

• - local identity generation
• LAN discovery by probing peer endpoints
• contact request creation
• contact approval or rejection
• trusted peer storage
• direct signed message creation and delivery
• inbox verification and acknowledgement
• lightweight HTTP server for discovery, contact-request intake, and message intake

Do not claim NAT traversal, full mesh routing, or multi-party consensus in V1.

Files and local state

Store mesh state outside the skill folder.
Use this default path unless the user specifies another one:

• - INLINECODE0

Expected files:

• - identity.json — local agent identity
• INLINECODE2 — local signing key
• INLINECODE3 — trusted peers
• INLINECODE4 — pending inbound contact requests
• INLINECODE5 — outbound contact requests
• INLINECODE6 — verified inbound messages
• INLINECODE7 — sent messages
• INLINECODE8 — reserved for future versions

Workflow

1. Initialize local identity

Run scripts/mesh.py init.
This creates a signing keypair and an identity card with:

• - INLINECODE10
• INLINECODE11
• INLINECODE12
• INLINECODE13
• INLINECODE14
• INLINECODE15

Set the endpoint to a reachable HTTP URL if the node should receive requests from peers.

2. Scan for nearby peers

Run scripts/mesh.py scan with a base URL template or a list of candidate URLs.
Scanning in V1 is HTTP discovery, not raw port scanning.
Probe each candidate at:

• - INLINECODE17

Treat discovered nodes as untrusted until approved.

3. Send a contact request

Run scripts/mesh.py request-contact.
Send a signed request to a discovered node’s inbox endpoint.
The receiver stores the request as pending.

4. Approve or reject the request

Run scripts/mesh.py list-requests then approve-request or reject-request.
Approval writes the peer into the trust store.
Rejection leaves no trusted relationship.

5. Send a direct message

Run scripts/mesh.py send-message only after trust exists.
The sender signs the message envelope.
The receiver verifies signature, timestamp, and trust status before accepting.

6. Verify delivery

Run scripts/mesh.py list-messages or inspect stored message JSON files.
Use acknowledgements to confirm receipt.

Transport model

V1 uses simple HTTP JSON endpoints:

• - INLINECODE24
• INLINECODE25
• INLINECODE26

Run scripts/server.py to expose these endpoints from a node that should be discoverable or receive peer traffic.
Example:

• - INLINECODE28

If the user does not yet have a server to receive HTTP traffic, use the scripts to generate and inspect signed payloads locally first.

Guardrails

• - Require explicit approval before trusting a peer.
• Never auto-accept unknown peers.
• Never send private keys over the network.
• Prefer signed JSON envelopes with timestamps and message IDs.
• Reject stale or malformed messages.
• Keep V1 limited to point-to-point trust and messaging.

References

• - Read references/protocol.md for the JSON message model.
• Read references/verification.md for trust and signature checks.

Deliverables

When using this skill, produce one or more of:

• - a configured local mesh identity
• a peer discovery result set
• a pending or approved contact request
• a verified direct-message flow
• a troubleshooting checklist for failed trust or message delivery