libp2p-mesh 2026.6.13 → 2026.6.14

package/README.md

@@ -225,11 +225,34 @@ If `inboundTargets` is an empty array, inbound delivery is disabled. If `inbound
 | `relayList` | `string[]` | `[]` | Multiaddrs of relays to reserve a slot on |
 | `discoverRelays` | `number` | `0` | Auto-discover this many relays via content routing |
 | `announceAddrs` | `string[]` | `[]` | Extra multiaddrs to announce on top of auto-detected ones |
+| `announceLogDetail` | `"off" \| "summary" \| "payload"` | `"summary"` | Controls instance announce logging. `summary` logs peer, instance, address count, and attribute count; `payload` also logs the full announce JSON; `off` disables only the new announce summary/payload logs and keeps legacy/basic info logs. |
 | `inboundChannel` | `string` | `undefined` | OpenClaw channel used to display inbound P2P user messages, for example `"feishu"` |
 | `inboundTarget` | `string` | `undefined` | OpenClaw channel target for inbound P2P messages, for example `user:ou_xxx` or `chat:oc_xxx` |
 | `inboundTargets` | `array` | `undefined` | Optional list of receiver-owned channel targets for inbound P2P user messages. When present, it overrides `inboundChannel`/`inboundTarget`; an empty array disables inbound delivery. |
 | `deliveryAckTimeoutMs` | `number` | `15000` | Timeout for waiting on remote channel delivery ACKs |
 
+### Announce Startup and Logging
+
+During gateway startup, `libp2p-mesh` registers the instance router handlers and direct/broadcast inbound handlers before starting the mesh node. This makes early `instance-announce` messages observable as soon as peers connect, instead of waiting until after mesh startup has already completed.
+
+Instance announce logs are controlled by `plugins.entries["libp2p-mesh"].config.announceLogDetail`:
+
+- `summary` is the default. It logs send/receive direction, peer ID, instance ID, multiaddr count, and public attribute count. It does not print the full announce JSON.
+- `off` disables the new announce summary and payload logs. It still keeps legacy/basic info logs such as sent announce lines and instance mapping updates, along with warnings and errors.
+- `payload` logs the same summary plus the full announce JSON at debug level.
+
+Use the debug command to inspect or change this value:
+
+```bash
+openclaw libp2p-mesh debug
+```
+
+Full payload logging is intended for short-lived troubleshooting only. Announce payloads can include `userPublicAttributes`, peer multiaddrs, the instance pubkey, and instance identity fields. After changing the setting, restart the gateway for the new logging level to take effect:
+
+```bash
+openclaw gateway restart
+```
+
 ## NAT Traversal
 
 When both peers have a routable address (same LAN, public IPs, or working port-forwarding) no extra setup is needed. The defaults above kick in automatically:
@@ -616,6 +639,20 @@ Peer connection and disconnection are logged at `info` level:
 
 If these lines are missing, confirm the gateway is running with normal info logs enabled and that both instances are on the same mDNS, bootstrap, or relay network.
 
+### Instance announce routes are missing between two machines
+
+If peers connect but sending by OpenClaw instance ID fails or `instance-peer.json` is not updated, first confirm both gateways were restarted after the latest config change. On startup, the gateway now attaches the instance router plus inbound message handlers before starting the mesh, so early announces should be handled once the peer connection appears.
+
+For a short debug session on both computers:
+
+1. Run `openclaw libp2p-mesh debug`.
+2. Set `announceLogDetail` to `payload` and confirm the privacy warning.
+3. Restart both gateways with `openclaw gateway restart`.
+4. Watch for summary lines and debug lines containing full announce payload JSON.
+5. Return to `summary` or `off` with `openclaw libp2p-mesh debug`, then restart again.
+
+Full payload logs may expose `userPublicAttributes`, multiaddrs, pubkey, and instance identity, so avoid sharing these logs outside the debugging context.
+
 ## Architecture
 
 ```

package/dist/src/debug-cli.d.ts

@@ -0,0 +1,21 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { OpenClawPluginCliContext } from "openclaw/plugin-sdk/plugin-runtime";
+import type { SetupPrompter } from "./setup-wizard.js";
+import type { AnnounceLogDetail } from "./types.js";
+type CliRootCommand = {
+    command(name: string): {
+        description(text: string): {
+            action(handler: () => Promise<void>): void;
+        };
+    };
+};
+export type DebugConfigWriter = {
+    saveAnnounceLogDetail(detail: AnnounceLogDetail): Promise<void>;
+};
+export type DebugCliDeps = {
+    createPrompter?: (ctx: OpenClawPluginCliContext) => SetupPrompter;
+    createWriter?: (api: OpenClawPluginApi) => DebugConfigWriter;
+};
+export declare function registerLibp2pMeshDebugCli(api: OpenClawPluginApi, deps?: DebugCliDeps): void;
+export declare function registerLibp2pMeshDebugCommand(root: CliRootCommand, api: OpenClawPluginApi, ctx: OpenClawPluginCliContext, deps?: DebugCliDeps): void;
+export {};

package/dist/src/debug-cli.js

@@ -0,0 +1,54 @@
+import { createReadlinePrompter, LIBP2P_MESH_CLI_REGISTRATION, } from "./setup-cli.js";
+import { applyAnnounceLogDetail, getAnnounceLogDetail, } from "./setup-config.js";
+import { runDebugWizard } from "./debug-wizard.js";
+const DEBUG_CLI_AFTER_WRITE = {
+    mode: "none",
+    reason: "libp2p-mesh debug config updated; restart manually to apply gateway changes.",
+};
+export function registerLibp2pMeshDebugCli(api, deps = {}) {
+    api.registerCli((ctx) => {
+        const root = ctx.program
+            .command("libp2p-mesh")
+            .description("Configure libp2p-mesh plugin.");
+        registerLibp2pMeshDebugCommand(root, api, ctx, deps);
+    }, LIBP2P_MESH_CLI_REGISTRATION);
+}
+export function registerLibp2pMeshDebugCommand(root, api, ctx, deps = {}) {
+    root
+        .command("debug")
+        .description("Manage libp2p-mesh debug logging config.")
+        .action(async () => {
+        const prompter = (deps.createPrompter?.(ctx) ?? createReadlinePrompter());
+        const writer = deps.createWriter?.(api) ?? createOpenClawDebugConfigWriter(api);
+        try {
+            const result = await runDebugWizard({
+                prompter,
+                current: getAnnounceLogDetail(ctx.config),
+                writer,
+            });
+            prompter.print(result.message);
+        }
+        finally {
+            prompter.close?.();
+        }
+    });
+}
+function createOpenClawDebugConfigWriter(api) {
+    return {
+        async saveAnnounceLogDetail(detail) {
+            await api.runtime.config.mutateConfigFile({
+                afterWrite: DEBUG_CLI_AFTER_WRITE,
+                mutate(draft) {
+                    const nextConfig = applyAnnounceLogDetail(draft, detail);
+                    replaceConfig(draft, nextConfig);
+                },
+            });
+        },
+    };
+}
+function replaceConfig(draft, nextConfig) {
+    for (const key of Object.keys(draft)) {
+        delete draft[key];
+    }
+    Object.assign(draft, structuredClone(nextConfig));
+}

