libp2p-mesh 2026.5.15 → 2026.5.17

package/README.md

@@ -42,7 +42,9 @@ 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`:
+After installing the plugin, you must:
+
+1. **Enable the plugin** in `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -62,6 +64,78 @@ Then add to your `~/.openclaw/openclaw.json`:
 }
 ```
 
+2. **Set `tools.profile` to `full`** — OpenClaw defaults to `"coding"` profile, which **filters out** P2P tools. Even if you add them to `tools.allow`, the coding profile will still block them. You must change to `"full"` first:
+
+```json
+{
+  "tools": {
+    "profile": "full",
+    "allow": [
+      "p2p_list_peers",
+      "p2p_send_message",
+      "p2p_broadcast"
+    ]
+  }
+}
+```
+
+> **Why `profile: "full"`?** The `"coding"` profile hardcodes a deny list that includes `p2p_list_peers`, `p2p_send_message`, and `p2p_broadcast`. With `profile: "coding"`, adding tools to `tools.allow` has no effect for these three — the profile filter runs first and removes them.
+
+3. **Restart the gateway:**
+
+```bash
+openclaw gateway restart
+```
+
+4. **Verify tool registration:**
+
+```bash
+openclaw plugins inspect libp2p-mesh --runtime --json | jq '.plugin.toolNames, .tools'
+```
+
+Expected output:
+```json
+[
+  "p2p_send_message",
+  "p2p_broadcast",
+  "p2p_list_peers",
+  "p2p_get_instance_identity",
+  "p2p_get_network_info"
+]
+```
+
+### One-command setup (optional)
+
+Instead of manually editing `openclaw.json`, run:
+
+```bash
+npx openclaw-libp2p-mesh-configure-tools
+# or, from the plugin directory:
+npm run configure-tools
+```
+
+This patches `~/.openclaw/openclaw.json` with the correct `tools.profile` and `tools.allow` values. Use `--check` to preview without modifying:
+
+```bash
+npm run configure-tools:check
+```
+
+## Troubleshooting
+
+### "plugin must declare contracts.tools before registering agent tools"
+
+Make sure you are running **OpenClaw >= 2026.6.5** and the plugin is installed via `openclaw install` or `npm install` into `~/.openclaw/npm`. The manifest (`openclaw.plugin.json`) ships with `contracts.tools` pre-declared, so no manual manifest edits are needed.
+
+### Tools still not available after setup
+
+1. Confirm `tools.profile` is `"full"` (not `"coding"`):
+   ```bash
+   cat ~/.openclaw/openclaw.json | jq '.tools'
+   ```
+2. Confirm all three P2P tools are in `tools.allow`.
+3. Restart the gateway (not just reload).
+4. Check `openclaw plugins inspect libp2p-mesh --runtime --json` for diagnostics.
+
 ## Configuration
 
 Add a `libp2p-mesh` block to your `openclaw.json` under `plugins`:

package/dist/index.d.ts

@@ -1,9 +1,3 @@
-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">;
+import { definePluginEntry } from "openclaw/plugin-sdk/core";
+declare const _default: ReturnType<typeof definePluginEntry>;
 export default _default;

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

@@ -214,4 +214,31 @@ export declare function buildP2PTools(mesh: MeshNetwork): ({
         };
         isError: boolean;
     }>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {
+            peerId?: undefined;
+            message?: undefined;
+            topic?: undefined;
+        };
+        required?: undefined;
+    };
+    execute(_toolCallId: string, _params: {}, _ctx: any): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {
+            localPeerId: string;
+            connectedPeers: string[];
+            knownIdentities: {
+                peerId: string;
+                identity: any;
+            }[];
+        };
+    }>;
 })[];

package/dist/src/agent-tools.js

@@ -191,5 +191,24 @@ export function buildP2PTools(mesh) {
                 }
             },
         },
+        {
+            name: "p2p_relay_status",
+            label: "P2P Relay Status",
+            description: "Get current P2P mesh connection status, known peers, and identity mapping.",
+            parameters: { type: "object", properties: {} },
+            async execute(_toolCallId, _params, _ctx) {
+                const peerIdentityMap = this.peerIdentityMap;
+                const localPeerId = mesh.getLocalPeerId();
+                const connectedPeers = mesh.getConnectedPeers();
+                const knownIdentities = connectedPeers
+                    .map((p) => ({ peerId: p, identity: peerIdentityMap?.resolve(p) }))
+                    .filter((entry) => entry.identity !== undefined);
+                const text = `P2P Mesh Status:\nLocal Peer ID: ${localPeerId}\nConnected Peers: ${connectedPeers.length}\nKnown Identities: ${knownIdentities.length}`;
+                return {
+                    content: [{ type: "text", text }],
+                    details: { localPeerId, connectedPeers, knownIdentities },
+                };
+            },
+        },
     ];
 }

package/dist/src/identity-exchange.d.ts

@@ -0,0 +1,12 @@
+import type { P2PMessage } from "./types.js";
+import type { PeerIdentityMap } from "./peer-identity.ts";
+export interface IdentityExchangeDeps {
+    peerIdentityMap: PeerIdentityMap;
+    localPeerId: string;
+    localAgentId: string;
+    localChannel: string;
+    localAccountId: string;
+    send: (peerId: string, message: P2PMessage) => Promise<void>;
+}
+export declare function buildIdentityMessage(peerId: string, agentId: string, channel: string, accountId: string): P2PMessage;
+export declare function handleIdentityMessage(msg: P2PMessage, deps: IdentityExchangeDeps): Promise<void>;

package/dist/src/identity-exchange.js

@@ -0,0 +1,35 @@
+export function buildIdentityMessage(peerId, agentId, channel, accountId) {
+    return {
+        id: crypto.randomUUID(),
+        type: "identity",
+        from: peerId,
+        payload: JSON.stringify({ agentId, channel, accountId }),
+        timestamp: Date.now(),
+    };
+}
+export async function handleIdentityMessage(msg, deps) {
+    // Parse remote identity payload
+    let parsed = {};
+    try {
+        parsed = JSON.parse(msg.payload);
+    }
+    catch {
+        // Malformed payload — skip silently
+        return;
+    }
+    const { agentId, channel, accountId } = parsed;
+    // Only register if all required fields are present
+    if (agentId && channel && accountId) {
+        const { buildAgentSessionKey } = await import("openclaw/plugin-sdk/core");
+        const sessionKey = buildAgentSessionKey({ agentId, channel, accountId });
+        deps.peerIdentityMap.register(msg.from, {
+            agentId,
+            channel,
+            accountId,
+            sessionKey,
+        });
+    }
+    // Send local identity back to the remote peer
+    const localIdentity = buildIdentityMessage(deps.localPeerId, deps.localAgentId, deps.localChannel, deps.localAccountId);
+    await deps.send(msg.from, localIdentity);
+}

package/dist/src/inbound.d.ts

@@ -1,10 +1,17 @@
 import type { P2PMessage } from "./types.js";
-export type InboundHandlerDeps = {
+import type { PeerIdentityMap } from "./peer-identity.ts";
+import type { PluginNextTurnInjection } from "openclaw/plugin-sdk/core";
+export interface InboundHandlerDeps {
+    peerIdentityMap?: PeerIdentityMap;
+    enqueueNextTurnInjection?: (injection: PluginNextTurnInjection) => Promise<{
+        enqueued: boolean;
+        id: string;
+    }>;
     logger?: {
         info?: (msg: string) => void;
         debug?: (msg: string) => void;
         warn?: (msg: string) => void;
         error?: (msg: string) => void;
     };
-};
-export declare function handleP2PInbound(msg: P2PMessage, deps: InboundHandlerDeps): void;
+}
+export declare function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDeps): void;

package/dist/src/inbound.js

@@ -1,6 +1,7 @@
 import { verifyInstanceSignature } from "./instance-id.js";
+import { buildAgentSessionKey } from "openclaw/plugin-sdk/core";
 export function handleP2PInbound(msg, deps) {
-    const { logger } = deps;
+    const logger = deps?.logger;
     const instanceTag = msg.instanceId ? ` [instance: ${msg.instanceId}]` : "";
     const signedTag = msg.signature ? " [signed]" : "";
     // Verify signature if present
@@ -15,7 +16,14 @@ export function handleP2PInbound(msg, deps) {
             timestamp: msg.timestamp,
             instanceId: msg.instanceId,
         });
-        const valid = verifyInstanceSignature({ id: msg.instanceId, name: "", pubkey: msg.pubkey, binding: "", bindingComponents: { username: "", hostname: "", platform: "" }, createdAt: 0 }, signedPayload, msg.signature);
+        const valid = verifyInstanceSignature({
+            id: msg.instanceId,
+            name: "",
+            pubkey: msg.pubkey,
+            binding: "",
+            bindingComponents: { username: "", hostname: "", platform: "" },
+            createdAt: 0,
+        }, signedPayload, msg.signature);
         if (valid) {
             logger?.info?.(`[libp2p-mesh] Verified signature from instance ${msg.instanceId}`);
         }
@@ -26,6 +34,66 @@ export function handleP2PInbound(msg, deps) {
     else if (msg.signature) {
         logger?.warn?.(`[libp2p-mesh] Message has signature but no pubkey; cannot verify`);
     }
+    // Relay handling when deps are provided with required fields
+    if (deps?.peerIdentityMap && deps?.enqueueNextTurnInjection) {
+        if (msg.type === "identity") {
+            // Parse remote identity payload and register synchronously
+            let parsed = {};
+            try {
+                parsed = JSON.parse(msg.payload);
+            }
+            catch {
+                // Malformed payload — skip silently
+                return;
+            }
+            const { agentId, channel, accountId } = parsed;
+            if (agentId && channel && accountId) {
+                const sessionKey = buildAgentSessionKey({ agentId, channel, accountId });
+                deps.peerIdentityMap.register(msg.from, {
+                    agentId,
+                    channel,
+                    accountId,
+                    sessionKey,
+                });
+            }
+        }
+        else if (msg.type === "direct") {
+            if (!msg.to) {
+                logger?.warn?.("[libp2p-mesh] Direct message missing 'to' field");
+            }
+            else {
+                const receiver = deps.peerIdentityMap.resolve(msg.to);
+                if (!receiver) {
+                    logger?.warn?.(`[libp2p-mesh] Unknown recipient peer: ${msg.to}`);
+                }
+                else {
+                    const sessionKey = buildAgentSessionKey({
+                        agentId: receiver.agentId,
+                        channel: receiver.channel,
+                        accountId: receiver.accountId,
+                    });
+                    const text = `【来自P2P网络的消息】\n来源：${msg.from}\n内容：${msg.payload}\n\n` +
+                        `请你通过你当前的 channel 将此消息转发给你所服务的用户。转发完成后，请务必调用 p2p_send_message 工具向 ${msg.from} 回复送达确认。`;
+                    deps.enqueueNextTurnInjection({ sessionKey, text, placement: "prepend_context" });
+                }
+            }
+        }
+        else if (msg.type === "broadcast") {
+            const topic = msg.topic || "(none)";
+            const text = `【来自P2P网络的广播消息】\n话题：${topic}\n来源：${msg.from}\n内容：${msg.payload}\n\n` +
+                `请你通过你当前的 channel 将此广播消息转发给你所服务的用户。`;
+            // Inject broadcast into each known peer's session
+            for (const [, identity] of deps.peerIdentityMap.entries()) {
+                const sessionKey = buildAgentSessionKey({
+                    agentId: identity.agentId,
+                    channel: identity.channel,
+                    accountId: identity.accountId,
+                });
+                deps.enqueueNextTurnInjection({ sessionKey, text, placement: "prepend_context" });
+            }
+        }
+    }
+    // Original logging (unchanged)
     if (msg.type === "broadcast") {
         logger?.info?.(`[libp2p-mesh] Broadcast from ${msg.from}${instanceTag}${signedTag} on topic ${msg.topic ?? "(none)"}: ${msg.payload}`);
     }

package/dist/src/mesh.js

@@ -214,11 +214,11 @@ export function createMeshNetwork(options) {
         });
         state.node.addEventListener("peer:connect", (evt) => {
             const peerIdStr = evt.detail.toString();
-            logger?.debug?.(`[libp2p-mesh] Peer connected: ${peerIdStr}`);
+            logger?.info?.(`[libp2p-mesh] Peer connected: ${peerIdStr}`);
         });
         state.node.addEventListener("peer:disconnect", (evt) => {
             const peerIdStr = evt.detail.toString();
-            logger?.debug?.(`[libp2p-mesh] Peer disconnected: ${peerIdStr}`);
+            logger?.info?.(`[libp2p-mesh] Peer disconnected: ${peerIdStr}`);
         });
         await state.node.handle(PROTOCOL, async ({ stream, connection }) => {
             try {

package/dist/src/peer-identity.d.ts

@@ -0,0 +1,17 @@
+export interface PeerIdentity {
+    agentId: string;
+    channel: string;
+    accountId: string;
+    sessionKey: string;
+}
+export interface PeerIdentityMap {
+    register(peerId: string, identity: PeerIdentity): void;
+    resolve(peerId: string): PeerIdentity | undefined;
+    resolveSessionKey(peerId: string): string | undefined;
+    unregister(peerId: string): void;
+    setLocalIdentity(peerId: string, identity: PeerIdentity): void;
+    getLocalIdentity(): PeerIdentity | undefined;
+    hasIdentity(peerId: string): boolean;
+    entries(): IterableIterator<[string, PeerIdentity]>;
+}
+export declare function createPeerIdentityMap(): PeerIdentityMap;

package/dist/src/peer-identity.js

@@ -0,0 +1,33 @@
+export function createPeerIdentityMap() {
+    const peers = new Map();
+    let localPeerId;
+    let localIdentity;
+    return {
+        register(peerId, identity) {
+            peers.set(peerId, identity);
+        },
+        resolve(peerId) {
+            return peers.get(peerId);
+        },
+        resolveSessionKey(peerId) {
+            return peers.get(peerId)?.sessionKey;
+        },
+        unregister(peerId) {
+            peers.delete(peerId);
+        },
+        setLocalIdentity(peerId, identity) {
+            localPeerId = peerId;
+            localIdentity = identity;
+            peers.set(peerId, identity);
+        },
+        getLocalIdentity() {
+            return localIdentity;
+        },
+        hasIdentity(peerId) {
+            return peers.has(peerId);
+        },
+        entries() {
+            return peers.entries();
+        },
+    };
+}

package/dist/src/plugin.js

@@ -2,18 +2,62 @@ import { createLibp2pMeshChannel } from "./channel.js";
 import { handleP2PInbound } from "./inbound.js";
 import { createMeshNetwork } from "./mesh.js";
 import { buildP2PTools } from "./agent-tools.js";
+import { createPeerIdentityMap } from "./peer-identity.js";
+import { buildIdentityMessage } from "./identity-exchange.js";
 export function registerLibp2pMesh(api) {
     const mesh = createMeshNetwork({
         config: api.pluginConfig,
         logger: api.logger,
     });
+    // Singleton: maps peerId -> { agentId, channel, accountId, sessionKey }
+    const peerIdentityMap = createPeerIdentityMap();
+    // Helper: build the deps object for the relay-aware inbound handler
+    function buildInboundDeps() {
+        return {
+            peerIdentityMap,
+            enqueueNextTurnInjection: (injection) => api.session.workflow.enqueueNextTurnInjection(injection),
+            logger: api.logger,
+        };
+    }
     // 1. Register Service (manages libp2p node lifecycle)
     api.registerService({
         id: "libp2p-mesh",
         start: async () => {
             await mesh.start();
+            // Register local identity so remote peers can route messages back to us
+            const config = api.pluginConfig;
+            const relayChannel = config?.relayChannel;
+            const relayAccountId = config?.relayAccountId;
+            if (relayChannel && relayAccountId) {
+                const localPeerId = mesh.getLocalPeerId();
+                const { buildAgentSessionKey } = await import("openclaw/plugin-sdk/core");
+                const sessionKey = buildAgentSessionKey({
+                    agentId: api.name,
+                    channel: relayChannel,
+                    accountId: relayAccountId,
+                });
+                peerIdentityMap.setLocalIdentity(localPeerId, {
+                    agentId: api.name,
+                    channel: relayChannel,
+                    accountId: relayAccountId,
+                    sessionKey,
+                });
+                api.logger.info?.(`[libp2p-mesh] Local identity registered: agent=${api.name}, channel=${relayChannel}, account=${relayAccountId}`);
+                // Announce identity to all currently-connected peers
+                const identityMsg = buildIdentityMessage(localPeerId, api.name, relayChannel, relayAccountId);
+                const connectedPeers = mesh.getConnectedPeers();
+                for (const peerId of connectedPeers) {
+                    try {
+                        await mesh.sendToPeer(peerId, JSON.stringify(identityMsg));
+                    }
+                    catch {
+                        // Best-effort; peer may be stale in the connection list
+                    }
+                }
+            }
+            // Wire up relay-aware message handler
             mesh.onMessage((msg) => {
-                handleP2PInbound(msg, { logger: api.logger });
+                handleP2PInbound(msg, buildInboundDeps());
             });
             const identity = mesh.getInstanceIdentity();
             api.logger.info?.(`[libp2p-mesh] Service started. Peer ID: ${mesh.getLocalPeerId()}`);
@@ -43,6 +87,7 @@ export function registerLibp2pMesh(api) {
     // 3. Register Agent Tools
     const tools = buildP2PTools(mesh);
     for (const tool of tools) {
+        tool.peerIdentityMap = peerIdentityMap;
         api.registerTool(tool);
     }
     // 4. Register Hook (log received messages for observability)

package/dist/src/types.d.ts

@@ -18,7 +18,7 @@ export interface InstanceIdentity {
 }
 export interface P2PMessage {
     id: string;
-    type: "direct" | "broadcast" | "agent-sync";
+    type: "direct" | "broadcast" | "agent-sync" | "identity";
     from: string;
     to?: string;
     topic?: string;
@@ -81,6 +81,10 @@ export interface MeshConfig {
      * forward where AutoNAT cannot probe (e.g. behind a cloud LB).
      */
     announceAddrs?: string[];
+    /** Relay channel this agent is bound to (used for peer identity registration) */
+    relayChannel?: string;
+    /** Relay account this agent is bound to (used for peer identity registration) */
+    relayAccountId?: string;
 }
 export interface NATTraversalStatus {
     /** Which NAT-traversal services were wired in at start() */

package/index.ts

@@ -122,4 +122,4 @@ export default definePluginEntry({
   description: "P2P network for cross-instance agent communication via libp2p.",
   configSchema: createLibp2pMeshConfigSchema(),
   register: registerLibp2pMesh,
-});
+}) as ReturnType<typeof definePluginEntry>;

package/openclaw.plugin.json

@@ -100,6 +100,16 @@
         "type": "array",
         "items": { "type": "string" },
         "description": "Extra multiaddrs to announce to the network on top of auto-detected ones."
+      },
+      "relayChannel": {
+        "type": "string",
+        "default": "",
+        "description": "P2P message relay channel (e.g. feishu). Required for user-to-user message relay."
+      },
+      "relayAccountId": {
+        "type": "string",
+        "default": "default",
+        "description": "Account ID for relay channel."
       }
     }
   },
@@ -109,7 +119,8 @@
       "p2p_broadcast",
       "p2p_list_peers",
       "p2p_get_instance_identity",
-      "p2p_get_network_info"
+      "p2p_get_network_info",
+      "p2p_relay_status"
     ]
   },
   "uiHints": {

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "libp2p-mesh",
-  "version": "2026.5.15",
+  "version": "2026.5.17",
   "description": "OpenClaw libp2p P2P mesh network plugin for cross-instance agent communication",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "configure-tools": "node scripts/configure-tools.js",
+    "configure-tools:check": "node scripts/configure-tools.js --check"
   },
   "files": [
     "dist",
@@ -63,7 +65,7 @@
       "systemImage": "network"
     },
     "install": {
-      "npmSpec": "libp2p-mesh",
+      "npmSpec": "openclaw-libp2p-mesh",
       "defaultChoice": "npm",
       "minHostVersion": ">=2026.3.24"
     },

package/src/agent-tools.ts

@@ -191,5 +191,24 @@ export function buildP2PTools(mesh: MeshNetwork) {
         }
       },
     },
+    {
+      name: "p2p_relay_status",
+      label: "P2P Relay Status",
+      description: "Get current P2P mesh connection status, known peers, and identity mapping.",
+      parameters: { type: "object" as const, properties: {} },
+      async execute(_toolCallId: string, _params: {}, _ctx: any) {
+        const peerIdentityMap = (this as any).peerIdentityMap;
+        const localPeerId = mesh.getLocalPeerId();
+        const connectedPeers = mesh.getConnectedPeers();
+        const knownIdentities = connectedPeers
+          .map((p) => ({ peerId: p, identity: peerIdentityMap?.resolve(p) }))
+          .filter((entry) => entry.identity !== undefined);
+        const text = `P2P Mesh Status:\nLocal Peer ID: ${localPeerId}\nConnected Peers: ${connectedPeers.length}\nKnown Identities: ${knownIdentities.length}`;
+        return {
+          content: [{ type: "text" as const, text }],
+          details: { localPeerId, connectedPeers, knownIdentities },
+        };
+      },
+    },
   ];
 }

package/src/identity-exchange.ts

@@ -0,0 +1,63 @@
+import type { P2PMessage } from "./types.js";
+import type { PeerIdentityMap } from "./peer-identity.ts";
+
+export interface IdentityExchangeDeps {
+  peerIdentityMap: PeerIdentityMap;
+  localPeerId: string;
+  localAgentId: string;
+  localChannel: string;
+  localAccountId: string;
+  send: (peerId: string, message: P2PMessage) => Promise<void>;
+}
+
+export function buildIdentityMessage(
+  peerId: string,
+  agentId: string,
+  channel: string,
+  accountId: string,
+): P2PMessage {
+  return {
+    id: crypto.randomUUID(),
+    type: "identity",
+    from: peerId,
+    payload: JSON.stringify({ agentId, channel, accountId }),
+    timestamp: Date.now(),
+  };
+}
+
+export async function handleIdentityMessage(
+  msg: P2PMessage,
+  deps: IdentityExchangeDeps,
+): Promise<void> {
+  // Parse remote identity payload
+  let parsed: { agentId?: string; channel?: string; accountId?: string } = {};
+  try {
+    parsed = JSON.parse(msg.payload);
+  } catch {
+    // Malformed payload — skip silently
+    return;
+  }
+
+  const { agentId, channel, accountId } = parsed;
+
+  // Only register if all required fields are present
+  if (agentId && channel && accountId) {
+    const { buildAgentSessionKey } = await import("openclaw/plugin-sdk/core");
+    const sessionKey = buildAgentSessionKey({ agentId, channel, accountId });
+    deps.peerIdentityMap.register(msg.from, {
+      agentId,
+      channel,
+      accountId,
+      sessionKey,
+    });
+  }
+
+  // Send local identity back to the remote peer
+  const localIdentity = buildIdentityMessage(
+    deps.localPeerId,
+    deps.localAgentId,
+    deps.localChannel,
+    deps.localAccountId,
+  );
+  await deps.send(msg.from, localIdentity);
+}

package/src/inbound.ts

@@ -1,17 +1,22 @@
 import type { P2PMessage } from "./types.js";
+import type { PeerIdentityMap } from "./peer-identity.ts";
+import type { PluginNextTurnInjection } from "openclaw/plugin-sdk/core";
 import { verifyInstanceSignature } from "./instance-id.js";
+import { buildAgentSessionKey } from "openclaw/plugin-sdk/core";
 
-export type InboundHandlerDeps = {
+export interface InboundHandlerDeps {
+  peerIdentityMap?: PeerIdentityMap;
+  enqueueNextTurnInjection?: (injection: PluginNextTurnInjection) => Promise<{ enqueued: boolean; id: string }>;
   logger?: {
     info?: (msg: string) => void;
     debug?: (msg: string) => void;
     warn?: (msg: string) => void;
     error?: (msg: string) => void;
   };
-};
+}
 
-export function handleP2PInbound(msg: P2PMessage, deps: InboundHandlerDeps): void {
-  const { logger } = deps;
+export function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDeps): void {
+  const logger = deps?.logger;
   const instanceTag = msg.instanceId ? ` [instance: ${msg.instanceId}]` : "";
   const signedTag = msg.signature ? " [signed]" : "";
 
@@ -28,7 +33,14 @@ export function handleP2PInbound(msg: P2PMessage, deps: InboundHandlerDeps): voi
       instanceId: msg.instanceId,
     });
     const valid = verifyInstanceSignature(
-      { id: msg.instanceId, name: "", pubkey: msg.pubkey, binding: "", bindingComponents: { username: "", hostname: "", platform: "" }, createdAt: 0 },
+      {
+        id: msg.instanceId,
+        name: "",
+        pubkey: msg.pubkey,
+        binding: "",
+        bindingComponents: { username: "", hostname: "", platform: "" },
+        createdAt: 0,
+      },
       signedPayload,
       msg.signature,
     );
@@ -41,6 +53,68 @@ export function handleP2PInbound(msg: P2PMessage, deps: InboundHandlerDeps): voi
     logger?.warn?.(`[libp2p-mesh] Message has signature but no pubkey; cannot verify`);
   }
 
+  // Relay handling when deps are provided with required fields
+  if (deps?.peerIdentityMap && deps?.enqueueNextTurnInjection) {
+    if (msg.type === "identity") {
+      // Parse remote identity payload and register synchronously
+      let parsed: { agentId?: string; channel?: string; accountId?: string } = {};
+      try {
+        parsed = JSON.parse(msg.payload);
+      } catch {
+        // Malformed payload — skip silently
+        return;
+      }
+
+      const { agentId, channel, accountId } = parsed;
+
+      if (agentId && channel && accountId) {
+        const sessionKey = buildAgentSessionKey({ agentId, channel, accountId });
+        deps.peerIdentityMap.register(msg.from, {
+          agentId,
+          channel,
+          accountId,
+          sessionKey,
+        });
+      }
+    } else if (msg.type === "direct") {
+      if (!msg.to) {
+        logger?.warn?.("[libp2p-mesh] Direct message missing 'to' field");
+      } else {
+        const receiver = deps.peerIdentityMap.resolve(msg.to);
+        if (!receiver) {
+          logger?.warn?.(`[libp2p-mesh] Unknown recipient peer: ${msg.to}`);
+        } else {
+          const sessionKey = buildAgentSessionKey({
+            agentId: receiver.agentId,
+            channel: receiver.channel,
+            accountId: receiver.accountId,
+          });
+          const text =
+            `【来自P2P网络的消息】\n来源：${msg.from}\n内容：${msg.payload}\n\n` +
+            `请你通过你当前的 channel 将此消息转发给你所服务的用户。转发完成后，请务必调用 p2p_send_message 工具向 ${msg.from} 回复送达确认。`;
+
+          deps.enqueueNextTurnInjection({ sessionKey, text, placement: "prepend_context" });
+        }
+      }
+    } else if (msg.type === "broadcast") {
+      const topic = msg.topic || "(none)";
+      const text =
+        `【来自P2P网络的广播消息】\n话题：${topic}\n来源：${msg.from}\n内容：${msg.payload}\n\n` +
+        `请你通过你当前的 channel 将此广播消息转发给你所服务的用户。`;
+
+      // Inject broadcast into each known peer's session
+      for (const [, identity] of deps.peerIdentityMap.entries()) {
+        const sessionKey = buildAgentSessionKey({
+          agentId: identity.agentId,
+          channel: identity.channel,
+          accountId: identity.accountId,
+        });
+        deps.enqueueNextTurnInjection({ sessionKey, text, placement: "prepend_context" });
+      }
+    }
+  }
+
+  // Original logging (unchanged)
   if (msg.type === "broadcast") {
     logger?.info?.(
       `[libp2p-mesh] Broadcast from ${msg.from}${instanceTag}${signedTag} on topic ${msg.topic ?? "(none)"}: ${msg.payload}`,

package/src/mesh.ts

@@ -257,12 +257,12 @@ export function createMeshNetwork(options: {
 
     state.node.addEventListener("peer:connect", (evt) => {
       const peerIdStr = evt.detail.toString();
-      logger?.debug?.(`[libp2p-mesh] Peer connected: ${peerIdStr}`);
+      logger?.info?.(`[libp2p-mesh] Peer connected: ${peerIdStr}`);
     });
 
     state.node.addEventListener("peer:disconnect", (evt) => {
       const peerIdStr = evt.detail.toString();
-      logger?.debug?.(`[libp2p-mesh] Peer disconnected: ${peerIdStr}`);
+      logger?.info?.(`[libp2p-mesh] Peer disconnected: ${peerIdStr}`);
     });
 
     await state.node.handle(

package/src/peer-identity.ts

@@ -0,0 +1,59 @@
+export interface PeerIdentity {
+  agentId: string;
+  channel: string;
+  accountId: string;
+  sessionKey: string;
+}
+
+export interface PeerIdentityMap {
+  register(peerId: string, identity: PeerIdentity): void;
+  resolve(peerId: string): PeerIdentity | undefined;
+  resolveSessionKey(peerId: string): string | undefined;
+  unregister(peerId: string): void;
+  setLocalIdentity(peerId: string, identity: PeerIdentity): void;
+  getLocalIdentity(): PeerIdentity | undefined;
+  hasIdentity(peerId: string): boolean;
+  entries(): IterableIterator<[string, PeerIdentity]>;
+}
+
+export function createPeerIdentityMap(): PeerIdentityMap {
+  const peers = new Map<string, PeerIdentity>();
+  let localPeerId: string | undefined;
+  let localIdentity: PeerIdentity | undefined;
+
+  return {
+    register(peerId: string, identity: PeerIdentity): void {
+      peers.set(peerId, identity);
+    },
+
+    resolve(peerId: string): PeerIdentity | undefined {
+      return peers.get(peerId);
+    },
+
+    resolveSessionKey(peerId: string): string | undefined {
+      return peers.get(peerId)?.sessionKey;
+    },
+
+    unregister(peerId: string): void {
+      peers.delete(peerId);
+    },
+
+    setLocalIdentity(peerId: string, identity: PeerIdentity): void {
+      localPeerId = peerId;
+      localIdentity = identity;
+      peers.set(peerId, identity);
+    },
+
+    getLocalIdentity(): PeerIdentity | undefined {
+      return localIdentity;
+    },
+
+    hasIdentity(peerId: string): boolean {
+      return peers.has(peerId);
+    },
+
+    entries(): IterableIterator<[string, PeerIdentity]> {
+      return peers.entries();
+    },
+  };
+}

package/src/plugin.ts

@@ -1,8 +1,10 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { OpenClawPluginApi, PluginNextTurnInjection } from "openclaw/plugin-sdk/core";
 import { createLibp2pMeshChannel } from "./channel.js";
 import { handleP2PInbound } from "./inbound.js";
 import { createMeshNetwork } from "./mesh.js";
 import { buildP2PTools } from "./agent-tools.js";
+import { createPeerIdentityMap } from "./peer-identity.js";
+import { buildIdentityMessage } from "./identity-exchange.js";
 import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
 import type { MeshConfig } from "./types.js";
 
@@ -12,14 +14,69 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
     logger: api.logger,
   });
 
+  // Singleton: maps peerId -> { agentId, channel, accountId, sessionKey }
+  const peerIdentityMap = createPeerIdentityMap();
+
+  // Helper: build the deps object for the relay-aware inbound handler
+  function buildInboundDeps() {
+    return {
+      peerIdentityMap,
+      enqueueNextTurnInjection: (injection: PluginNextTurnInjection) =>
+        api.session.workflow.enqueueNextTurnInjection(injection),
+      logger: api.logger,
+    };
+  }
+
   // 1. Register Service (manages libp2p node lifecycle)
   api.registerService({
     id: "libp2p-mesh",
     start: async () => {
       await mesh.start();
+
+      // Register local identity so remote peers can route messages back to us
+      const config = api.pluginConfig as MeshConfig | undefined;
+      const relayChannel = config?.relayChannel;
+      const relayAccountId = config?.relayAccountId;
+      if (relayChannel && relayAccountId) {
+        const localPeerId = mesh.getLocalPeerId();
+        const { buildAgentSessionKey } = await import("openclaw/plugin-sdk/core");
+        const sessionKey = buildAgentSessionKey({
+          agentId: api.name,
+          channel: relayChannel,
+          accountId: relayAccountId,
+        });
+        peerIdentityMap.setLocalIdentity(localPeerId, {
+          agentId: api.name,
+          channel: relayChannel,
+          accountId: relayAccountId,
+          sessionKey,
+        });
+        api.logger.info?.(
+          `[libp2p-mesh] Local identity registered: agent=${api.name}, channel=${relayChannel}, account=${relayAccountId}`,
+        );
+
+        // Announce identity to all currently-connected peers
+        const identityMsg = buildIdentityMessage(
+          localPeerId,
+          api.name,
+          relayChannel,
+          relayAccountId,
+        );
+        const connectedPeers = mesh.getConnectedPeers();
+        for (const peerId of connectedPeers) {
+          try {
+            await mesh.sendToPeer(peerId, JSON.stringify(identityMsg));
+          } catch {
+            // Best-effort; peer may be stale in the connection list
+          }
+        }
+      }
+
+      // Wire up relay-aware message handler
       mesh.onMessage((msg) => {
-        handleP2PInbound(msg, { logger: api.logger });
+        handleP2PInbound(msg, buildInboundDeps());
       });
+
       const identity = mesh.getInstanceIdentity();
       api.logger.info?.(`[libp2p-mesh] Service started. Peer ID: ${mesh.getLocalPeerId()}`);
       if (identity) {
@@ -54,11 +111,12 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
   // 3. Register Agent Tools
   const tools = buildP2PTools(mesh);
   for (const tool of tools) {
+    (tool as any).peerIdentityMap = peerIdentityMap;
     api.registerTool(tool as never);
   }
 
   // 4. Register Hook (log received messages for observability)
-  api.registerHook("message:received", async (event) => {
+  api.registerHook("message:received", async (event: any) => {
     const ctx = event.context as { channelId?: string } | undefined;
     api.logger.debug?.(`[libp2p-mesh] message received on channel ${ctx?.channelId ?? "unknown"}`);
   }, { name: "libp2p-mesh-message-received" });

package/src/types.ts

@@ -19,7 +19,7 @@ export interface InstanceIdentity {
 
 export interface P2PMessage {
   id: string;
-  type: "direct" | "broadcast" | "agent-sync";
+  type: "direct" | "broadcast" | "agent-sync" | "identity";
   from: string;
   to?: string;
   topic?: string;
@@ -89,6 +89,10 @@ export interface MeshConfig {
    * forward where AutoNAT cannot probe (e.g. behind a cloud LB).
    */
   announceAddrs?: string[];
+  /** Relay channel this agent is bound to (used for peer identity registration) */
+  relayChannel?: string;
+  /** Relay account this agent is bound to (used for peer identity registration) */
+  relayAccountId?: string;
 }
 
 export interface NATTraversalStatus {