fix(hooks): preserve plugin-registered hooks across gateway startup reload

SidQin-cyber · cursoragent · SidQin-cyber · commit ee2530d5d519 · 2026-02-25T15:21:40.000+08:00
Plugins register internal hooks during loadGatewayPlugins(), but startGatewaySidecars() later calls clearInternalHooks() to reload file-based hook definitions, which wiped plugin handlers. Hooks registered via api.registerHook() appeared in `openclaw hooks list` but never fired. Introduce registerPluginHook() that tracks handlers separately. clearInternalHooks() now restores plugin handlers after clearing, so they survive the gateway startup reload cycle. Closes #25859 Co-authored-by: Cursor <cursoragent@cursor.com>
diff --git a/src/hooks/internal-hooks.test.ts b/src/hooks/internal-hooks.test.ts
@@ -8,6 +8,7 @@ import {
   isMessageReceivedEvent,
   isMessageSentEvent,
   registerInternalHook,
+  registerPluginHook,
   triggerInternalHook,
   unregisterInternalHook,
   type AgentBootstrapHookContext,
@@ -454,5 +455,28 @@ describe("hooks", () => {
       const keys = getRegisteredEventKeys();
       expect(keys).toEqual([]);
     });
+
+    it("should preserve plugin-registered handlers", async () => {
+      const pluginHandler = vi.fn();
+      const configHandler = vi.fn();
+
+      registerPluginHook("message:received", pluginHandler);
+      registerInternalHook("message:received", configHandler);
+
+      clearInternalHooks();
+
+      const keys = getRegisteredEventKeys();
+      expect(keys).toContain("message:received");
+
+      const event = createInternalHookEvent("message", "received", "test-session", {
+        from: "user1",
+        channelId: "telegram",
+        content: "hello",
+      });
+      await triggerInternalHook(event);
+
+      expect(pluginHandler).toHaveBeenCalledTimes(1);
+      expect(configHandler).not.toHaveBeenCalled();
+    });
   });
 });
diff --git a/src/hooks/internal-hooks.ts b/src/hooks/internal-hooks.ts
@@ -112,6 +112,8 @@ export type InternalHookHandler = (event: InternalHookEvent) => Promise<void> |
 
 /** Registry of hook handlers by event key */
 const handlers = new Map<string, InternalHookHandler[]>();
+/** Handlers registered by plugins survive clearInternalHooks() */
+const pluginHandlers = new Map<string, InternalHookHandler[]>();
 const log = createSubsystemLogger("internal-hooks");
 
 /**
@@ -140,6 +142,18 @@ export function registerInternalHook(eventKey: string, handler: InternalHookHand
   handlers.get(eventKey)!.push(handler);
 }
 
+/**
+ * Register a hook handler from a plugin.  Plugin-registered handlers are
+ * preserved when clearInternalHooks() is called during gateway startup.
+ */
+export function registerPluginHook(eventKey: string, handler: InternalHookHandler): void {
+  registerInternalHook(eventKey, handler);
+  if (!pluginHandlers.has(eventKey)) {
+    pluginHandlers.set(eventKey, []);
+  }
+  pluginHandlers.get(eventKey)!.push(handler);
+}
+
 /**
  * Unregister a specific hook handler
  *
@@ -164,10 +178,17 @@ export function unregisterInternalHook(eventKey: string, handler: InternalHookHa
 }
 
 /**
- * Clear all registered hooks (useful for testing)
+ * Clear config-loaded hooks while preserving plugin-registered handlers.
+ * Called during gateway startup to ensure fresh loading from disk-based
+ * hook definitions without losing hooks registered by plugins.
  */
 export function clearInternalHooks(): void {
   handlers.clear();
+  for (const [eventKey, list] of pluginHandlers) {
+    if (list.length > 0) {
+      handlers.set(eventKey, [...list]);
+    }
+  }
 }
 
 /**
diff --git a/src/plugins/registry.ts b/src/plugins/registry.ts
@@ -6,7 +6,7 @@ import type {
   GatewayRequestHandler,
   GatewayRequestHandlers,
 } from "../gateway/server-methods/types.js";
-import { registerInternalHook } from "../hooks/internal-hooks.js";
+import { registerPluginHook } from "../hooks/internal-hooks.js";
 import type { HookEntry } from "../hooks/types.js";
 import { resolveUserPath } from "../utils.js";
 import { registerPluginCommand } from "./commands.js";
@@ -262,7 +262,7 @@ export function createPluginRegistry(registryParams: PluginRegistryParams) {
     }
 
     for (const event of normalizedEvents) {
-      registerInternalHook(event, handler);
+      registerPluginHook(event, handler);
     }
   };
 