package/dist/src/debug-wizard.d.ts

@@ -0,0 +1,19 @@
+import { type SetupPrompter } from "./setup-wizard.js";
+import type { AnnounceLogDetail } from "./types.js";
+export type DebugPromptChoice = AnnounceLogDetail | "cancel";
+export type RunDebugWizardOptions = {
+    prompter: SetupPrompter;
+    current: AnnounceLogDetail;
+    writer: {
+        saveAnnounceLogDetail(detail: AnnounceLogDetail): Promise<void>;
+    };
+};
+export type DebugWizardResult = {
+    status: "saved";
+    announceLogDetail: AnnounceLogDetail;
+    message: string;
+} | {
+    status: "cancelled";
+    message: string;
+};
+export declare function runDebugWizard(options: RunDebugWizardOptions): Promise<DebugWizardResult>;

package/dist/src/debug-wizard.js

@@ -0,0 +1,41 @@
+import { SetupCancelledError } from "./setup-wizard.js";
+const CANCELLED_MESSAGE = "Debug configuration cancelled. No changes were written.";
+const SAVED_MESSAGE = "Debug config updated.\n\nRestart the gateway to apply changes:\nopenclaw gateway restart";
+export async function runDebugWizard(options) {
+    try {
+        options.prompter.print(`Current announceLogDetail: ${options.current}`);
+        const selected = await options.prompter.select("Set announceLogDetail:", [
+            { label: "summary: log peer, instance, address and attribute counts", value: "summary" },
+            { label: "off: disable announce summary/payload logs", value: "off" },
+            { label: "payload: log full announce JSON", value: "payload" },
+            { label: "Cancel", value: "cancel" },
+        ]);
+        if (selected === "cancel") {
+            return cancelledResult();
+        }
+        if (selected === "payload") {
+            const confirmed = await options.prompter.confirm("Full announce payload logs may include userPublicAttributes, multiaddrs, pubkey and instance identity. Enable payload logs?", false);
+            if (!confirmed) {
+                return cancelledResult();
+            }
+        }
+        await options.writer.saveAnnounceLogDetail(selected);
+        return {
+            status: "saved",
+            announceLogDetail: selected,
+            message: SAVED_MESSAGE,
+        };
+    }
+    catch (error) {
+        if (error instanceof SetupCancelledError) {
+            return cancelledResult();
+        }
+        throw error;
+    }
+}
+function cancelledResult() {
+    return {
+        status: "cancelled",
+        message: CANCELLED_MESSAGE,
+    };
+}

package/dist/src/instance-router.js

