OpenClaw bundled hooks

Not every hook has to be written. OpenClaw ships five, each bound to specific internal events, and enabling one is a single command followed by checking its side effect; startup-only hooks wait for the next Gateway start. Here is what each bundled hook does, which events it listens to, the options it accepts, the limits it works under, and the places where the docs warn that a missing message or file is not a stuck hook.

The five hooks

• Boot-md runs a non-empty BOOT file from each configured agent’s resolved workspace at Gateway startup; a workspace shared by several agents runs it once under the first agent selected, startup tasks run sequentially, and a failed task is logged without blocking later ones. It executes through an agent run in a fresh temporary boot session that is cleaned up afterwards, not as a shell script or a bootstrap injection, with normal final-response delivery disabled, so instructions that must notify someone name a channel and target for the message tool.
• Bootstrap-extra-files adds matching workspace bootstrap files to context on the agent bootstrap event: a paths list is preferred, with patterns or files as alternatives rather than merged lists, paths resolve relative to the event’s workspace and must stay inside it after symlink resolution, and only the agents, soul, identity, user, bootstrap and memory basenames load.
• Command-logger appends one JSON line per emitted command event to a commands log in the state directory, with timestamp, action, session key, sender and source, where absent values become unknown; core emits only the new, reset and stop commands, the handler awaits the append and never confirms in chat, and the log is not rotated, so access and retention for the identifiers it records are yours to set.
• Compaction-notifier adds a short notice before compaction and a completion notice after a successful one, with message and token counts when available; the notices travel through the compaction caller’s callback, so without one that delivers them a visible message is not guaranteed, and a manual compact command does not supply that callback, which makes it an unreliable way to test the hook.

Keep boot instructions short and safe to repeat on every restart.

Session memory

Session-memory saves the ended session’s recent user and assistant text when a new-session or reset command runs, including soft resets, or when the automatic daily or idle rollover replaces the session, which emits its own auto-reset event rather than a synthetic command; expiry is checked when the next turn is admitted, not by a timer at the daily boundary. The artifact is a dated file under the workspace memory directory with a numeric suffix on collision, dated in the user timezone, then the process timezone, then the host’s, and it records the session identity and the command source or reset reason. Three options: the number of recent messages, fifteen by default; an optional model-generated filename slug, off by default because it costs a model call and falls back to a timestamp on failure; and the model used for that slug. The hook captures the departing conversation before the reset closes its window and writes in the background, bounded to 4,096 scanned messages and eight mebibytes, and manual resets do not wait for the write, so the docs say to wait for the saved-context log line before expecting the file. It is a filtered excerpt, not a transcript or a model summary: slash-command text, tool messages, inter-session input, silent markers and duplicate delivery mirrors are omitted.

Limits and overlaps

• Extra bootstrap files go through the normal filtering and caps: reads capped at two mebibytes per file, injection at twenty thousand characters per file and sixty thousand in total under the agent defaults, a separate four-thousand-character cap on the user file, duplicates removed, sub-agents keeping only the agents file, and additional privacy filters for cron and non-private conversations; the context detail command shows the actual injected result.
• A tools file is not a recognised bootstrap basename: the doctor fix archives a workspace-root one and merges customised content into the tools section of the agents file, and patterns naming other tools files should point at the agents file instead.
• If session transcript indexing is also enabled, one conversation can be represented both as a memory excerpt and as a session source, adding overlapping results and embedding work; for hook-only recall restrict the memory search sources to memory and turn off cross-conversation recall, and for full-transcript recall disable the hook instead. Those search settings do not stop the hook’s file writes.

OpenClaw hooks and webhooks is the guide these five belong to, and The OpenClaw agent workspace lists the bootstrap files the extra-files hook is allowed to add.

Two things they touch

Two of the five sit on the memory path: the compaction notifier reports on it and session memory feeds it. OpenClaw context window and compaction explains the before and after phases the notifier wraps, and OpenClaw memory explained the workspace memory directory the excerpt lands in.

On Diali

On Diali the bundled hooks are present in the runtime image, and whichever ones are switched on act on the workspace and state directory on the assistant’s volume; a boot file, if you use one, runs again at every release restart, so keep it idempotent. Hosted OpenClaw on Diali is the assistant and OpenClaw sessions the resets that trigger session memory.

• Five hooks, enabled by name, verified by their side effect.
• Boot runs through an agent, not a shell.
• Session memory is an excerpt, written in the background.