libp2p-mesh 2026.5.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+# openclaw-libp2p-mesh
+
+P2P mesh network plugin for OpenClaw. Enables direct peer-to-peer communication between OpenClaw instances using libp2p — no central server required.
+
+## Features
+
+- **LAN Discovery** — Auto-discovers peers on the same local network via mDNS (Bonjour/Avahi)
+- **Direct Messaging** — Send messages directly to another peer by its Peer ID
+- **Broadcast** — Publish messages to a shared topic, flood-fill forwarded across the mesh
+- **Bootstrap Mode** — Optional static bootstrap peer list for non-LAN scenarios
+- **WebSocket Transport** — Optional WebSocket support for NAT/firewall-friendly connections
+
+## Requirements
+
+- OpenClaw >= 2026.3.24
+- Node.js >= 22
+- For LAN discovery: both peers must be on the same local network (same WiFi / Ethernet segment)
+
+## Installation
+
+### Method 1: Via OpenClaw CLI (Recommended)
+
+```bash
+openclaw install openclaw-libp2p-mesh
+```
+
+### Method 2: Manual (npm)
+
+如果无法通过 OpenClaw CLI 安装，可以手动安装到 managed npm root：
+
+```bash
+cd ~/.openclaw/npm
+npm install openclaw-libp2p-mesh
+```
+
+然后刷新插件注册表：
+
+```bash
+openclaw plugins registry --refresh
+```
+
+The published npm package includes compiled JavaScript under `dist/`, so OpenClaw and acpx can load it directly.
+
+Then add to your `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "libp2p-mesh": {
+      "enabled": true,
+      "config": {
+        "discovery": "mdns"
+      }
+    }
+  },
+  "channels": {
+    "libp2p-mesh": {
+      "enabled": true
+    }
+  }
+}
+```
+
+## Configuration
+
+Add a `libp2p-mesh` block to your `openclaw.json` under `plugins`:
+
+### Minimal LAN Setup (Default)
+
+```json
+{
+  "plugins": {
+    "libp2p-mesh": {
+      "enabled": true,
+      "config": {
+        "discovery": "mdns"
+      }
+    }
+  },
+  "channels": {
+    "libp2p-mesh": {
+      "enabled": true
+    }
+  }
+}
+```
+
+This is sufficient for two computers on the same WiFi to discover each other.
+
+### With Static Port (Optional)
+
+By default, the node picks a random TCP port. To use a fixed port:
+
+```json
+{
+  "plugins": {
+    "libp2p-mesh": {
+      "enabled": true,
+      "config": {
+        "discovery": "mdns",
+        "listenAddrs": ["/ip4/0.0.0.0/tcp/4001"]
+      }
+    }
+  },
+  "channels": {
+    "libp2p-mesh": {
+      "enabled": true
+    }
+  }
+}
+```
+
+### With Bootstrap Nodes (Cross-Network)
+
+If peers are on different networks, use a bootstrap node:
+
+```json
+{
+  "plugins": {
+    "libp2p-mesh": {
+      "enabled": true,
+      "config": {
+        "discovery": "bootstrap",
+        "bootstrapList": [
+          "/ip4/203.0.113.10/tcp/4001/p2p/12D3KooW..."
+        ]
+      }
+    }
+  },
+  "channels": {
+    "libp2p-mesh": {
+      "enabled": true
+    }
+  }
+}
+```
+
+### Full Configuration Reference
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `discovery` | `string` | `"mdns"` | Discovery mechanism: `"mdns"` (LAN), `"bootstrap"` (static list), `"dht"` (not yet implemented) |
+| `listenAddrs` | `string[]` | `["/ip4/0.0.0.0/tcp/0"]` | libp2p listen multiaddrs |
+| `bootstrapList` | `string[]` | `[]` | Static bootstrap peer multiaddrs (when `discovery=bootstrap`) |
+| `enableWebSocket` | `boolean` | `false` | Enable WebSocket transport for browser/NAT compatibility |
+| `meshTopic` | `string` | `"openclaw-mesh"` | Default broadcast topic |
+| `enableAgentSync` | `boolean` | `true` | Enable agent state synchronization over the mesh |
+
+## Usage: Two Computers on the Same LAN
+
+### Step 1 — Start both gateways
+
+**Computer A** (e.g. your desktop):
+```bash
+openclaw gateway run
+```
+
+**Computer B** (e.g. your laptop or a friend's machine):
+```bash
+openclaw gateway run
+```
+
+Wait ~5–10 seconds for mDNS discovery. You should see in the logs:
+```
+[libp2p-mesh] Peer connected: 12D3KooW...
+```
+
+### Step 2 — Find your Peer ID
+
+On each computer:
+```bash
+openclaw channels status --probe
+```
+
+Look for the `libp2p-mesh` channel section — your Peer ID is displayed there. It looks like:
+```
+12D3KooWRYyHaWzL8n7i5Z8zZ8Z8Z8Z8Z8Z8Z8Z8Z8Z8Z8
+```
+
+Alternatively, check the gateway startup log:
+```
+[libp2p-mesh] Node started. Peer ID: 12D3KooW...
+```
+
+### Step 3 — Send a message
+
+**From Computer A to Computer B:**
+```bash
+openclaw message send libp2p-mesh <COMPUTER-B-PEER-ID> "Hello from A!"
+```
+
+**From Computer B to Computer A:**
+```bash
+openclaw message send libp2p-mesh <COMPUTER-A-PEER-ID> "Hello from B!"
+```
+
+### Step 4 — Verify receipt
+
+Check the gateway logs on the receiving machine. You should see:
+```
+[libp2p-mesh] Direct message from <sender-peer-id>: Hello from A!
+```
+
+## Troubleshooting
+
+### Peers do not discover each other
+
+1. **Confirm same network** — Both computers must be on the same subnet (e.g. `192.168.1.x`). Check with `ip addr` or `ifconfig`.
+2. **Check firewall** — OpenClaw needs inbound TCP access on the port chosen by libp2p (random by default). Temporarily disable the firewall to test:
+   - macOS: `sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off`
+   - Linux (ufw): `sudo ufw disable`
+   - Linux (firewalld): `sudo systemctl stop firewalld`
+3. **Check mDNS** — Ensure mDNS/Bonjour/Avahi is running:
+   - macOS: built-in, should work
+   - Linux: `sudo systemctl status avahi-daemon`
+4. **Use static port + manual IP** — If mDNS still fails, switch to bootstrap mode and use the LAN IP directly:
+   ```json
+   {
+     "discovery": "bootstrap",
+     "bootstrapList": [
+       "/ip4/192.168.1.42/tcp/4001/p2p/<PEER-ID-OF-OTHER-MACHINE>"
+     ]
+   }
+   ```
+
+### "Mesh network is not started" error
+
+This error only appears if you run `openclaw message send` while the gateway is **not** running. Start the gateway first:
+```bash
+openclaw gateway run
+```
+
+If the gateway is already running, the CLI automatically routes through the gateway (this was fixed in recent versions).
+
+### Message timeout after 8 seconds
+
+The peer may be unreachable. Check:
+- Is the target gateway still running?
+- Are both machines on the same network?
+- Is there a firewall blocking the connection?
+
+## Architecture
+
+```
+┌─────────────┐      mDNS LAN        ┌─────────────┐
+│  Computer A │  ←────────────────→  │  Computer B │
+│  (OpenClaw) │    auto-discovery    │  (OpenClaw) │
+│             │  ◄─── libp2p/TCP ──► │             │
+│  Peer ID: A │                      │  Peer ID: B │
+└─────────────┘                      └─────────────┘
+```
+
+- **mDNS** broadcasts service announcements on the LAN
+- **libp2p** handles encrypted peer connections and stream multiplexing
+- **Noise** encrypts all traffic between peers
+- Messages are deduplicated by message ID to prevent loops
+
+## Development
+
+```bash
+cd extensions/libp2p-mesh
+
+# Standalone mesh test (no OpenClaw required)
+node --import tsx test-p2p-communication.mjs
+
+# Build the plugin
+cd ../..
+pnpm build
+```
+
+## License
+
+MIT

package/api.ts

@@ -0,0 +1,2 @@
+export { createMeshNetwork } from "./src/mesh.js";
+export type { MeshNetwork, P2PMessage, MeshConfig } from "./src/types.js";

package/dist/api.d.ts

@@ -0,0 +1,2 @@
+export { createMeshNetwork } from "./src/mesh.js";
+export type { MeshNetwork, P2PMessage, MeshConfig } from "./src/types.js";

package/dist/api.js

@@ -0,0 +1 @@
+export { createMeshNetwork } from "./src/mesh.js";

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { OpenClawPluginConfigSchema } from "openclaw/plugin-sdk/core";
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: OpenClawPluginConfigSchema;
+    register: NonNullable<import("openclaw/plugin-sdk/core").OpenClawPluginDefinition["register"]>;
+} & Pick<import("openclaw/plugin-sdk/core").OpenClawPluginDefinition, "reload" | "kind" | "nodeHostCommands" | "securityAuditCollectors">;
+export default _default;

