Fixing Hooks That Are Not Found, Eligible, or Running
Diagnose hooks that go undiscovered, fail eligibility checks, or never execute. Useful for developers and operators debugging hook discovery and execution in OpenClaw.
Read this when
- `openclaw hooks list` does not show your hook
- A hook reports as not eligible and you need the blocking reason
- A hook is loaded but its side effect never appears
Troubleshooting a hook that goes undiscovered, fails eligibility, or never runs. This page belongs to the Hooks guide.
Troubleshooting
Hook not discovered
Inspect the report's workspaceDir and managedHooksDir by running
openclaw hooks list --json. Make sure the host, profile, and agent you are looking at are the ones you meant. A hook requires HOOK.md plus a single supported handler file; metadata on its own will not do. Collection locations only look at immediate children. Either an explicit extra path or a linked root may itself be a hook or a pack. When dealing with a pack, check that openclaw.hooks names the intended hook directories directly: nested packs and collections are skipped, and entries that get rejected will not cause unlisted children to be scanned.
Look through Gateway logs for duplicate names and containment warnings. A workspace hook has no power to override a bundled or managed hook. For extra directories and linked packs, confirm the root layout that Hook discovery describes.
Hook not eligible
openclaw hooks info my-hook
openclaw hooks list --verbose
Verify blockedReason, any binaries missing on the Gateway's PATH, the environment, config paths, and the OS. Until it is explicitly enabled, a workspace hook stays disabled. A hook that declares no events cannot be loaded. Requirements may pass in a report even though the module itself does not import successfully.
Hook not executing
Check hooks.internal.enabled, how the configured name is selected, and the hook's hookKey entry together with its reload mode. A ready report neither overrides the master switch nor the name selection, and it does not prove that another agent's workspace was loaded.
openclaw logs --follow
Watch for import/export errors, boundary failures, unknown-event warnings, or Hook error [<type>:<action>]. Fire the same event once more and confirm a hook-specific marker or artifact shows up. Plain chat text will not trigger command:new; hook replies are not sent by /stop; and a metadata subscription cannot conjure a custom trigger.
When the marker shows up but no chat reply follows, inspect the producer and route described in Reply delivery rather than checking enablement alone. With session-memory, let background writing complete, then examine the resolved agent workspace instead of assuming the default one.