Writing hooks: file layout, handler contract, and replies

Hook file layout, the handler contract, how replies are delivered, and the HOOK.md metadata fields. This page is part of the Hooks guide.

Writing hooks

The example below answers a reset command and writes a fixed log marker. It never reads message content, calls a model, or contacts an external service.

Hook structure

Create a fresh managed hook directory on the Gateway host. The commands that follow presume the default state directory and that reset-greeting does not exist yet; pick a different name instead of overwriting a hook that is already there.

mkdir -p ~/.openclaw/hooks/reset-greeting

cat > ~/.openclaw/hooks/reset-greeting/HOOK.md <<'HOOK'
---
name: reset-greeting
description: "Confirm that a reset hook ran"
metadata:
  { "openclaw": { "events": ["command:new", "command:reset"] } }
---

# Reset greeting

Send a short confirmation after an authorized reset command.
HOOK

cat > ~/.openclaw/hooks/reset-greeting/handler.js <<'HANDLER'
export default function handler(event) {
  if (event.type !== "command" || !["new", "reset"].includes(event.action)) {
    return;
  }

  console.log("[reset-greeting] reset hook ran");
  event.messages.push("Reset hook ran.");
}
HANDLER

Two things are required for a hook: HOOK.md and a handler file. Discovery looks for handler.ts, handler.js, index.ts, and then index.js, in that order, and takes the first file it finds. JavaScript is used in the example, so no TypeScript types or SDK imports are required.

Turn it on and load it:

openclaw hooks info reset-greeting
openclaw hooks enable reset-greeting

In a disposable conversation on a configured chat channel that can route replies, such as a direct message to the bot, send /new. Reset hook ran. should appear in that conversation, and [reset-greeting] reset hook ran should appear in Gateway logs. The same example is also triggered by /reset. Ordinary command authorization still applies.

Use a regular OpenClaw conversation rather than an ACP-bound thread, since bound sessions hand reset handling to the runtime that owns them. As the chat-reply check, avoid Control UI/webchat and a sessions.reset RPC: neither path delivers this hook's event.messages to the UI. The log marker can still confirm that a reset event ran. The precise boundary is described in Reply delivery.

When you are done with the example, disable it:

openclaw hooks disable reset-greeting

Files stay on disk after disabling. If you would rather use a workspace directory, place the two files in <workspace>/hooks/reset-greeting/ and then enable the hook explicitly. A workspace location is neither an agent sandbox nor a promise that the Gateway will load hooks from that workspace.

Handler implementation

A handler exports a function that returns void or Promise<void>. The default export is what the loader uses, unless metadata.openclaw.export names a different export. Nothing a handler returns blocks, cancels, or rewrites the operation.

These fields are present on every event:

Context is meant for observation, not as a live API for editing state. Which fields appear depends on the producer, and cfg is absent from some events. Patch events, for example, carry cloned snapshots. The one explicit mutable exception is agent:bootstrap's context.bootstrapFiles.

Reply delivery

Pushing to event.messages is not a general-purpose send-message API:

A reply can fail to arrive for several reasons: no recipient, an unsupported route, send policy, or a delivery error. Append messages before the handler's promise settles, because detached work that pushes afterward may miss the producer's delivery step. For control over normal agent replies or for sending a cancellation, use the appropriate typed plugin hook.

HOOK.md format

HOOK.md consists of YAML frontmatter followed by human-readable Markdown:

---
name: my-hook
description: "Short description of what this hook does"
homepage: https://example.com/my-hook
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

Explain the side effects, configuration, and verification steps here.

name defaults to the directory name, so choose a name that is unique and stable. description appears in reports. The fields listed below go under metadata.openclaw.

The metadata.clawdbot layout used before July 2026 is no longer parsed. To bring an older HOOK.md up to date, rename that metadata block to openclaw and leave its event list and remaining fields intact. When an openclaw block is already present, retain its values and merge in only the legacy fields you still need. OpenClaw leaves the file untouched, and any event declarations or requirements inside the old block are disregarded.

Activation is controlled through hooks.internal.entries.<hookKey>.enabled, not by a top-level enabled flag placed in HOOK.md. Where historical requirement metadata is concerned, workspace.dir, browser.enabled, and browser.evaluateEnabled are treated as true when they are missing. workspace.dir is not a new setting for you to add to your config.