package/dist/index.js

@@ -0,0 +1,62 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/core";
+import { registerLibp2pMesh } from "./src/plugin.js";
+function createLibp2pMeshConfigSchema() {
+    return {
+        safeParse(value) {
+            if (value === undefined) {
+                return { success: true, data: undefined };
+            }
+            if (!value || typeof value !== "object" || Array.isArray(value)) {
+                return {
+                    success: false,
+                    error: { issues: [{ path: [], message: "expected config object" }] },
+                };
+            }
+            return { success: true, data: value };
+        },
+        jsonSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                listenAddrs: {
+                    type: "array",
+                    items: { type: "string" },
+                    default: ["/ip4/0.0.0.0/tcp/0"],
+                },
+                enableWebSocket: {
+                    type: "boolean",
+                    default: false,
+                    description: "Enable WebSocket transport (useful for browser compatibility)",
+                },
+                discovery: {
+                    type: "string",
+                    enum: ["mdns", "bootstrap", "dht"],
+                    default: "mdns",
+                },
+                bootstrapList: {
+                    type: "array",
+                    items: { type: "string" },
+                },
+                meshTopic: {
+                    type: "string",
+                    default: "openclaw-mesh",
+                },
+                enablePubsub: {
+                    type: "boolean",
+                    default: true,
+                },
+                enableAgentSync: {
+                    type: "boolean",
+                    default: true,
+                },
+            },
+        },
+    };
+}
+export default definePluginEntry({
+    id: "libp2p-mesh",
+    name: "libp2p Mesh Network",
+    description: "P2P network for cross-instance agent communication via libp2p.",
+    configSchema: createLibp2pMeshConfigSchema(),
+    register: registerLibp2pMesh,
+});

