openclaw - 💡(How to fix) Fix [Bug]: hooks.internal — TS handler entries silently fail to load, only bootstrap-extra-files actually fires

Summary

When configuring hooks.internal, only the bootstrap-extra-files entry type appears to actually take effect. Entries referencing a TypeScript handler module, or using extraDirs / installs keys, are silently ignored — no error in gateway logs, no warning in openclaw doctor, no rejection at config.patch time.

Discovered while wiring up a per-session reminder for an agent workflow. The TS handler under hooks.internal.entries.<name>.handler and the extraDirs reference (pointing to a directory of .md files) didn't inject anything. Switching the same content to bootstrap-extra-files: [<path>] worked immediately on hot-reload.

Environment

• OpenClaw 2026.5.28
• Windows 11 Pro 10.0.26200
• Node v24.11.1

Reproduction

1. Add a hooks.internal.entries.<id> block referencing a TS handler:

   {
     "hooks": {
       "internal": {
         "entries": {
           "self-improve": {
             "handler": "./hooks/self-improve.ts",
             "events": ["session.bootstrap"]
           }
         }
       }
     }
   }

2. Save (hot-reload accepted, no error in logs).
3. Start a new agent session — handler does not fire, no log lines for the entry.
4. Replace with "entries": { "self-improve": { "bootstrap-extra-files": ["./skills/self-improving-agent/AGENTS.md"] } }.
5. New session sees the file injected as expected.

Expected

Either:

• (a) all documented entry types work, or
• (b) unsupported entry types are rejected at config.patch time / surfaced as warnings in openclaw doctor so they're not silently broken.

Workaround

Use bootstrap-extra-files exclusively. (We adopted this and it works reliably.)

Suggested fix

• Add a schema validator for hooks.internal.entries.* that rejects unknown keys at patch time.
• Document the supported entry-type set in the configuration reference, with examples for each.

Related

• Adjacent: #86241 (preserveGatewayHookRunner handler stacking) — different surface, same general area.