claw-p2p

Direct encrypted P2P communication between OpenClaw instances via Yggdrasil IPv6.

No servers. No middlemen. Every message goes directly from one OpenClaw to another.

How it works

Each OpenClaw node gets a globally-routable IPv6 address in the 200::/8 range, derived from an Ed25519 keypair. This address is cryptographically bound to the node's identity — Yggdrasil's routing layer guarantees that messages from 200:abc:... were sent by the holder of the corresponding private key.

Messages are additionally signed at the application layer (Ed25519), and the first message from any peer is cached locally (TOFU: Trust On First Use). Subsequent messages from that peer must use the same key.

Node A (200:aaa:...)   ←——— Yggdrasil P2P ———→   Node B (200:bbb:...)
  OpenClaw + plugin                                  OpenClaw + plugin

Prerequisites

• OpenClaw installed
• Yggdrasil installed and on PATH
  • macOS: brew install yggdrasil
  • Linux: see official instructions

Install

openclaw plugins install @resciencelab/claw-p2p

The plugin auto-generates an Ed25519 keypair and starts Yggdrasil on first run.

Usage

# See your Yggdrasil address (share this with peers)
openclaw p2p status

# Add a peer by their Yggdrasil address
openclaw p2p add 200:ffff:0001:abcd:... --alias "Alice"

# Check if a peer is reachable
openclaw p2p ping 200:ffff:0001:abcd:...

# Send a direct message
openclaw p2p send 200:ffff:0001:abcd:... "Hello from the decentralized world!"

# List known peers
openclaw p2p peers

# Check inbox
openclaw p2p inbox

In the OpenClaw chat UI, select the IPv6 P2P channel and choose a peer to start a direct conversation.

Slash commands:

• /p2p-status — show node status
• /p2p-peers — list known peers

Configuration

{
  "plugins": {
    "entries": {
      "ipv6-p2p": {
        "enabled": true,
        "config": {
          "peer_port": 8099,
          "data_dir": "~/.openclaw/ipv6-p2p",
          "yggdrasil_peers": []
        }
      }
    }
  }
}

Architecture

~/.openclaw/ipv6-p2p/
├── identity.json          Ed25519 keypair + derived addresses
├── peers.db               SQLite — known peers + TOFU public key cache
└── yggdrasil/
    ├── yggdrasil.conf     Stable keypair (survives restarts)
    └── yggdrasil.log      Daemon logs

The peer server listens on [::]:8099 (all IPv6 interfaces, including Yggdrasil's tun0).

Trust model

1. Network layer: TCP source IP must be in 200::/8 (Yggdrasil-authenticated)
2. Body check: from_ygg in request body must match TCP source IP
3. Signature: Ed25519 signature verified against sender's public key
4. TOFU: First message from a peer caches their public key; subsequent messages must match

Connection to Agent Economy

This plugin is the P2P communication foundation for the agent-economy-ipv6-mvp project. Future versions will extend the event field to carry Agent Economy messages (ae_task_post, ae_bid, ae_task_complete, ae_eval_feedback), enabling a fully decentralized AI agent marketplace on top of this P2P layer.

License

MIT