Summary

Plugin api.registerHook("message:received", ...) shows up in openclaw hooks list but never fires (likely cleared at gateway startup)

Version
OpenClaw 2026.2.23

When registering an internal hook from a plugin via api.registerHook("message:received", ...), the hook is visible in openclaw hooks list/info as “Managed by plugin”, but it never triggers on inbound messages. In contrast, the plugin lifecycle hook api.on("message_received", ...) works fine.

This makes api.registerHook(...) look supported but non-functional for runtime events.

Config
Internal hooks enabled:
hooks: {
internal: {
enabled: true,
entries: {
boot-md: { enabled: true },
bootstrap-extra-files: { enabled: true },
command-logger: { enabled: true },
session-memory: { enabled: true },
},
},
},

Steps to reproduce

1. Create a plugin (e.g. ~/.openclaw/extensions/x402/index.ts) and register a hook:
   export default function register(api) {
   api.registerHook(
   "message:received",
   async () => {
   api.logger.warn("[x402] Message received, running hook");
   },
   {
   name: "x402.message-received",
   description: "Runs when a message is received",
   },
   );
   }

2. Restart gateway.

3. Verify it appears:

openclaw hooks info x402.message-received
Source: openclaw-plugin (x402)
Events: message:received
Managed by plugin; enable/disable via hooks CLI not available.

4. Send any inbound message (e.g. Telegram DM/group).

Workaround that works
Using plugin lifecycle hook works immediately:

Expected behavior

Expected
The handler logs "[x402] Message received, running hook" (and/or otherwise runs) for inbound messages.

Actual behavior

Actual
No log output; handler does not appear to run, despite being listed as registered.

Work Around:
api.on("message_received", async (event, _) => {
api.logger.info([x402] inbound message: ${event.content});
});

Logs show:
[hooks] running message_received (1 handlers)
[x402] inbound message: test

OpenClaw version

2026.2.23

Operating system

Ubuntu 24.04.4 LTS

Install method

No response

Logs, screenshots, and evidence

Impact and severity

No response

Additional information

Suspected cause (implementation detail)
It looks like plugin registerHook(...) registers into the internal hook registry during plugin load, but later gateway startup clears/reloads internal hooks (HOOK.md system), wiping plugin-registered internal handlers.

If correct, either:
plugins should register internal hooks after the clear/reload step, or
internal hook clearing should preserve plugin-registered handlers, or
plugin api.registerHook should be documented as “listing-only” (if intentional), or removed/changed.