package/dist/src/agent-tools.d.ts

@@ -0,0 +1,130 @@
+import type { MeshNetwork } from "./types.js";
+export declare function buildP2PTools(mesh: MeshNetwork): ({
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {
+            peerId: {
+                type: "string";
+                description: string;
+            };
+            message: {
+                type: "string";
+                description: string;
+            };
+            topic?: undefined;
+        };
+        required: string[];
+    };
+    execute(_toolCallId: string, params: {
+        peerId: string;
+        message: string;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            sent: boolean;
+            peerId: string;
+            error?: undefined;
+        };
+        isError?: undefined;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            sent: boolean;
+            peerId: string;
+            error: string;
+        };
+        isError: boolean;
+    }>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {
+            topic: {
+                type: "string";
+                description: string;
+            };
+            message: {
+                type: "string";
+                description: string;
+            };
+            peerId?: undefined;
+        };
+        required: string[];
+    };
+    execute(_toolCallId: string, params: {
+        topic: string;
+        message: string;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            broadcast: boolean;
+            topic: string;
+            error?: undefined;
+        };
+        isError?: undefined;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            broadcast: boolean;
+            topic: string;
+            error: string;
+        };
+        isError: boolean;
+    }>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {
+            peerId?: undefined;
+            message?: undefined;
+            topic?: undefined;
+        };
+        required?: undefined;
+    };
+    execute(_toolCallId: string): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            localPeerId: string;
+            connectedPeers: string[];
+            count: number;
+            error?: undefined;
+        };
+        isError?: undefined;
+    } | {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            error: string;
+            localPeerId?: undefined;
+            connectedPeers?: undefined;
+            count?: undefined;
+        };
+        isError: boolean;
+    }>;
+})[];

package/dist/src/agent-tools.js

