How do I create a custom hook?

Hooks allow you to run custom TypeScript code when specific events occur in OpenClaw. They are powerful tools for auditing commands, persisting memory snapshots, or triggering external automations (like effective zapier-style workflows) whenever a user interacts with your agent.

A hook is simply a directory containing two essential files: HOOK.md (for metadata and discovery) and handler.ts (for the executable logic).

Step 1: Create the directory

Hooks are automatically discovered from standard locations. You can place them in ~/.openclaw/hooks/ for global availability across all agents, or in <workspace>/hooks/ for agent-specific logic.

Step 2: Define metadata (HOOK.md)

The HOOK.md file uses YAML frontmatter to tell OpenClaw's plugin system how to load your hook. The events array is critical—it defines exactly which triggers will wake up your handler.

Step 3: Write Logic (handler.ts)

Your `handler.ts` exports a default function that receives an `event` object. This object contains all the context you need, including the session ID, the user's message, and a mutable `messages` array for sending replies.

Step 4: Enable it

For security, new hooks are disabled by default. You must explicitly enable them via the CLI and restart the gateway for changes to take effect.

Troubleshooting

If your hook isn't firing, check the gateway logs. OpenClaw logs hook registration at startup.

Look for lines like Registered hook: my-greeter -> command:new. If you don't see them, run openclaw hooks info my-greeter to check for missing requirements or syntax errors in your `HOOK.md`.