From b9ad8fa8b29005ce3760521842239af22b90c9bf Mon Sep 17 00:00:00 2001
From: Yufeng He <40085740+he-yufeng@users.noreply.github.com>
Date: Fri, 12 Jun 2026 22:02:59 +0800
Subject: [PATCH] fix(openclaw): skip runtime setup during metadata
 registration (#5383)

---
 integrations/openclaw/index.test.ts           | 45 ++++++++++++++++++-
 integrations/openclaw/index.ts                | 16 +++++++
 .../openclaw/openclaw-plugin-sdk.d.ts         |  1 +
 3 files changed, 60 insertions(+), 2 deletions(-)

diff --git a/integrations/openclaw/index.test.ts b/integrations/openclaw/index.test.ts
index 3adf1666d..da86c5a7c 100644
--- a/integrations/openclaw/index.test.ts
+++ b/integrations/openclaw/index.test.ts
@@ -2,8 +2,8 @@
  * Regression tests for per-agent memory isolation helpers and
  * message filtering logic.
  */
-import { describe, it, expect } from "vitest";
-import {
+import { describe, it, expect, vi } from "vitest";
+import memoryPlugin, {
   extractAgentId,
   effectiveUserId,
   agentUserId,
@@ -16,6 +16,47 @@ import {
   filterMessagesForExtraction,
 } from "./index.ts";
 
+function createPluginApi(registrationMode?: string) {
+  return {
+    pluginConfig: {
+      mode: "platform",
+      apiKey: "test-api-key",
+      userId: "alice",
+    },
+    registrationMode,
+    logger: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    },
+    resolvePath: vi.fn((p: string) => p),
+    registerTool: vi.fn(),
+    on: vi.fn(),
+    registerCli: vi.fn(),
+    registerCommand: vi.fn(),
+    registerService: vi.fn(),
+    registerMemoryCapability: vi.fn(),
+  };
+}
+
+describe("plugin registration modes", () => {
+  it("keeps cli-metadata registration free of runtime side effects", () => {
+    const api = createPluginApi("cli-metadata");
+
+    memoryPlugin.register(api as any);
+
+    expect(api.registerCli).toHaveBeenCalledTimes(1);
+    expect(api.registerService).not.toHaveBeenCalled();
+    expect(api.registerMemoryCapability).not.toHaveBeenCalled();
+    expect(api.registerTool).not.toHaveBeenCalled();
+    expect(api.on).not.toHaveBeenCalled();
+    expect(api.logger.info).not.toHaveBeenCalledWith(
+      expect.stringContaining("openclaw-mem0: registered"),
+    );
+  });
+});
+
 // ---------------------------------------------------------------------------
 // extractAgentId
 // ---------------------------------------------------------------------------
diff --git a/integrations/openclaw/index.ts b/integrations/openclaw/index.ts
index 4b4c89041..31bd0e437 100644
--- a/integrations/openclaw/index.ts
+++ b/integrations/openclaw/index.ts
@@ -107,6 +107,7 @@ const memoryPlugin = definePluginEntry({
       baseUrl: pluginAuth.baseUrl,
     };
     const cfg = mem0ConfigSchema.parse(api.pluginConfig, fileConfig);
+    const isMetadataRegistration = api.registrationMode === "cli-metadata";
 
     // Telemetry context bound to this plugin instance's config
     const telemetryCtx = {
@@ -122,6 +123,21 @@ const memoryPlugin = definePluginEntry({
       }
     };
 
+    if (isMetadataRegistration) {
+      registerCliCommands(
+        api,
+        null as any,
+        null as any,
+        cfg,
+        () => cfg.userId,
+        (id: string) => `${cfg.userId}:agent:${id}`,
+        () => ({ user_id: cfg.userId, top_k: cfg.topK }),
+        () => undefined,
+        (cmd: string) => _captureEvent(`openclaw.cli.${cmd}`, { command: cmd }),
+      );
+      return;
+    }
+
     if (cfg.needsSetup) {
       api.logger.warn(
         "openclaw-mem0: API key not configured. Memory features are disabled.\n" +
diff --git a/integrations/openclaw/openclaw-plugin-sdk.d.ts b/integrations/openclaw/openclaw-plugin-sdk.d.ts
index 7484e4813..9854a5462 100644
--- a/integrations/openclaw/openclaw-plugin-sdk.d.ts
+++ b/integrations/openclaw/openclaw-plugin-sdk.d.ts
@@ -26,6 +26,7 @@ declare module "openclaw/plugin-sdk" {
 
   export interface OpenClawPluginApi {
     pluginConfig: Record<string, unknown>;
+    registrationMode?: "full" | "cli-metadata" | string;
     logger: {
       info(msg: string): void;
       warn(msg: string): void;