@@ -14,6 +14,17 @@ function isNonEmptyString(value) {
 function summarizeError(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function effectiveAnnounceLogDetail(value) {
+    if (value === "off" || value === "payload") {
+        return value;
+    }
+    return "summary";
+}
+function countAnnounceAttributes(payload) {
+    return Array.isArray(payload.userPublicAttributes)
+        ? payload.userPublicAttributes.length
+        : 0;
+}
 function describeAttributeMatch(match) {
     if (match.kind === "tag") {
         return `tag ${match.value}`;
@@ -81,6 +92,7 @@ export function createInstanceRouter(options) {
     const { mesh, store, delivery } = options;
     const config = options.config ?? {};
     const logger = options.logger;
+    const announceLogDetail = effectiveAnnounceLogDetail(config.announceLogDetail);
     const ackTimeoutMs = config.deliveryAckTimeoutMs ?? 15000;
     const announcedPeers = new Set();
     const pendingAcks = new Map();
@@ -133,7 +145,29 @@ export function createInstanceRouter(options) {
             payload: JSON.stringify(payload),
         });
         announcedPeers.add(peerId);
-        logger?.info?.(`[libp2p-mesh] Sent instance announce to ${peerId} (${payload.instanceId})`);
+        logAnnounce("Sent", peerId, payload);
+    }
+    function announceSummary(direction, peerId, payload, changed) {
+        const changedDetail = changed === undefined ? "" : ` changed=${changed}`;
+        return `[libp2p-mesh] ${direction} instance announce peer=${peerId} instance=${payload.instanceId} addrs=${payload.multiaddrs.length} attrs=${countAnnounceAttributes(payload)}${changedDetail}`;
+    }
+    function logAnnounce(direction, peerId, payload, changed) {
+        if (announceLogDetail === "off") {
+            if (direction === "Sent") {
+                logger?.info?.(`[libp2p-mesh] Sent instance announce to ${peerId} (${payload.instanceId})`);
+            }
+            return;
+        }
+        logger?.info?.(announceSummary(direction, peerId, payload, changed));
+        if (announceLogDetail !== "payload") {
+            return;
+        }
+        try {
+            logger?.debug?.(`[libp2p-mesh] ${direction} instance announce payload=${JSON.stringify(payload)}`);
+        }
+        catch {
+            return;
+        }
     }
     async function announceToConnectedPeers() {
         for (const peerId of mesh.getConnectedPeers()) {
@@ -163,9 +197,7 @@ export function createInstanceRouter(options) {
         if (result.changed) {
             logger?.info?.(`[libp2p-mesh] Instance mapping updated: ${payload.instanceId} -> ${payload.peerId}`);
         }
-        else {
-            logger?.debug?.(`[libp2p-mesh] Instance mapping unchanged: ${payload.instanceId}`);
-        }
+        logAnnounce("Received", msg.from, payload, result.changed);
         if (!announcedPeers.has(msg.from)) {
             await announceToPeer(msg.from).catch((error) => {
                 logger?.warn?.(`[libp2p-mesh] Failed to respond to announce from ${msg.from}: ${summarizeError(error)}`);
@@ -328,7 +360,10 @@ export function createInstanceRouter(options) {
             handleAck(msg);
         }
     }
-    async function start() {
+    function attachHandlers() {
+        if (unsubs.length > 0) {
+            return;
+        }
         unsubs.push(mesh.onMessage((msg) => {
             handleMessage(msg).catch((error) => {
                 logger?.error?.(`[libp2p-mesh] Instance router message error: ${summarizeError(error)}`);
@@ -339,6 +374,9 @@ export function createInstanceRouter(options) {
                 logger?.warn?.(`[libp2p-mesh] Failed to announce to connected peer ${peerId}: ${summarizeError(error)}`);
             });
         }));
+    }
+    async function start() {
+        attachHandlers();
         await announceToConnectedPeers();
     }
     async function stop() {
@@ -505,6 +543,8 @@ export function createInstanceRouter(options) {
         };
     }
     return {
+        attachHandlers,
+        announceToConnectedPeers,
         start,
         stop,
         handleMessage,

package/dist/src/plugin.d.ts

@@ -1,2 +1,9 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { createInstanceRouter } from "./instance-router.js";
+import { createMeshNetwork } from "./mesh.js";
+export type Libp2pMeshPluginDeps = {
+    createMeshNetwork?: typeof createMeshNetwork;
+    createInstanceRouter?: typeof createInstanceRouter;
+};
 export declare function registerLibp2pMesh(api: OpenClawPluginApi): void;
+export declare function registerLibp2pMeshWithDeps(api: OpenClawPluginApi, deps?: Libp2pMeshPluginDeps): void;

package/dist/src/plugin.js

@@ -9,11 +9,15 @@ import { createUserProfileStore } from "./user-profile-store.js";
 import { buildP2PTools } from "./agent-tools.js";
 import { registerLibp2pMeshCli } from "./profile-cli.js";
 export function registerLibp2pMesh(api) {
+    registerLibp2pMeshWithDeps(api);
+}
+export function registerLibp2pMeshWithDeps(api, deps = {}) {
     registerLibp2pMeshCli(api);
     const config = api.pluginConfig;
     let unsubscribeInbound;
     let serviceStarted = false;
-    const mesh = createMeshNetwork({
+    let startPromise;
+    const mesh = (deps.createMeshNetwork ?? createMeshNetwork)({
         config,
         logger: api.logger,
     });
@@ -32,7 +36,7 @@ export function registerLibp2pMesh(api) {
         },
         logger: api.logger,
     });
-    const router = createInstanceRouter({
+    const router = (deps.createInstanceRouter ?? createInstanceRouter)({
         mesh,
         store,
         delivery,
@@ -42,6 +46,62 @@ export function registerLibp2pMesh(api) {
         userProfileStore,
     });
     const channel = createLibp2pMeshChannel(mesh);
+    function attachInboundHandlers() {
+        return mesh.onMessage((msg) => {
+            if (msg.type === "direct" || msg.type === "broadcast") {
+                const sendToChannel = async (_channelId, _target, text) => {
+                    if (!config?.inboundChannel || !config?.inboundTarget) {
+                        api.logger.warn?.("[libp2p-mesh] inboundChannel/inboundTarget not configured; direct message logged only.");
+                        return;
+                    }
+                    const result = await delivery.deliver({
+                        channel: config.inboundChannel,
+                        target: config.inboundTarget,
+                        text,
+                        metadata: {
+                            fromInstanceId: msg.instanceId ?? msg.from,
+                            fromPeerId: msg.from,
+                            p2pMessageId: msg.id,
+                            allowAgentAutoReply: false,
+                            replyToInstanceId: msg.instanceId ?? msg.from,
+                            replyTool: "p2p_send_instance_message",
+                        },
+                    });
+                    if (!result.ok) {
+                        api.logger.error?.(`[libp2p-mesh] Failed to forward direct message from ${msg.from}: ${result.error}`);
+                    }
+                };
+                handleP2PInbound(msg, { logger: api.logger, sendToChannel });
+            }
+            else if (msg.type === "agent-sync") {
+                handleP2PInbound(msg, { logger: api.logger });
+            }
+        });
+    }
+    async function cleanupStartupFailure() {
+        try {
+            unsubscribeInbound?.();
+        }
+        catch (error) {
+            api.logger.warn?.(`[libp2p-mesh] Failed to clean inbound handler after startup failure: ${String(error)}`);
+        }
+        finally {
+            unsubscribeInbound = undefined;
+        }
+        try {
+            await router.stop();
+        }
+        catch (error) {
+            api.logger.warn?.(`[libp2p-mesh] Failed to stop router after startup failure: ${String(error)}`);
+        }
+        try {
+            await mesh.stop();
+        }
+        catch (error) {
+            api.logger.warn?.(`[libp2p-mesh] Failed to stop mesh after startup failure: ${String(error)}`);
+        }
+        serviceStarted = false;
+    }
     // 1. Register Service (manages libp2p node lifecycle)
     api.registerService({
         id: "libp2p-mesh",
@@ -50,56 +110,45 @@ export function registerLibp2pMesh(api) {
                 api.logger.debug?.("[libp2p-mesh] Service already started; ignoring duplicate start.");
                 return;
             }
-            await mesh.start();
-            await router.start();
-            unsubscribeInbound = mesh.onMessage((msg) => {
-                if (msg.type === "direct" || msg.type === "broadcast") {
-                    const sendToChannel = async (_channelId, _target, text) => {
-                        if (!config?.inboundChannel || !config?.inboundTarget) {
-                            api.logger.warn?.("[libp2p-mesh] inboundChannel/inboundTarget not configured; direct message logged only.");
-                            return;
-                        }
-                        const result = await delivery.deliver({
-                            channel: config.inboundChannel,
-                            target: config.inboundTarget,
-                            text,
-                            metadata: {
-                                fromInstanceId: msg.instanceId ?? msg.from,
-                                fromPeerId: msg.from,
-                                p2pMessageId: msg.id,
-                                allowAgentAutoReply: false,
-                                replyToInstanceId: msg.instanceId ?? msg.from,
-                                replyTool: "p2p_send_instance_message",
-                            },
-                        });
-                        if (!result.ok) {
-                            api.logger.error?.(`[libp2p-mesh] Failed to forward direct message from ${msg.from}: ${result.error}`);
-                        }
-                    };
-                    handleP2PInbound(msg, { logger: api.logger, sendToChannel });
+            if (startPromise) {
+                api.logger.debug?.("[libp2p-mesh] Service start already in progress; waiting for it.");
+                return startPromise;
+            }
+            startPromise = (async () => {
+                try {
+                    router.attachHandlers();
+                    unsubscribeInbound = attachInboundHandlers();
+                    await mesh.start();
+                    await router.announceToConnectedPeers();
+                    const identity = mesh.getInstanceIdentity();
+                    api.logger.info?.(`[libp2p-mesh] Service started. Peer ID: ${mesh.getLocalPeerId()}`);
+                    if (identity) {
+                        api.logger.info?.(`[libp2p-mesh] Instance Identity: ${identity.id}`);
+                    }
+                    const nat = mesh.getNATStatus();
+                    const enabledNames = Object.entries(nat.enabled)
+                        .filter(([, on]) => on)
+                        .map(([k]) => k);
+                    if (enabledNames.length > 0) {
+                        api.logger.info?.(`[libp2p-mesh] NAT traversal services: ${enabledNames.join(", ")}`);
+                    }
+                    if (nat.reservedRelays.length > 0) {
+                        api.logger.info?.(`[libp2p-mesh] Active relay reservations: ${nat.reservedRelays.join(", ")}`);
+                    }
+                    serviceStarted = true;
                 }
-                else if (msg.type === "agent-sync") {
-                    handleP2PInbound(msg, { logger: api.logger });
+                catch (error) {
+                    await cleanupStartupFailure();
+                    throw error;
                 }
-            });
-            const identity = mesh.getInstanceIdentity();
-            api.logger.info?.(`[libp2p-mesh] Service started. Peer ID: ${mesh.getLocalPeerId()}`);
-            if (identity) {
-                api.logger.info?.(`[libp2p-mesh] Instance Identity: ${identity.id}`);
-            }
-            const nat = mesh.getNATStatus();
-            const enabledNames = Object.entries(nat.enabled)
-                .filter(([, on]) => on)
-                .map(([k]) => k);
-            if (enabledNames.length > 0) {
-                api.logger.info?.(`[libp2p-mesh] NAT traversal services: ${enabledNames.join(", ")}`);
-            }
-            if (nat.reservedRelays.length > 0) {
-                api.logger.info?.(`[libp2p-mesh] Active relay reservations: ${nat.reservedRelays.join(", ")}`);
-            }
-            serviceStarted = true;
+                finally {
+                    startPromise = undefined;
+                }
+            })();
+            return startPromise;
         },
         stop: async () => {
+            await startPromise?.catch(() => undefined);
             unsubscribeInbound?.();
             unsubscribeInbound = undefined;
             await router.stop();

package/dist/src/profile-cli.d.ts

@@ -1,6 +1,7 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 import type { OpenClawPluginCliContext } from "openclaw/plugin-sdk/plugin-runtime";
 import { type SetupCliDeps } from "./setup-cli.js";
+import { type DebugCliDeps } from "./debug-cli.js";
 import { type UserProfileStore } from "./user-profile-store.js";
 import type { SetupPrompter } from "./setup-wizard.js";
 type CliRootCommand = {
@@ -20,6 +21,7 @@ export type ProfileCliDeps = {
 export type Libp2pMeshCliDeps = {
     setup?: SetupCliDeps;
     profile?: ProfileCliDeps;
+    debug?: DebugCliDeps;
 };
 export declare function registerLibp2pMeshCli(api: OpenClawPluginApi, deps?: Libp2pMeshCliDeps): void;
 export declare function registerLibp2pMeshProfileCli(api: OpenClawPluginApi, deps?: ProfileCliDeps): void;

package/dist/src/profile-cli.js

@@ -1,4 +1,5 @@
 import { createReadlinePrompter, LIBP2P_MESH_CLI_REGISTRATION, registerLibp2pMeshSetupCommand, } from "./setup-cli.js";
+import { registerLibp2pMeshDebugCommand } from "./debug-cli.js";
 import { runProfileWizard } from "./profile-wizard.js";
 import { createUserMdAttributeSource } from "./user-md-attributes.js";
 import { createUserProfileStore } from "./user-profile-store.js";
@@ -9,6 +10,7 @@ export function registerLibp2pMeshCli(api, deps = {}) {
             .description("Configure libp2p-mesh plugin.");
         registerLibp2pMeshSetupCommand(root, api, ctx, deps.setup);
         registerLibp2pMeshProfileCommand(root, api, ctx, deps.profile);
+        registerLibp2pMeshDebugCommand(root, api, ctx, deps.debug);
     }, LIBP2P_MESH_CLI_REGISTRATION);
 }
 export function registerLibp2pMeshProfileCli(api, deps = {}) {

package/dist/src/setup-config.d.ts

@@ -1,4 +1,4 @@
-import type { InboundTargetConfig, MeshConfig } from "./types.js";
+import type { AnnounceLogDetail, InboundTargetConfig, MeshConfig } from "./types.js";
 export declare const LIBP2P_MESH_PLUGIN_ID = "libp2p-mesh";
 export declare const DEFAULT_DELIVERY_ACK_TIMEOUT_MS = 15000;
 export type SetupMode = "lan" | "cross-network" | "relay-node" | "tools-only";
@@ -32,11 +32,14 @@ export type AddInboundTargetResult = {
 };
 export type LegacyInboundMigrationMode = "convert" | "keep" | "replace";
 export declare function getLibp2pMeshConfig(config: OpenClawConfigLike): MeshConfig | undefined;
+export declare function getAnnounceLogDetail(config: OpenClawConfigLike): AnnounceLogDetail;
+export declare function normalizeAnnounceLogDetail(value: unknown): AnnounceLogDetail;
 export declare function buildNetworkConfig(mode: SetupMode, options?: {
     crossNetwork?: CrossNetworkOptions;
     relayNode?: RelayNodeOptions;
 }): MeshConfig;
 export declare function applyPluginConfig(config: OpenClawConfigLike, pluginConfig: MeshConfig): OpenClawConfigLike;
+export declare function applyAnnounceLogDetail(config: OpenClawConfigLike, announceLogDetail: AnnounceLogDetail): OpenClawConfigLike;
 export declare function mergeNetworkConfig(existing: MeshConfig | undefined, networkConfig: MeshConfig): MeshConfig;
 export declare function listConfiguredChannels(config: OpenClawConfigLike): string[];
 export declare function generateInboundTargetId(channel: string, existingTargets: InboundTargetConfig[]): string;

package/dist/src/setup-config.js

@@ -3,6 +3,12 @@ export const DEFAULT_DELIVERY_ACK_TIMEOUT_MS = 15000;
 export function getLibp2pMeshConfig(config) {
     return config.plugins?.entries?.[LIBP2P_MESH_PLUGIN_ID]?.config;
 }
+export function getAnnounceLogDetail(config) {
+    return normalizeAnnounceLogDetail(getLibp2pMeshConfig(config)?.announceLogDetail);
+}
+export function normalizeAnnounceLogDetail(value) {
+    return value === "off" || value === "payload" || value === "summary" ? value : "summary";
+}
 export function buildNetworkConfig(mode, options) {
     switch (mode) {
         case "lan":
@@ -53,6 +59,27 @@ export function applyPluginConfig(config, pluginConfig) {
         },
     };
 }
+export function applyAnnounceLogDetail(config, announceLogDetail) {
+    const existingEntry = config.plugins?.entries?.[LIBP2P_MESH_PLUGIN_ID];
+    const existingPluginConfig = existingEntry?.config ?? {};
+    return {
+        ...config,
+        plugins: {
+            ...config.plugins,
+            entries: {
+                ...config.plugins?.entries,
+                [LIBP2P_MESH_PLUGIN_ID]: {
+                    ...existingEntry,
+                    enabled: existingEntry?.enabled ?? true,
+                    config: {
+                        ...existingPluginConfig,
+                        announceLogDetail,
+                    },
+                },
+            },
+        },
+    };
+}
 export function mergeNetworkConfig(existing, networkConfig) {
     if (!existing) {
         return { ...networkConfig };

package/dist/src/types.d.ts

@@ -180,6 +180,8 @@ export type InstanceRouterOptions = {
     };
 };
 export interface InstanceRouter {
+    attachHandlers(): void;
+    announceToConnectedPeers(): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
     handleMessage(msg: P2PMessage): Promise<void>;
@@ -206,6 +208,7 @@ export interface MeshConfig {
     discovery?: "mdns" | "bootstrap" | "dht";
     bootstrapList?: string[];
     meshTopic?: string;
+    announceLogDetail?: AnnounceLogDetail;
     enableAgentSync?: boolean;
     enableWebSocket?: boolean;
     peerIdPath?: string;
@@ -299,6 +302,7 @@ export interface MeshNetwork {
     /** Inspect which NAT-traversal services are running and whether any relay reservations are active */
     getNATStatus(): NATTraversalStatus;
 }
+export type AnnounceLogDetail = "off" | "summary" | "payload";
 export type MeshAccount = {
     accountId: string;
     configured: boolean;

package/openclaw.plugin.json

@@ -35,6 +35,12 @@
             "type": "string",
             "default": "openclaw-mesh"
           },
+          "announceLogDetail": {
+            "type": "string",
+            "enum": ["off", "summary", "payload"],
+            "default": "summary",
+            "description": "Controls instance announce logging detail."
+          },
           "inboundTargets": {
             "type": "array",
             "items": {
@@ -82,6 +88,12 @@
         "type": "string",
         "default": "openclaw-mesh"
       },
+      "announceLogDetail": {
+        "type": "string",
+        "enum": ["off", "summary", "payload"],
+        "default": "summary",
+        "description": "Controls instance announce logging detail."
+      },
       "enablePubsub": {
         "type": "boolean",
         "default": true

package/package.json

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

package/src/debug-cli.ts

@@ -0,0 +1,93 @@
+import type { OpenClawConfig, OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { OpenClawPluginCliContext } from "openclaw/plugin-sdk/plugin-runtime";
+import {
+  createReadlinePrompter,
+  LIBP2P_MESH_CLI_REGISTRATION,
+  type ClosableSetupPrompter,
+} from "./setup-cli.js";
+import {
+  applyAnnounceLogDetail,
+  getAnnounceLogDetail,
+  type OpenClawConfigLike,
+} from "./setup-config.js";
+import type { SetupPrompter } from "./setup-wizard.js";
+import { runDebugWizard } from "./debug-wizard.js";
+import type { AnnounceLogDetail } from "./types.js";
+
+const DEBUG_CLI_AFTER_WRITE = {
+  mode: "none",
+  reason: "libp2p-mesh debug config updated; restart manually to apply gateway changes.",
+} as const;
+
+type CliRootCommand = {
+  command(name: string): {
+    description(text: string): {
+      action(handler: () => Promise<void>): void;
+    };
+  };
+};
+
+export type DebugConfigWriter = {
+  saveAnnounceLogDetail(detail: AnnounceLogDetail): Promise<void>;
+};
+
+export type DebugCliDeps = {
+  createPrompter?: (ctx: OpenClawPluginCliContext) => SetupPrompter;
+  createWriter?: (api: OpenClawPluginApi) => DebugConfigWriter;
+};
+
+export function registerLibp2pMeshDebugCli(api: OpenClawPluginApi, deps: DebugCliDeps = {}): void {
+  api.registerCli((ctx) => {
+    const root = ctx.program
+      .command("libp2p-mesh")
+      .description("Configure libp2p-mesh plugin.");
+
+    registerLibp2pMeshDebugCommand(root, api, ctx, deps);
+  }, LIBP2P_MESH_CLI_REGISTRATION);
+}
+
+export function registerLibp2pMeshDebugCommand(
+  root: CliRootCommand,
+  api: OpenClawPluginApi,
+  ctx: OpenClawPluginCliContext,
+  deps: DebugCliDeps = {},
+): void {
+  root
+    .command("debug")
+    .description("Manage libp2p-mesh debug logging config.")
+    .action(async () => {
+      const prompter = (deps.createPrompter?.(ctx) ?? createReadlinePrompter()) as ClosableSetupPrompter;
+      const writer = deps.createWriter?.(api) ?? createOpenClawDebugConfigWriter(api);
+      try {
+        const result = await runDebugWizard({
+          prompter,
+          current: getAnnounceLogDetail(ctx.config as OpenClawConfigLike),
+          writer,
+        });
+        prompter.print(result.message);
+      } finally {
+        prompter.close?.();
+      }
+    });
+}
+
+function createOpenClawDebugConfigWriter(api: OpenClawPluginApi): DebugConfigWriter {
+  return {
+    async saveAnnounceLogDetail(detail) {
+      await api.runtime.config.mutateConfigFile({
+        afterWrite: DEBUG_CLI_AFTER_WRITE,
+        mutate(draft) {
+          const nextConfig = applyAnnounceLogDetail(draft as OpenClawConfigLike, detail);
+          replaceConfig(draft as OpenClawConfig, nextConfig as OpenClawConfig);
+        },
+      });
+    },
+  };
+}
+
+function replaceConfig(draft: OpenClawConfig, nextConfig: OpenClawConfig): void {
+  for (const key of Object.keys(draft) as Array<keyof OpenClawConfig>) {
+    delete draft[key];
+  }
+  Object.assign(draft, structuredClone(nextConfig));
+}

package/src/debug-wizard.ts

@@ -0,0 +1,64 @@
+import { SetupCancelledError, type SetupPrompter } from "./setup-wizard.js";
+import type { AnnounceLogDetail } from "./types.js";
+
+const CANCELLED_MESSAGE = "Debug configuration cancelled. No changes were written.";
+const SAVED_MESSAGE = "Debug config updated.\n\nRestart the gateway to apply changes:\nopenclaw gateway restart";
+
+export type DebugPromptChoice = AnnounceLogDetail | "cancel";
+
+export type RunDebugWizardOptions = {
+  prompter: SetupPrompter;
+  current: AnnounceLogDetail;
+  writer: {
+    saveAnnounceLogDetail(detail: AnnounceLogDetail): Promise<void>;
+  };
+};
+
+export type DebugWizardResult =
+  | { status: "saved"; announceLogDetail: AnnounceLogDetail; message: string }
+  | { status: "cancelled"; message: string };
+
+export async function runDebugWizard(options: RunDebugWizardOptions): Promise<DebugWizardResult> {
+  try {
+    options.prompter.print(`Current announceLogDetail: ${options.current}`);
+    const selected = await options.prompter.select<DebugPromptChoice>("Set announceLogDetail:", [
+      { label: "summary: log peer, instance, address and attribute counts", value: "summary" },
+      { label: "off: disable announce summary/payload logs", value: "off" },
+      { label: "payload: log full announce JSON", value: "payload" },
+      { label: "Cancel", value: "cancel" },
+    ]);
+
+    if (selected === "cancel") {
+      return cancelledResult();
+    }
+
+    if (selected === "payload") {
+      const confirmed = await options.prompter.confirm(
+        "Full announce payload logs may include userPublicAttributes, multiaddrs, pubkey and instance identity. Enable payload logs?",
+        false,
+      );
+      if (!confirmed) {
+        return cancelledResult();
+      }
+    }
+
+    await options.writer.saveAnnounceLogDetail(selected);
+    return {
+      status: "saved",
+      announceLogDetail: selected,
+      message: SAVED_MESSAGE,
+    };
+  } catch (error) {
+    if (error instanceof SetupCancelledError) {
+      return cancelledResult();
+    }
+    throw error;
+  }
+}
+
+function cancelledResult(): DebugWizardResult {
+  return {
+    status: "cancelled",
+    message: CANCELLED_MESSAGE,
+  };
+}

package/src/instance-router.ts

@@ -1,4 +1,5 @@
 import type {
+  AnnounceLogDetail,
   DeliveryAckPayload,
   DeliveryTargetResult,
   InboundTargetConfig,
@@ -50,6 +51,20 @@ function summarizeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+function effectiveAnnounceLogDetail(value: unknown): AnnounceLogDetail {
+  if (value === "off" || value === "payload") {
+    return value;
+  }
+
+  return "summary";
+}
+
+function countAnnounceAttributes(payload: InstanceAnnouncePayload): number {
+  return Array.isArray(payload.userPublicAttributes)
+    ? payload.userPublicAttributes.length
+    : 0;
+}
+
 function describeAttributeMatch(match: UserAttributeMatch): string {
   if (match.kind === "tag") {
     return `tag ${match.value}`;
@@ -149,6 +164,7 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
   const { mesh, store, delivery } = options;
   const config = options.config ?? {};
   const logger = options.logger;
+  const announceLogDetail = effectiveAnnounceLogDetail(config.announceLogDetail);
   const ackTimeoutMs = config.deliveryAckTimeoutMs ?? 15000;
   const announcedPeers = new Set<string>();
   const pendingAcks = new Map<string, PendingAck>();
@@ -212,9 +228,46 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
       payload: JSON.stringify(payload),
     });
     announcedPeers.add(peerId);
-    logger?.info?.(
-      `[libp2p-mesh] Sent instance announce to ${peerId} (${payload.instanceId})`,
-    );
+    logAnnounce("Sent", peerId, payload);
+  }
+
+  function announceSummary(
+    direction: "Sent" | "Received",
+    peerId: string,
+    payload: InstanceAnnouncePayload,
+    changed?: boolean,
+  ): string {
+    const changedDetail = changed === undefined ? "" : ` changed=${changed}`;
+    return `[libp2p-mesh] ${direction} instance announce peer=${peerId} instance=${payload.instanceId} addrs=${payload.multiaddrs.length} attrs=${countAnnounceAttributes(payload)}${changedDetail}`;
+  }
+
+  function logAnnounce(
+    direction: "Sent" | "Received",
+    peerId: string,
+    payload: InstanceAnnouncePayload,
+    changed?: boolean,
+  ): void {
+    if (announceLogDetail === "off") {
+      if (direction === "Sent") {
+        logger?.info?.(
+          `[libp2p-mesh] Sent instance announce to ${peerId} (${payload.instanceId})`,
+        );
+      }
+      return;
+    }
+
+    logger?.info?.(announceSummary(direction, peerId, payload, changed));
+    if (announceLogDetail !== "payload") {
+      return;
+    }
+
+    try {
+      logger?.debug?.(
+        `[libp2p-mesh] ${direction} instance announce payload=${JSON.stringify(payload)}`,
+      );
+    } catch {
+      return;
+    }
   }
 
   async function announceToConnectedPeers(): Promise<void> {
@@ -255,9 +308,8 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
       logger?.info?.(
         `[libp2p-mesh] Instance mapping updated: ${payload.instanceId} -> ${payload.peerId}`,
       );
-    } else {
-      logger?.debug?.(`[libp2p-mesh] Instance mapping unchanged: ${payload.instanceId}`);
     }
+    logAnnounce("Received", msg.from, payload, result.changed);
 
     if (!announcedPeers.has(msg.from)) {
       await announceToPeer(msg.from).catch((error) => {
@@ -449,7 +501,11 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
     }
   }
 
-  async function start(): Promise<void> {
+  function attachHandlers(): void {
+    if (unsubs.length > 0) {
+      return;
+    }
+
     unsubs.push(
       mesh.onMessage((msg) => {
         handleMessage(msg).catch((error) => {
@@ -468,7 +524,10 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
         });
       }),
     );
+  }
 
+  async function start(): Promise<void> {
+    attachHandlers();
     await announceToConnectedPeers();
   }
 
@@ -658,6 +717,8 @@ export function createInstanceRouter(options: InstanceRouterOptions): InstanceRo
   }
 
   return {
+    attachHandlers,
+    announceToConnectedPeers,
     start,
     stop,
     handleMessage,

package/src/plugin.ts

@@ -12,13 +12,26 @@ import { registerLibp2pMeshCli } from "./profile-cli.js";
 import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
 import type { MeshConfig } from "./types.js";
 
+export type Libp2pMeshPluginDeps = {
+  createMeshNetwork?: typeof createMeshNetwork;
+  createInstanceRouter?: typeof createInstanceRouter;
+};
+
 export function registerLibp2pMesh(api: OpenClawPluginApi) {
+  registerLibp2pMeshWithDeps(api);
+}
+
+export function registerLibp2pMeshWithDeps(
+  api: OpenClawPluginApi,
+  deps: Libp2pMeshPluginDeps = {},
+) {
   registerLibp2pMeshCli(api);
 
   const config = api.pluginConfig as MeshConfig | undefined;
   let unsubscribeInbound: (() => void) | undefined;
   let serviceStarted = false;
-  const mesh = createMeshNetwork({
+  let startPromise: Promise<void> | undefined;
+  const mesh = (deps.createMeshNetwork ?? createMeshNetwork)({
     config,
     logger: api.logger,
   });
@@ -39,7 +52,7 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
     },
     logger: api.logger,
   });
-  const router = createInstanceRouter({
+  const router = (deps.createInstanceRouter ?? createInstanceRouter)({
     mesh,
     store,
     delivery,
@@ -51,6 +64,73 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
 
   const channel = createLibp2pMeshChannel(mesh);
 
+  function attachInboundHandlers(): () => void {
+    return mesh.onMessage((msg) => {
+      if (msg.type === "direct" || msg.type === "broadcast") {
+        const sendToChannel: InboundHandlerDeps["sendToChannel"] = async (_channelId, _target, text) => {
+          if (!config?.inboundChannel || !config?.inboundTarget) {
+            api.logger.warn?.(
+              "[libp2p-mesh] inboundChannel/inboundTarget not configured; direct message logged only.",
+            );
+            return;
+          }
+
+          const result = await delivery.deliver({
+            channel: config.inboundChannel,
+            target: config.inboundTarget,
+            text,
+            metadata: {
+              fromInstanceId: msg.instanceId ?? msg.from,
+              fromPeerId: msg.from,
+              p2pMessageId: msg.id,
+              allowAgentAutoReply: false,
+              replyToInstanceId: msg.instanceId ?? msg.from,
+              replyTool: "p2p_send_instance_message",
+            },
+          });
+          if (!result.ok) {
+            api.logger.error?.(
+              `[libp2p-mesh] Failed to forward direct message from ${msg.from}: ${result.error}`,
+            );
+          }
+        };
+        handleP2PInbound(msg, { logger: api.logger, sendToChannel });
+      } else if (msg.type === "agent-sync") {
+        handleP2PInbound(msg, { logger: api.logger });
+      }
+    });
+  }
+
+  async function cleanupStartupFailure(): Promise<void> {
+    try {
+      unsubscribeInbound?.();
+    } catch (error) {
+      api.logger.warn?.(
+        `[libp2p-mesh] Failed to clean inbound handler after startup failure: ${String(error)}`,
+      );
+    } finally {
+      unsubscribeInbound = undefined;
+    }
+
+    try {
+      await router.stop();
+    } catch (error) {
+      api.logger.warn?.(
+        `[libp2p-mesh] Failed to stop router after startup failure: ${String(error)}`,
+      );
+    }
+
+    try {
+      await mesh.stop();
+    } catch (error) {
+      api.logger.warn?.(
+        `[libp2p-mesh] Failed to stop mesh after startup failure: ${String(error)}`,
+      );
+    }
+
+    serviceStarted = false;
+  }
+
   // 1. Register Service (manages libp2p node lifecycle)
   api.registerService({
     id: "libp2p-mesh",
@@ -59,64 +139,52 @@ export function registerLibp2pMesh(api: OpenClawPluginApi) {
         api.logger.debug?.("[libp2p-mesh] Service already started; ignoring duplicate start.");
         return;
       }
-      await mesh.start();
-      await router.start();
-      unsubscribeInbound = mesh.onMessage((msg) => {
-        if (msg.type === "direct" || msg.type === "broadcast") {
-          const sendToChannel: InboundHandlerDeps["sendToChannel"] = async (_channelId, _target, text) => {
-            if (!config?.inboundChannel || !config?.inboundTarget) {
-              api.logger.warn?.(
-                "[libp2p-mesh] inboundChannel/inboundTarget not configured; direct message logged only.",
-              );
-              return;
-            }
-
-            const result = await delivery.deliver({
-              channel: config.inboundChannel,
-              target: config.inboundTarget,
-              text,
-              metadata: {
-                fromInstanceId: msg.instanceId ?? msg.from,
-                fromPeerId: msg.from,
-                p2pMessageId: msg.id,
-                allowAgentAutoReply: false,
-                replyToInstanceId: msg.instanceId ?? msg.from,
-                replyTool: "p2p_send_instance_message",
-              },
-            });
-            if (!result.ok) {
-              api.logger.error?.(
-                `[libp2p-mesh] Failed to forward direct message from ${msg.from}: ${result.error}`,
-              );
-            }
-          };
-          handleP2PInbound(msg, { logger: api.logger, sendToChannel });
-        } else if (msg.type === "agent-sync") {
-          handleP2PInbound(msg, { logger: api.logger });
-        }
-      });
-      const identity = mesh.getInstanceIdentity();
-      api.logger.info?.(`[libp2p-mesh] Service started. Peer ID: ${mesh.getLocalPeerId()}`);
-      if (identity) {
-        api.logger.info?.(`[libp2p-mesh] Instance Identity: ${identity.id}`);
-      }
-      const nat = mesh.getNATStatus();
-      const enabledNames = Object.entries(nat.enabled)
-        .filter(([, on]) => on)
-        .map(([k]) => k);
-      if (enabledNames.length > 0) {
-        api.logger.info?.(
-          `[libp2p-mesh] NAT traversal services: ${enabledNames.join(", ")}`,
-        );
-      }
-      if (nat.reservedRelays.length > 0) {
-        api.logger.info?.(
-          `[libp2p-mesh] Active relay reservations: ${nat.reservedRelays.join(", ")}`,
-        );
+
+      if (startPromise) {
+        api.logger.debug?.("[libp2p-mesh] Service start already in progress; waiting for it.");
+        return startPromise;
       }
-      serviceStarted = true;
+
+      startPromise = (async () => {
+        try {
+          router.attachHandlers();
+          unsubscribeInbound = attachInboundHandlers();
+          await mesh.start();
+          await router.announceToConnectedPeers();
+          const identity = mesh.getInstanceIdentity();
+          api.logger.info?.(
+            `[libp2p-mesh] Service started. Peer ID: ${mesh.getLocalPeerId()}`,
+          );
+          if (identity) {
+            api.logger.info?.(`[libp2p-mesh] Instance Identity: ${identity.id}`);
+          }
+          const nat = mesh.getNATStatus();
+          const enabledNames = Object.entries(nat.enabled)
+            .filter(([, on]) => on)
+            .map(([k]) => k);
+          if (enabledNames.length > 0) {
+            api.logger.info?.(
+              `[libp2p-mesh] NAT traversal services: ${enabledNames.join(", ")}`,
+            );
+          }
+          if (nat.reservedRelays.length > 0) {
+            api.logger.info?.(
+              `[libp2p-mesh] Active relay reservations: ${nat.reservedRelays.join(", ")}`,
+            );
+          }
+          serviceStarted = true;
+        } catch (error) {
+          await cleanupStartupFailure();
+          throw error;
+        } finally {
+          startPromise = undefined;
+        }
+      })();
+
+      return startPromise;
     },
     stop: async () => {
+      await startPromise?.catch(() => undefined);
       unsubscribeInbound?.();
       unsubscribeInbound = undefined;
       await router.stop();

package/src/profile-cli.ts

@@ -7,6 +7,7 @@ import {
   type ClosableSetupPrompter,
   type SetupCliDeps,
 } from "./setup-cli.js";
+import { registerLibp2pMeshDebugCommand, type DebugCliDeps } from "./debug-cli.js";
 import { runProfileWizard } from "./profile-wizard.js";
 import { createUserMdAttributeSource } from "./user-md-attributes.js";
 import { createUserProfileStore, type UserProfileStore } from "./user-profile-store.js";
@@ -29,6 +30,7 @@ export type ProfileCliDeps = {
 export type Libp2pMeshCliDeps = {
   setup?: SetupCliDeps;
   profile?: ProfileCliDeps;
+  debug?: DebugCliDeps;
 };
 
 export function registerLibp2pMeshCli(api: OpenClawPluginApi, deps: Libp2pMeshCliDeps = {}): void {
@@ -39,6 +41,7 @@ export function registerLibp2pMeshCli(api: OpenClawPluginApi, deps: Libp2pMeshCl
 
     registerLibp2pMeshSetupCommand(root, api, ctx, deps.setup);
     registerLibp2pMeshProfileCommand(root, api, ctx, deps.profile);
+    registerLibp2pMeshDebugCommand(root, api, ctx, deps.debug);
   }, LIBP2P_MESH_CLI_REGISTRATION);
 }
 

package/src/setup-config.ts

@@ -1,4 +1,4 @@
-import type { InboundTargetConfig, MeshConfig } from "./types.js";
+import type { AnnounceLogDetail, InboundTargetConfig, MeshConfig } from "./types.js";
 
 export const LIBP2P_MESH_PLUGIN_ID = "libp2p-mesh";
 export const DEFAULT_DELIVERY_ACK_TIMEOUT_MS = 15000;
@@ -38,6 +38,14 @@ export function getLibp2pMeshConfig(config: OpenClawConfigLike): MeshConfig | un
   return config.plugins?.entries?.[LIBP2P_MESH_PLUGIN_ID]?.config as MeshConfig | undefined;
 }
 
+export function getAnnounceLogDetail(config: OpenClawConfigLike): AnnounceLogDetail {
+  return normalizeAnnounceLogDetail(getLibp2pMeshConfig(config)?.announceLogDetail);
+}
+
+export function normalizeAnnounceLogDetail(value: unknown): AnnounceLogDetail {
+  return value === "off" || value === "payload" || value === "summary" ? value : "summary";
+}
+
 export function buildNetworkConfig(
   mode: SetupMode,
   options?: {
@@ -99,6 +107,32 @@ export function applyPluginConfig(config: OpenClawConfigLike, pluginConfig: Mesh
   };
 }
 
+export function applyAnnounceLogDetail(
+  config: OpenClawConfigLike,
+  announceLogDetail: AnnounceLogDetail,
+): OpenClawConfigLike {
+  const existingEntry = config.plugins?.entries?.[LIBP2P_MESH_PLUGIN_ID];
+  const existingPluginConfig = existingEntry?.config ?? {};
+
+  return {
+    ...config,
+    plugins: {
+      ...config.plugins,
+      entries: {
+        ...config.plugins?.entries,
+        [LIBP2P_MESH_PLUGIN_ID]: {
+          ...existingEntry,
+          enabled: existingEntry?.enabled ?? true,
+          config: {
+            ...existingPluginConfig,
+            announceLogDetail,
+          },
+        },
+      },
+    },
+  };
+}
+
 export function mergeNetworkConfig(existing: MeshConfig | undefined, networkConfig: MeshConfig): MeshConfig {
   if (!existing) {
     return { ...networkConfig };

package/src/types.ts

@@ -203,6 +203,8 @@ export type InstanceRouterOptions = {
 };
 
 export interface InstanceRouter {
+  attachHandlers(): void;
+  announceToConnectedPeers(): Promise<void>;
   start(): Promise<void>;
   stop(): Promise<void>;
   handleMessage(msg: P2PMessage): Promise<void>;
@@ -232,6 +234,7 @@ export interface MeshConfig {
   discovery?: "mdns" | "bootstrap" | "dht";
   bootstrapList?: string[];
   meshTopic?: string;
+  announceLogDetail?: AnnounceLogDetail;
   enableAgentSync?: boolean;
   enableWebSocket?: boolean;
   peerIdPath?: string;
@@ -335,6 +338,8 @@ export interface MeshNetwork {
   getNATStatus(): NATTraversalStatus;
 }
 
+export type AnnounceLogDetail = "off" | "summary" | "payload";
+
 export type MeshAccount = {
   accountId: string;
   configured: boolean;