How to Use OpenClaw Hooks

Hooks are for the moments when you want the gateway itself to react to an event instead of waiting for a human message. They are intentionally small and close to the runtime. That makes them powerful, but it also means you should use them with a scalpel, not a shovel.

What this feature is really for

The official docs define hooks as small scripts that run when something happens inside the gateway. They cover internal lifecycle events like command:new, command:reset, command:stop, and related session lifecycle surfaces. The same docs are careful to distinguish internal hooks from webhooks. Internal hooks run inside OpenClaw. Webhooks are outside callers hitting an HTTP endpoint. If you blur those two, you design the wrong thing.

The win is not that OpenClaw gained another abstraction. The win is that you can stop stuffing long operational instructions into ad hoc chat messages and move them into something the gateway can apply consistently. That gives you cleaner sessions, fewer repeated prompts, and much less drift between what you meant and what the agent actually does.

How to set it up without making a mess

A clean hook workflow starts by discovering what already exists. OpenClaw can load hooks from directories and plugins, but it only loads internal hooks after you enable hooks or configure at least one hook entry, hook pack, legacy handler, or extra hook directory. In other words, do not assume the runtime is watching your hook folder by default. Turn the surface on, inspect it, then enable only the hooks you actually need.

# List available hooks
openclaw hooks list

# Enable a hook
openclaw hooks enable session-memory

# Check hook status
openclaw hooks check

# Get detailed information
openclaw hooks info session-memory

• Use hooks for tight gateway reactions, not sprawling cross-team workflows.
• Remember that hooks can come from standalone directories and from plugins.
• Keep event selection explicit so you know exactly when the handler runs.
• Inspect before enabling so you do not accidentally light up behavior you forgot was installed.

How I would operate it day to day

When you do need a custom hook, follow the documented structure: a HOOK.md file for metadata and documentation, and a handler file for the implementation. That sounds almost boring, but it is the right kind of boring. It keeps the hook inspectable. You can see the event list, prerequisites, and purpose before you trust it. For production work, that transparency is worth more than cleverness.

The classic mistake is pushing business logic into hooks because they feel immediate. Resist that urge. Hooks are best when they stay narrow, deterministic, and easy to disable. If you find yourself wanting branching review states, long waits, or many human-visible updates, you probably want background tasks or Task Flow instead. Another mistake is forgetting the load rules and wondering why a folder exists but nothing fires.

Used well, hooks let OpenClaw feel responsive at the system boundary without turning your gateway into a mystery box. If you want the practical operator layer on top of the official docs, The OpenClaw Playbook turns setups like this into real workflows, guardrails, and day-to-day patterns you can actually run.

I also like to treat hooks as runtime glue rather than product strategy. They are excellent for session setup, cleanup, or controlled internal reactions. They are usually a bad place to hide policy that other operators need to read and challenge.

The docs also call out discovery order, which matters more than people expect. Bundled hooks, plugin hooks, managed hooks, and workspace hooks do not all behave the same, and workspace hooks cannot override bundled or plugin hooks with the same name. That is a sane guardrail, not a limitation.

If you are debugging, remember the shortest loop: list, info, check, then restart the gateway so hooks reload. Most hook confusion comes from discovery assumptions or eligibility requirements, not from the handler code itself.