Bundled Hooks in OpenClaw: Behavior and Options for Each

Hooks that ship with OpenClaw, along with how each one behaves and what options it takes. This page is part of the Hooks guide.

Bundled hooks

To turn one on, use openclaw hooks enable <hook-name>, then confirm the side effect it produces. Hooks that only fire at startup, such as boot-md, do not run until the next Gateway start.

boot-md details

For every configured agent, a nonempty BOOT.md is run from that agent's resolved workspace. When several agents share a workspace, it runs a single time, under whichever agent was picked first for that workspace. Startup tasks execute one after another; if one fails, the failure is logged and the remaining tasks still run.

Instructions here go through an agent run. They are not run as a shell script, and they are not injected as a bootstrap file. Every run gets a fresh temporary agent:<id>:boot:<run-id> session that is cleaned up whether it succeeds or fails. Sessions that already exist, and their history, stay intact. Normal final-response delivery is turned off; should the instructions need to reach someone, they have to name a channel and target for the message tool. Files that are missing or empty are skipped.

Keep boot instructions brief and safe to repeat on each restart. They are able to use model and tool capabilities, so turning this hook on may lead to model calls and outbound side effects.

bootstrap-extra-files config

{
  "hooks": {
    "internal": {
      "entries": {
        "bootstrap-extra-files": {
          "enabled": true,
          "paths": ["packages/*/AGENTS.md"]
        }
      }
    }
  }
}

paths takes precedence. When it is empty, the handler falls back to patterns, and then to files; these are alternatives rather than lists that get merged. If no patterns are given, the hook does nothing.

Paths are resolved relative to the event's workspace and must stay within it, even after symlink resolution. Only the following basenames are loaded: AGENTS.md, SOUL.md, IDENTITY.md, USER.md, BOOTSTRAP.md, and MEMORY.md.

Additional files are subject to the usual bootstrap filtering and injection limits. Each file read is capped at 2 MiB. By default, injection allows 20,000 characters per file and 60,000 in total, set through bootstrapMaxChars and bootstrapTotalMaxChars in agent defaults or overrides; USER.md is capped separately at 4,000 characters. Duplicate paths get removed. Subagents keep only AGENTS.md; cron and non-private conversations are subject to further context and privacy filters. To see what was actually injected, use /context detail; see Context.

TOOLS.md is not a recognized runtime bootstrap basename. openclaw doctor --fix archives the workspace-root TOOLS.md and merges customized content into the ## Tools section of AGENTS.md. Other TOOLS.md files that patterns name are not migrated; instead, point those patterns at AGENTS.md.

command-logger details

Each emitted command event is appended as one JSON line to <stateDir>/logs/commands.log. The fields are timestamp, action, sessionKey, senderId, and source; sender or source values that are absent become unknown. Core emits /new, /reset, and /stop, not every slash command.

The handler waits for the append to finish, logs any write errors, and sends no chat confirmation. The log is not rotated. Set suitable access and retention for the session and sender identifiers it records. See Log inspection.

compaction-notifier details

A short notice is added before compaction, and a completion notice after compaction succeeds. When available, notices may include message counts and before/after token counts. They are delivered through the compaction caller's notice callback; if no callback delivers them, turning the hook on does not guarantee a visible message. A before notice with no after notice may point to a compaction that was skipped, failed, or interrupted, rather than a stuck hook. Manual /compact does not provide this hook-message delivery callback, so it is not a dependable way to test the notices.

session-memory details

Writes the departing session's latest user and assistant text on /new, /reset (soft reset included), or a scheduled daily/idle rollover. A scheduled rollover emits session:auto-reset rather than a synthetic command event. The expiry check happens only when the next turn is admitted, so this is not a timer that writes memory at the daily boundary while the session sits idle.

By default the artifact is <workspace>/memory/YYYY-MM-DD-HHMM.md, and a numeric suffix is appended when that filename is already taken. For dates, agents.defaults.userTimezone is used first; if no user timezone is set, TZ is used instead, with the host timezone as a fallback. Session identity, plus the command source or the reason for an automatic reset, is recorded in the file.

The conversation being left behind is captured before a reset closes its active window, and the snapshot is then written in the background. Scanning is capped at 4,096 messages and 8 MiB. No memory artifacts are produced for incognito sessions, whether the reset is manual or automatic. A manual reset does not wait for the file write or for the optional slug-model call, and automatic reset dispatch likewise runs independently of the successor turn. Before you expect the file, wait for Session context saved to ... in the logs.

This is a filtered excerpt, not a full transcript and not a summary written by a model. Slash-command text, tool messages, inter-session user input, silent reply markers, and duplicate delivery-mirror text are all left out. Should reading the transcript fail, the artifact may record that the content was unavailable. The workspace comes from event/agent config, so no workspace.dir key needs to be added.

When llmSlug: true is on, conversation text goes to the configured model so the file can be named. If that call fails, a timestamp slug is used instead. Keep it off if you want no extra model call for naming.

Note

Saved excerpts are workspace memory artifacts. When session transcript indexing is enabled as well, a single conversation may be represented by both memory and sessions, which adds overlapping results and embedding work. If you want recall from the hook only, set memory.search.sources: ["memory"] and memory.search.rememberAcrossConversations: false; sources on its own will not prevent cross-conversation recall from adding sessions. To get full-transcript recall instead, turn off session-memory. None of these search settings stop the hook from writing files or affect ordinary transcript persistence.