@@ -0,0 +1,116 @@
+export function buildP2PTools(mesh) {
+    return [
+        {
+            name: "p2p_send_message",
+            label: "P2P Send Message",
+            description: "Send a direct message to another agent via the P2P mesh network.",
+            parameters: {
+                type: "object",
+                properties: {
+                    peerId: {
+                        type: "string",
+                        description: "Target peer ID (libp2p Peer ID string)",
+                    },
+                    message: {
+                        type: "string",
+                        description: "Message content to send",
+                    },
+                },
+                required: ["peerId", "message"],
+            },
+            async execute(_toolCallId, params) {
+                try {
+                    await mesh.sendToPeer(params.peerId, params.message);
+                    return {
+                        content: [{ type: "text", text: `Message sent to ${params.peerId}` }],
+                        details: { sent: true, peerId: params.peerId },
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Failed to send message to ${params.peerId}: ${String(err)}`,
+                            },
+                        ],
+                        details: { sent: false, peerId: params.peerId, error: String(err) },
+                        isError: true,
+                    };
+                }
+            },
+        },
+        {
+            name: "p2p_broadcast",
+            label: "P2P Broadcast",
+            description: "Broadcast a message to all peers on a topic via the P2P mesh network.",
+            parameters: {
+                type: "object",
+                properties: {
+                    topic: {
+                        type: "string",
+                        description: "Topic name to broadcast on",
+                    },
+                    message: {
+                        type: "string",
+                        description: "Message content to broadcast",
+                    },
+                },
+                required: ["topic", "message"],
+            },
+            async execute(_toolCallId, params) {
+                try {
+                    await mesh.publishToTopic(params.topic, params.message);
+                    return {
+                        content: [{ type: "text", text: `Broadcast sent to topic ${params.topic}` }],
+                        details: { broadcast: true, topic: params.topic },
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Failed to broadcast to topic ${params.topic}: ${String(err)}`,
+                            },
+                        ],
+                        details: { broadcast: false, topic: params.topic, error: String(err) },
+                        isError: true,
+                    };
+                }
+            },
+        },
+        {
+            name: "p2p_list_peers",
+            label: "P2P List Peers",
+            description: "List currently connected peers in the P2P mesh network.",
+            parameters: {
+                type: "object",
+                properties: {},
+            },
+            async execute(_toolCallId) {
+                try {
+                    const peers = mesh.getConnectedPeers();
+                    const text = peers.length === 0
+                        ? "No peers currently connected."
+                        : `Connected peers (${peers.length}): ${peers.join(", ")}`;
+                    return {
+                        content: [{ type: "text", text }],
+                        details: {
+                            localPeerId: mesh.getLocalPeerId(),
+                            connectedPeers: peers,
+                            count: peers.length,
+                        },
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [{ type: "text", text: `Failed to list peers: ${String(err)}` }],
+                        details: { error: String(err) },
+                        isError: true,
+                    };
+                }
+            },
+        },
+    ];
+}

package/dist/src/channel.d.ts

@@ -0,0 +1,3 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+import type { MeshNetwork } from "./types.js";
+export declare function createLibp2pMeshChannel(mesh: MeshNetwork): ChannelPlugin;

package/dist/src/channel.js

@@ -0,0 +1,66 @@
+import { createChatChannelPlugin } from "openclaw/plugin-sdk/core";
+import { sendViaMesh } from "./send.js";
+export function createLibp2pMeshChannel(mesh) {
+    return createChatChannelPlugin({
+        base: {
+            id: "libp2p-mesh",
+            meta: {
+                id: "libp2p-mesh",
+                label: "P2P Mesh",
+                selectionLabel: "P2P Mesh",
+                docsPath: "/channels/libp2p-mesh",
+                docsLabel: "libp2p-mesh",
+                blurb: "libp2p mesh network for cross-instance agent communication.",
+                systemImage: "network",
+            },
+            capabilities: {
+                chatTypes: ["direct"],
+                media: false,
+                blockStreaming: false,
+            },
+            configSchema: {
+                schema: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {},
+                },
+            },
+            config: {
+                listAccountIds: () => ["default"],
+                resolveAccount: () => ({
+                    accountId: "default",
+                    configured: true,
+                    enabled: true,
+                }),
+                isConfigured: () => true,
+                isEnabled: () => true,
+                describeAccount: () => ({
+                    accountId: "default",
+                    name: "default",
+                    configured: true,
+                    enabled: true,
+                    connected: mesh.getConnectedPeers().length > 0,
+                }),
+            },
+            messaging: {
+                normalizeTarget: (raw) => raw.trim(),
+                targetResolver: {
+                    looksLikeId: () => true,
+                    hint: "peer-id",
+                },
+            },
+        },
+        outbound: {
+            deliveryMode: "gateway",
+            sendText: async ({ to, text }) => {
+                try {
+                    await sendViaMesh(mesh, to, text);
+                    return { channel: "libp2p-mesh", messageId: `p2p-${Date.now()}` };
+                }
+                catch (err) {
+                    return { channel: "libp2p-mesh", messageId: `p2p-${Date.now()}`, meta: { error: String(err) } };
+                }
+            },
+        },
+    });
+}