libp2p-mesh 2026.5.20 → 2026.5.21

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

@@ -8,6 +8,12 @@ export interface IdentityExchangeDeps {
     localAccountId: string;
     localInstanceId?: string;
     send: (peerId: string, message: P2PMessage) => Promise<void>;
+    logger?: {
+        info?: (msg: string) => void;
+        debug?: (msg: string) => void;
+        warn?: (msg: string) => void;
+        error?: (msg: string) => void;
+    };
 }
 export declare function buildIdentityMessage(peerId: string, agentId: string, channel: string, accountId: string, instanceId?: string): P2PMessage;
 export declare function handleIdentityMessage(msg: P2PMessage, deps: IdentityExchangeDeps): Promise<void>;

package/dist/src/identity-exchange.js

@@ -8,6 +8,7 @@ export function buildIdentityMessage(peerId, agentId, channel, accountId, instan
     };
 }
 export async function handleIdentityMessage(msg, deps) {
+    const logger = deps.logger;
     // Parse remote identity payload
     let parsed = {};
     try {
@@ -22,15 +23,26 @@ export async function handleIdentityMessage(msg, deps) {
     if (agentId && channel && accountId) {
         const { buildAgentSessionKey } = await import("openclaw/plugin-sdk/core");
         const sessionKey = buildAgentSessionKey({ agentId, channel, accountId });
-        deps.peerIdentityMap.register(msg.from, {
+        await deps.peerIdentityMap.register(msg.from, {
             agentId,
             channel,
             accountId,
             sessionKey,
             instanceId,
         });
+        // Force immediate persistence so the identity is durable even if the
+        // process exits before the next save cycle.
+        await deps.peerIdentityMap.saveNow();
+        logger?.info?.(`[libp2p-mesh] Registered peer identity: ${msg.from} (agent=${agentId}, channel=${channel}, instanceId=${instanceId ?? "n/a"})`);
     }
-    // Send local identity back to the remote peer
+    // Send local identity back to the remote peer.
+    // We intentionally do NOT await this — the send callback (and any
+    // downstream identity handling it triggers) runs asynchronously and
+    // independently.  Awaiting would create a deep synchronous chain that
+    // blocks the caller; the recipient's handler will persist the reply on
+    // its own via saveNow().
     const localIdentity = buildIdentityMessage(deps.localPeerId, deps.localAgentId, deps.localChannel, deps.localAccountId, deps.localInstanceId);
-    await deps.send(msg.from, localIdentity);
+    deps.send(msg.from, localIdentity).catch((sendErr) => {
+        logger?.warn?.(`[libp2p-mesh] Failed to send identity reply to ${msg.from}: ${String(sendErr)}`);
+    });
 }

package/dist/src/inbound.d.ts

@@ -14,4 +14,4 @@ export interface InboundHandlerDeps {
         error?: (msg: string) => void;
     };
 }
-export declare function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDeps): void;
+export declare function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDeps): Promise<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) {
+import { handleIdentityMessage } from "./identity-exchange.js";
+export async function handleP2PInbound(msg, deps) {
     const logger = deps?.logger;
     const instanceTag = msg.instanceId ? ` [instance: ${msg.instanceId}]` : "";
     const signedTag = msg.signature ? " [signed]" : "";
@@ -32,31 +33,29 @@ export function handleP2PInbound(msg, deps) {
         }
     }
     else if (msg.signature) {
-        logger?.warn?.(`[libp2p-mesh] Message has signature but no pubkey; cannot verify`);
+        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 = {};
+            // Delegate full identity exchange (register + send reply) to the
+            // dedicated handler.  This ensures bidirectional identity propagation,
+            // forced persistence via saveNow(), and proper logging.
             try {
-                parsed = JSON.parse(msg.payload);
-            }
-            catch {
-                // Malformed payload — skip silently
-                return;
-            }
-            const { agentId, channel, accountId, instanceId } = parsed;
-            if (agentId && channel && accountId) {
-                const sessionKey = buildAgentSessionKey({ agentId, channel, accountId });
-                deps.peerIdentityMap.register(msg.from, {
-                    agentId,
-                    channel,
-                    accountId,
-                    sessionKey,
-                    instanceId,
+                await handleIdentityMessage(msg, {
+                    peerIdentityMap: deps.peerIdentityMap,
+                    localPeerId: deps.peerIdentityMap.getLocalIdentity()?.sessionKey ?? "",
+                    localAgentId: "",
+                    localChannel: "",
+                    localAccountId: "",
+                    localInstanceId: deps.peerIdentityMap.getLocalIdentity()?.instanceId,
+                    send: async () => { }, // no-op; reply is handled within handleIdentityMessage
+                    logger,
                 });
             }
+            catch (err) {
+                logger?.error?.(`[libp2p-mesh] Identity message handler error: ${String(err)}`);
+            }
         }
         else if (msg.type === "direct") {
             if (!msg.to) {
@@ -65,7 +64,25 @@ export function handleP2PInbound(msg, deps) {
             else {
                 const receiver = deps.peerIdentityMap.resolve(msg.to);
                 if (!receiver) {
-                    logger?.warn?.(`[libp2p-mesh] Unknown recipient peer: ${msg.to}`);
+                    // Fallback: check if the recipient is our own local identity.
+                    // setLocalIdentity stores the local peer separately (not in peers
+                    // Map) to avoid duplication, so direct messages addressed to
+                    // ourselves need this fallback to resolve correctly.
+                    const localPeerId = deps.peerIdentityMap.getLocalPeerId();
+                    const localId = deps.peerIdentityMap.getLocalIdentity();
+                    if (localId && msg.to === localPeerId) {
+                        const sessionKey = buildAgentSessionKey({
+                            agentId: localId.agentId,
+                            channel: localId.channel,
+                            accountId: localId.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 {
+                        logger?.warn?.(`[libp2p-mesh] Unknown recipient peer: ${msg.to}`);
+                    }
                 }
                 else {
                     const sessionKey = buildAgentSessionKey({
@@ -78,13 +95,50 @@ export function handleP2PInbound(msg, deps) {
                     deps.enqueueNextTurnInjection({ sessionKey, text, placement: "prepend_context" });
                 }
             }
+            // If the sender is not yet registered, register them synchronously
+            // (in-memory only) so that subsequent message routing works correctly.
+            // This handles NAT/relay scenarios where peer:connect may not fire
+            // bidirectionally, causing the identity exchange to be one-sided.
+            // Persistence (saveNow) is fire-and-forget to avoid blocking the
+            // message handler.
+            if (!deps.peerIdentityMap.hasIdentity(msg.from)) {
+                const localIdentity = deps.peerIdentityMap.getLocalIdentity();
+                if (localIdentity) {
+                    deps.peerIdentityMap.registerSync(msg.from, {
+                        agentId: localIdentity.agentId,
+                        channel: localIdentity.channel,
+                        accountId: localIdentity.accountId,
+                        sessionKey: "",
+                        instanceId: msg.instanceId,
+                    });
+                    deps.peerIdentityMap.saveNow().catch(() => { });
+                    logger?.debug?.(`[libp2p-mesh] Auto-registered unknown sender ${msg.from} from direct message`);
+                }
+            }
         }
         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()) {
+            // Inject broadcast into each known peer's session.
+            // Include remote peers from the peers Map, plus our own local identity
+            // (setLocalIdentity stores local separately to avoid duplication).
+            // Exclude the sender so they don't receive their own broadcast.
+            const seenPeers = new Set([msg.from]);
+            const localPeerId = deps.peerIdentityMap.getLocalPeerId();
+            const localIdentity = deps.peerIdentityMap.getLocalIdentity();
+            if (localPeerId && localIdentity && !seenPeers.has(localPeerId)) {
+                const sessionKey = buildAgentSessionKey({
+                    agentId: localIdentity.agentId,
+                    channel: localIdentity.channel,
+                    accountId: localIdentity.accountId,
+                });
+                deps.enqueueNextTurnInjection({ sessionKey, text, placement: "prepend_context" });
+                seenPeers.add(localPeerId);
+            }
+            for (const [peerId, identity] of deps.peerIdentityMap.entries()) {
+                if (seenPeers.has(peerId))
+                    continue;
                 const sessionKey = buildAgentSessionKey({
                     agentId: identity.agentId,
                     channel: identity.channel,
@@ -92,6 +146,21 @@ export function handleP2PInbound(msg, deps) {
                 });
                 deps.enqueueNextTurnInjection({ sessionKey, text, placement: "prepend_context" });
             }
+            // If the sender is not yet registered, register them synchronously
+            if (!deps.peerIdentityMap.hasIdentity(msg.from)) {
+                const localIdentity = deps.peerIdentityMap.getLocalIdentity();
+                if (localIdentity) {
+                    deps.peerIdentityMap.registerSync(msg.from, {
+                        agentId: localIdentity.agentId,
+                        channel: localIdentity.channel,
+                        accountId: localIdentity.accountId,
+                        sessionKey: "",
+                        instanceId: msg.instanceId,
+                    });
+                    deps.peerIdentityMap.saveNow().catch(() => { });
+                    logger?.debug?.(`[libp2p-mesh] Auto-registered unknown sender ${msg.from} from broadcast`);
+                }
+            }
         }
     }
     // Original logging (unchanged)

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

@@ -11,7 +11,9 @@ export interface PeerIdentity {
     lastSeen?: number;
 }
 export interface PeerIdentityMap {
-    register(peerId: string, identity: PeerIdentity): void;
+    register(peerId: string, identity: PeerIdentity): Promise<void>;
+    /** Synchronous in-memory registration without disk I/O */
+    registerSync(peerId: string, identity: PeerIdentity): void;
     resolve(peerId: string): PeerIdentity | undefined;
     resolveSessionKey(peerId: string): string | undefined;
     resolveByInstanceId(instanceId: string): {
@@ -21,9 +23,13 @@ export interface PeerIdentityMap {
     unregister(peerId: string): void;
     setLocalIdentity(peerId: string, identity: PeerIdentity): void;
     getLocalIdentity(): PeerIdentity | undefined;
+    /** Returns the peerId of the local node (if set) */
+    getLocalPeerId(): string | undefined;
     hasIdentity(peerId: string): boolean;
     entries(): IterableIterator<[string, PeerIdentity]>;
-    /** Persist current state to disk */
+    /** Force an immediate synchronous-style save (returns promise for await) */
+    saveNow(): Promise<void>;
+    /** Persist current state to disk (fire-and-forget, same as before) */
     save(): Promise<void>;
 }
 export declare function createPeerIdentityMap(storePath?: string): PeerIdentityMap & {

package/dist/src/peer-identity.js

@@ -8,7 +8,20 @@ export function createPeerIdentityMap(storePath) {
     let localPeerId;
     let localIdentity;
     const filePath = storePath ?? DEFAULT_STORE_PATH;
-    async function save() {
+    // Synchronous in-memory registration (no disk I/O).  Used as a fast-path
+    // when we need the entry to be visible immediately (e.g. routing a
+    // received message) and can persist to disk afterwards.
+    function doRegisterSync(peerId, identity) {
+        const now = Date.now();
+        const existing = peers.get(peerId);
+        identity.firstSeen = existing?.firstSeen ?? now;
+        identity.lastSeen = now;
+        peers.set(peerId, identity);
+        if (identity.instanceId) {
+            byInstanceId.set(identity.instanceId, { peerId, identity });
+        }
+    }
+    async function doSave() {
         const entries = {};
         for (const [peerId, identity] of peers.entries()) {
             entries[peerId] = identity;
@@ -23,8 +36,9 @@ export function createPeerIdentityMap(storePath) {
             await mkdir(path.dirname(filePath), { recursive: true });
             await writeFile(filePath, JSON.stringify(payload, null, 2), "utf-8");
         }
-        catch {
-            // Best-effort persistence; non-critical
+        catch (err) {
+            // Best-effort persistence; non-critical but surface unexpected errors
+            console.error(`[peer-identity] Failed to save identity map: ${String(err)}`);
         }
     }
     async function load() {
@@ -49,18 +63,18 @@ export function createPeerIdentityMap(storePath) {
         }
     }
     return {
-        async save() { await save(); },
+        async save() { await doSave(); },
+        /** Force an immediate save — caller can await for confirmation */
+        async saveNow() { await doSave(); },
         async load() { await load(); },
-        register(peerId, identity) {
-            const now = Date.now();
-            const existing = peers.get(peerId);
-            identity.firstSeen = existing?.firstSeen ?? now;
-            identity.lastSeen = now;
-            peers.set(peerId, identity);
-            if (identity.instanceId) {
-                byInstanceId.set(identity.instanceId, { peerId, identity });
-            }
-            save().catch(() => { });
+        async register(peerId, identity) {
+            doRegisterSync(peerId, identity);
+            await doSave();
+        },
+        /** Synchronous in-memory registration (no disk I/O).  Use this when the
+         *  entry must be visible immediately; call saveNow() afterwards to persist. */
+        registerSync(peerId, identity) {
+            doRegisterSync(peerId, identity);
         },
         resolve(peerId) {
             return peers.get(peerId);
@@ -84,19 +98,28 @@ export function createPeerIdentityMap(storePath) {
         },
         setLocalIdentity(peerId, identity) {
             localPeerId = peerId;
-            localIdentity = identity;
             const now = Date.now();
-            identity.firstSeen = now;
+            // Preserve firstSeen if the local identity was already loaded from disk
+            if (!localIdentity) {
+                identity.firstSeen = now;
+            }
+            else {
+                identity.firstSeen = localIdentity.firstSeen ?? now;
+            }
             identity.lastSeen = now;
-            peers.set(peerId, identity);
+            localIdentity = identity;
+            // Also index by instanceId so resolveByInstanceId works for local
             if (identity.instanceId) {
                 byInstanceId.set(identity.instanceId, { peerId, identity });
             }
-            save().catch(() => { });
+            doSave().catch(() => { });
         },
         getLocalIdentity() {
             return localIdentity;
         },
+        getLocalPeerId() {
+            return localPeerId;
+        },
         hasIdentity(peerId) {
             return peers.has(peerId);
         },

package/dist/src/plugin.js

@@ -1,5 +1,6 @@
 import { createLibp2pMeshChannel } from "./channel.js";
 import { handleP2PInbound } from "./inbound.js";
+import { handleIdentityMessage } from "./identity-exchange.js";
 import { createMeshNetwork } from "./mesh.js";
 import { buildP2PTools } from "./agent-tools.js";
 import { createPeerIdentityMap } from "./peer-identity.js";
@@ -41,6 +42,10 @@ export function registerLibp2pMesh(api) {
                     channel: relayChannel,
                     accountId: relayAccountId,
                 });
+                // setLocalIdentity stores the local identity separately (not in peers
+                // Map) to avoid duplication.  We also register in peers Map so
+                // direct messages addressed to us (msg.to === localPeerId) can be
+                // resolved by deps.peerIdentityMap.resolve() in handleP2PInbound.
                 peerIdentityMap.setLocalIdentity(localPeerId, {
                     agentId: api.name,
                     channel: relayChannel,
@@ -48,6 +53,13 @@ export function registerLibp2pMesh(api) {
                     sessionKey,
                     instanceId: localInstanceId,
                 });
+                await peerIdentityMap.register(localPeerId, {
+                    agentId: api.name,
+                    channel: relayChannel,
+                    accountId: relayAccountId,
+                    sessionKey,
+                    instanceId: localInstanceId,
+                });
                 api.logger.info?.(`[libp2p-mesh] Local identity registered: agent=${api.name}, channel=${relayChannel}, account=${relayAccountId}, instanceId=${localInstanceId}`);
                 // Announce identity to all currently-connected peers
                 const identityMsg = buildIdentityMessage(localPeerId, api.name, relayChannel, relayAccountId, localInstanceId);
@@ -61,6 +73,7 @@ export function registerLibp2pMesh(api) {
                 }
                 // When a new peer connects, send our identity to them
                 mesh.onPeerConnect((peerId) => {
+                    api.logger.info?.(`[libp2p-mesh] Peer connected: ${peerId} — sending identity`);
                     const msg = buildIdentityMessage(localPeerId, api.name, relayChannel, relayAccountId, localInstanceId);
                     mesh.sendToPeer(peerId, JSON.stringify(msg)).catch(() => {
                         // Best-effort
@@ -68,12 +81,38 @@ export function registerLibp2pMesh(api) {
                 });
                 // When a peer disconnects, clean up the identity map
                 mesh.onPeerDisconnect((peerId) => {
+                    api.logger.info?.(`[libp2p-mesh] Peer disconnected: ${peerId}`);
                     peerIdentityMap.unregister(peerId);
+                    peerIdentityMap.saveNow().catch(() => { });
                 });
             }
-            // Wire up relay-aware message handler
+            // Wire up relay-aware message handler.
+            // Identity messages get special treatment: they register the remote
+            // peer's identity, force immediate persistence via saveNow(), and
+            // automatically send our identity back — ensuring bidirectional
+            // identity exchange even when peer:connect events are one-sided
+            // (e.g. NAT/relay scenarios).
             mesh.onMessage((msg) => {
-                handleP2PInbound(msg, buildInboundDeps());
+                if (msg.type === "identity") {
+                    const localIdentity = peerIdentityMap.getLocalIdentity();
+                    handleIdentityMessage(msg, {
+                        peerIdentityMap,
+                        localPeerId,
+                        localAgentId: api.name,
+                        localChannel: relayChannel ?? "",
+                        localAccountId: relayAccountId ?? "",
+                        localInstanceId,
+                        send: async (targetPeerId, replyMsg) => {
+                            mesh.sendToPeer(targetPeerId, JSON.stringify(replyMsg)).catch(() => { });
+                        },
+                        logger: api.logger,
+                    }).catch((err) => {
+                        api.logger.error?.(`[libp2p-mesh] Identity exchange error: ${String(err)}`);
+                    });
+                }
+                else {
+                    handleP2PInbound(msg, buildInboundDeps());
+                }
             });
             const identity = mesh.getInstanceIdentity();
             api.logger.info?.(`[libp2p-mesh] Service started. Peer ID: ${localPeerId}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2p-mesh",
-  "version": "2026.5.20",
+  "version": "2026.5.21",
   "description": "OpenClaw libp2p P2P mesh network plugin for cross-instance agent communication",
   "type": "module",
   "main": "dist/index.js",

package/src/identity-exchange.ts

@@ -9,6 +9,12 @@ export interface IdentityExchangeDeps {
   localAccountId: string;
   localInstanceId?: string;
   send: (peerId: string, message: P2PMessage) => Promise<void>;
+  logger?: {
+    info?: (msg: string) => void;
+    debug?: (msg: string) => void;
+    warn?: (msg: string) => void;
+    error?: (msg: string) => void;
+  };
 }
 
 export function buildIdentityMessage(
@@ -31,6 +37,8 @@ export async function handleIdentityMessage(
   msg: P2PMessage,
   deps: IdentityExchangeDeps,
 ): Promise<void> {
+  const logger = deps.logger;
+
   // Parse remote identity payload
   let parsed: { agentId?: string; channel?: string; accountId?: string; instanceId?: string } = {};
   try {
@@ -46,16 +54,27 @@ export async function handleIdentityMessage(
   if (agentId && channel && accountId) {
     const { buildAgentSessionKey } = await import("openclaw/plugin-sdk/core");
     const sessionKey = buildAgentSessionKey({ agentId, channel, accountId });
-    deps.peerIdentityMap.register(msg.from, {
+    await deps.peerIdentityMap.register(msg.from, {
       agentId,
       channel,
       accountId,
       sessionKey,
       instanceId,
     });
+    // Force immediate persistence so the identity is durable even if the
+    // process exits before the next save cycle.
+    await deps.peerIdentityMap.saveNow();
+    logger?.info?.(
+      `[libp2p-mesh] Registered peer identity: ${msg.from} (agent=${agentId}, channel=${channel}, instanceId=${instanceId ?? "n/a"})`,
+    );
   }
 
-  // Send local identity back to the remote peer
+  // Send local identity back to the remote peer.
+  // We intentionally do NOT await this — the send callback (and any
+  // downstream identity handling it triggers) runs asynchronously and
+  // independently.  Awaiting would create a deep synchronous chain that
+  // blocks the caller; the recipient's handler will persist the reply on
+  // its own via saveNow().
   const localIdentity = buildIdentityMessage(
     deps.localPeerId,
     deps.localAgentId,
@@ -63,5 +82,9 @@ export async function handleIdentityMessage(
     deps.localAccountId,
     deps.localInstanceId,
   );
-  await deps.send(msg.from, localIdentity);
+  deps.send(msg.from, localIdentity).catch((sendErr) => {
+    logger?.warn?.(
+      `[libp2p-mesh] Failed to send identity reply to ${msg.from}: ${String(sendErr)}`,
+    );
+  });
 }

package/src/inbound.ts

@@ -3,6 +3,7 @@ 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";
+import { handleIdentityMessage } from "./identity-exchange.js";
 
 export interface InboundHandlerDeps {
   peerIdentityMap?: PeerIdentityMap;
@@ -15,7 +16,7 @@ export interface InboundHandlerDeps {
   };
 }
 
-export function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDeps): void {
+export async function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDeps): Promise<void> {
   const logger = deps?.logger;
   const instanceTag = msg.instanceId ? ` [instance: ${msg.instanceId}]` : "";
   const signedTag = msg.signature ? " [signed]" : "";
@@ -50,32 +51,28 @@ export function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDeps): vo
       logger?.warn?.(`[libp2p-mesh] Invalid signature from instance ${msg.instanceId}`);
     }
   } else if (msg.signature) {
-    logger?.warn?.(`[libp2p-mesh] Message has signature but no pubkey; cannot verify`);
+    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; instanceId?: string } = {};
+      // Delegate full identity exchange (register + send reply) to the
+      // dedicated handler.  This ensures bidirectional identity propagation,
+      // forced persistence via saveNow(), and proper logging.
       try {
-        parsed = JSON.parse(msg.payload);
-      } catch {
-        // Malformed payload — skip silently
-        return;
-      }
-
-      const { agentId, channel, accountId, instanceId } = parsed;
-
-      if (agentId && channel && accountId) {
-        const sessionKey = buildAgentSessionKey({ agentId, channel, accountId });
-        deps.peerIdentityMap.register(msg.from, {
-          agentId,
-          channel,
-          accountId,
-          sessionKey,
-          instanceId,
+        await handleIdentityMessage(msg, {
+          peerIdentityMap: deps.peerIdentityMap,
+          localPeerId: deps.peerIdentityMap.getLocalIdentity()?.sessionKey ?? "",
+          localAgentId: "",
+          localChannel: "",
+          localAccountId: "",
+          localInstanceId: deps.peerIdentityMap.getLocalIdentity()?.instanceId,
+          send: async () => {}, // no-op; reply is handled within handleIdentityMessage
+          logger,
         });
+      } catch (err) {
+        logger?.error?.(`[libp2p-mesh] Identity message handler error: ${String(err)}`);
       }
     } else if (msg.type === "direct") {
       if (!msg.to) {
@@ -83,7 +80,25 @@ export function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDeps): vo
       } else {
         const receiver = deps.peerIdentityMap.resolve(msg.to);
         if (!receiver) {
-          logger?.warn?.(`[libp2p-mesh] Unknown recipient peer: ${msg.to}`);
+          // Fallback: check if the recipient is our own local identity.
+          // setLocalIdentity stores the local peer separately (not in peers
+          // Map) to avoid duplication, so direct messages addressed to
+          // ourselves need this fallback to resolve correctly.
+          const localPeerId = deps.peerIdentityMap.getLocalPeerId();
+          const localId = deps.peerIdentityMap.getLocalIdentity();
+          if (localId && msg.to === localPeerId) {
+            const sessionKey = buildAgentSessionKey({
+              agentId: localId.agentId,
+              channel: localId.channel,
+              accountId: localId.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 {
+            logger?.warn?.(`[libp2p-mesh] Unknown recipient peer: ${msg.to}`);
+          }
         } else {
           const sessionKey = buildAgentSessionKey({
             agentId: receiver.agentId,
@@ -93,18 +108,56 @@ export function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDeps): vo
           const text =
             `【来自P2P网络的消息】\n来源：${msg.from}\n内容：${msg.payload}\n\n` +
             `请你通过你当前的 channel 将此消息转发给你所服务的用户。转发完成后，请务必调用 p2p_send_message 工具向 ${msg.from} 回复送达确认。`;
-
           deps.enqueueNextTurnInjection({ sessionKey, text, placement: "prepend_context" });
         }
       }
+
+      // If the sender is not yet registered, register them synchronously
+      // (in-memory only) so that subsequent message routing works correctly.
+      // This handles NAT/relay scenarios where peer:connect may not fire
+      // bidirectionally, causing the identity exchange to be one-sided.
+      // Persistence (saveNow) is fire-and-forget to avoid blocking the
+      // message handler.
+      if (!deps.peerIdentityMap.hasIdentity(msg.from)) {
+        const localIdentity = deps.peerIdentityMap.getLocalIdentity();
+        if (localIdentity) {
+          deps.peerIdentityMap.registerSync(msg.from, {
+            agentId: localIdentity.agentId,
+            channel: localIdentity.channel,
+            accountId: localIdentity.accountId,
+            sessionKey: "",
+            instanceId: msg.instanceId,
+          });
+          deps.peerIdentityMap.saveNow().catch(() => {});
+          logger?.debug?.(
+            `[libp2p-mesh] Auto-registered unknown sender ${msg.from} from direct message`,
+          );
+        }
+      }
     } 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()) {
+      // Inject broadcast into each known peer's session.
+      // Include remote peers from the peers Map, plus our own local identity
+      // (setLocalIdentity stores local separately to avoid duplication).
+      // Exclude the sender so they don't receive their own broadcast.
+      const seenPeers = new Set<string>([msg.from]);
+      const localPeerId = deps.peerIdentityMap.getLocalPeerId();
+      const localIdentity = deps.peerIdentityMap.getLocalIdentity();
+      if (localPeerId && localIdentity && !seenPeers.has(localPeerId)) {
+        const sessionKey = buildAgentSessionKey({
+          agentId: localIdentity.agentId,
+          channel: localIdentity.channel,
+          accountId: localIdentity.accountId,
+        });
+        deps.enqueueNextTurnInjection({ sessionKey, text, placement: "prepend_context" });
+        seenPeers.add(localPeerId);
+      }
+      for (const [peerId, identity] of deps.peerIdentityMap.entries()) {
+        if (seenPeers.has(peerId)) continue;
         const sessionKey = buildAgentSessionKey({
           agentId: identity.agentId,
           channel: identity.channel,
@@ -112,6 +165,24 @@ export function handleP2PInbound(msg: P2PMessage, deps?: InboundHandlerDeps): vo
         });
         deps.enqueueNextTurnInjection({ sessionKey, text, placement: "prepend_context" });
       }
+
+      // If the sender is not yet registered, register them synchronously
+      if (!deps.peerIdentityMap.hasIdentity(msg.from)) {
+        const localIdentity = deps.peerIdentityMap.getLocalIdentity();
+        if (localIdentity) {
+          deps.peerIdentityMap.registerSync(msg.from, {
+            agentId: localIdentity.agentId,
+            channel: localIdentity.channel,
+            accountId: localIdentity.accountId,
+            sessionKey: "",
+            instanceId: msg.instanceId,
+          });
+          deps.peerIdentityMap.saveNow().catch(() => {});
+          logger?.debug?.(
+            `[libp2p-mesh] Auto-registered unknown sender ${msg.from} from broadcast`,
+          );
+        }
+      }
     }
   }
 

package/src/peer-identity.ts

@@ -16,16 +16,22 @@ export interface PeerIdentity {
 }
 
 export interface PeerIdentityMap {
-  register(peerId: string, identity: PeerIdentity): void;
+  register(peerId: string, identity: PeerIdentity): Promise<void>;
+  /** Synchronous in-memory registration without disk I/O */
+  registerSync(peerId: string, identity: PeerIdentity): void;
   resolve(peerId: string): PeerIdentity | undefined;
   resolveSessionKey(peerId: string): string | undefined;
   resolveByInstanceId(instanceId: string): { peerId: string; identity: PeerIdentity } | undefined;
   unregister(peerId: string): void;
   setLocalIdentity(peerId: string, identity: PeerIdentity): void;
   getLocalIdentity(): PeerIdentity | undefined;
+  /** Returns the peerId of the local node (if set) */
+  getLocalPeerId(): string | undefined;
   hasIdentity(peerId: string): boolean;
   entries(): IterableIterator<[string, PeerIdentity]>;
-  /** Persist current state to disk */
+  /** Force an immediate synchronous-style save (returns promise for await) */
+  saveNow(): Promise<void>;
+  /** Persist current state to disk (fire-and-forget, same as before) */
   save(): Promise<void>;
 }
 
@@ -38,7 +44,21 @@ export function createPeerIdentityMap(storePath?: string): PeerIdentityMap & { l
   let localIdentity: PeerIdentity | undefined;
   const filePath = storePath ?? DEFAULT_STORE_PATH;
 
-  async function save(): Promise<void> {
+  // Synchronous in-memory registration (no disk I/O).  Used as a fast-path
+  // when we need the entry to be visible immediately (e.g. routing a
+  // received message) and can persist to disk afterwards.
+  function doRegisterSync(peerId: string, identity: PeerIdentity): void {
+    const now = Date.now();
+    const existing = peers.get(peerId);
+    identity.firstSeen = existing?.firstSeen ?? now;
+    identity.lastSeen = now;
+    peers.set(peerId, identity);
+    if (identity.instanceId) {
+      byInstanceId.set(identity.instanceId, { peerId, identity });
+    }
+  }
+
+  async function doSave(): Promise<void> {
     const entries: Record<string, PeerIdentity> = {};
     for (const [peerId, identity] of peers.entries()) {
       entries[peerId] = identity;
@@ -52,8 +72,9 @@ export function createPeerIdentityMap(storePath?: string): PeerIdentityMap & { l
     try {
       await mkdir(path.dirname(filePath), { recursive: true });
       await writeFile(filePath, JSON.stringify(payload, null, 2), "utf-8");
-    } catch {
-      // Best-effort persistence; non-critical
+    } catch (err) {
+      // Best-effort persistence; non-critical but surface unexpected errors
+      console.error(`[peer-identity] Failed to save identity map: ${String(err)}`);
     }
   }
 
@@ -76,20 +97,22 @@ export function createPeerIdentityMap(storePath?: string): PeerIdentityMap & { l
   }
 
   return {
-    async save() { await save(); },
+    async save() { await doSave(); },
+
+    /** Force an immediate save — caller can await for confirmation */
+    async saveNow() { await doSave(); },
 
     async load() { await load(); },
 
-    register(peerId: string, identity: PeerIdentity): void {
-      const now = Date.now();
-      const existing = peers.get(peerId);
-      identity.firstSeen = existing?.firstSeen ?? now;
-      identity.lastSeen = now;
-      peers.set(peerId, identity);
-      if (identity.instanceId) {
-        byInstanceId.set(identity.instanceId, { peerId, identity });
-      }
-      save().catch(() => {});
+    async register(peerId: string, identity: PeerIdentity): Promise<void> {
+      doRegisterSync(peerId, identity);
+      await doSave();
+    },
+
+    /** Synchronous in-memory registration (no disk I/O).  Use this when the
+     *  entry must be visible immediately; call saveNow() afterwards to persist. */
+    registerSync(peerId: string, identity: PeerIdentity): void {
+      doRegisterSync(peerId, identity);
     },
 
     resolve(peerId: string): PeerIdentity | undefined {
@@ -118,21 +141,30 @@ export function createPeerIdentityMap(storePath?: string): PeerIdentityMap & { l
 
     setLocalIdentity(peerId: string, identity: PeerIdentity): void {
       localPeerId = peerId;
-      localIdentity = identity;
       const now = Date.now();
-      identity.firstSeen = now;
+      // Preserve firstSeen if the local identity was already loaded from disk
+      if (!localIdentity) {
+        identity.firstSeen = now;
+      } else {
+        identity.firstSeen = localIdentity.firstSeen ?? now;
+      }
       identity.lastSeen = now;
-      peers.set(peerId, identity);
+      localIdentity = identity;
+      // Also index by instanceId so resolveByInstanceId works for local
       if (identity.instanceId) {
         byInstanceId.set(identity.instanceId, { peerId, identity });
       }
-      save().catch(() => {});
+      doSave().catch(() => {});
     },
 
     getLocalIdentity(): PeerIdentity | undefined {
       return localIdentity;
     },
 
+    getLocalPeerId(): string | undefined {
+      return localPeerId;
+    },
+
     hasIdentity(peerId: string): boolean {
       return peers.has(peerId);
     },

package/src/plugin.ts

@@ -1,6 +1,7 @@
 import type { OpenClawPluginApi, PluginNextTurnInjection } from "openclaw/plugin-sdk/core";
 import { createLibp2pMeshChannel } from "./channel.js";
 import { handleP2PInbound } from "./inbound.js";
+import { handleIdentityMessage } from "./identity-exchange.js";
 import { createMeshNetwork } from "./mesh.js";
 import { buildP2PTools } from "./agent-tools.js";
 import { createPeerIdentityMap } from "./peer-identity.js";
@@ -52,6 +53,10 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
           channel: relayChannel,
           accountId: relayAccountId,
         });
+        // setLocalIdentity stores the local identity separately (not in peers
+        // Map) to avoid duplication.  We also register in peers Map so
+        // direct messages addressed to us (msg.to === localPeerId) can be
+        // resolved by deps.peerIdentityMap.resolve() in handleP2PInbound.
         peerIdentityMap.setLocalIdentity(localPeerId, {
           agentId: api.name,
           channel: relayChannel,
@@ -59,6 +64,13 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
           sessionKey,
           instanceId: localInstanceId,
         });
+        await peerIdentityMap.register(localPeerId, {
+          agentId: api.name,
+          channel: relayChannel,
+          accountId: relayAccountId,
+          sessionKey,
+          instanceId: localInstanceId,
+        });
         api.logger.info?.(
           `[libp2p-mesh] Local identity registered: agent=${api.name}, channel=${relayChannel}, account=${relayAccountId}, instanceId=${localInstanceId}`,
         );
@@ -81,6 +93,7 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
 
         // When a new peer connects, send our identity to them
         mesh.onPeerConnect((peerId: string) => {
+          api.logger.info?.(`[libp2p-mesh] Peer connected: ${peerId} — sending identity`);
           const msg = buildIdentityMessage(
             localPeerId,
             api.name,
@@ -95,13 +108,38 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
 
         // When a peer disconnects, clean up the identity map
         mesh.onPeerDisconnect((peerId: string) => {
+          api.logger.info?.(`[libp2p-mesh] Peer disconnected: ${peerId}`);
           peerIdentityMap.unregister(peerId);
+          peerIdentityMap.saveNow().catch(() => {});
         });
       }
 
-      // Wire up relay-aware message handler
+      // Wire up relay-aware message handler.
+      // Identity messages get special treatment: they register the remote
+      // peer's identity, force immediate persistence via saveNow(), and
+      // automatically send our identity back — ensuring bidirectional
+      // identity exchange even when peer:connect events are one-sided
+      // (e.g. NAT/relay scenarios).
       mesh.onMessage((msg) => {
-        handleP2PInbound(msg, buildInboundDeps());
+        if (msg.type === "identity") {
+          const localIdentity = peerIdentityMap.getLocalIdentity();
+          handleIdentityMessage(msg, {
+            peerIdentityMap,
+            localPeerId,
+            localAgentId: api.name,
+            localChannel: relayChannel ?? "",
+            localAccountId: relayAccountId ?? "",
+            localInstanceId,
+            send: async (targetPeerId: string, replyMsg: any) => {
+              mesh.sendToPeer(targetPeerId, JSON.stringify(replyMsg)).catch(() => {});
+            },
+            logger: api.logger,
+          }).catch((err) => {
+            api.logger.error?.(`[libp2p-mesh] Identity exchange error: ${String(err)}`);
+          });
+        } else {
+          handleP2PInbound(msg, buildInboundDeps());
+        }
       });
 
       const identity = mesh.getInstanceIdentity();