Bundled Hooks Reference

+15 Mana ✨

Introduction

OpenClaw ships with four bundled hooks that provide essential automation out of the box. These hooks handle session memory persistence, command auditing, file injection during bootstrap, and startup scripts, covering the most common automation needs without any configuration.

Key Concepts

  • session-memory: A bundled hook that automatically saves session context whenever a new session is created via the /new command.
  • command-logger: An audit hook that writes every command event to a JSONL log file for traceability and debugging.
  • bootstrap-extra-files: A hook that injects additional files into the agent context during the agent:bootstrap event.
  • boot-md: A hook that executes a BOOT.md file when the gateway starts up, enabling startup automation scripts.

Real World Context

Production systems rely on audit logs, automatic initialization, and context persistence. The bundled hooks mirror patterns found in tools like shell profile scripts (.bashrc), systemd unit files, and application-level logging middleware. They provide sensible defaults that most users need without requiring manual setup.

Deep Dive

The session-memory hook listens for the command:new event and persists the current session context so it can be restored later:

typescript
// session-memory hook
// Triggers on: command:new
// Purpose: saves current context when a new session starts

const handler: HookHandler = async (event) => {
  if (event.type === 'command' && event.action === 'new') {
    const { sessionKey, context, messages } = event;
    await saveSessionContext(sessionKey, {
      context,
      messages,
      savedAt: event.timestamp
    });
  }
};

This hook fires every time the user runs /new to start a fresh session. It captures the session key, context, and messages, then persists them. This allows OpenClaw to recall previous session state and maintain continuity across conversations.

The command-logger hook provides an audit trail by writing command events to a JSONL file:

typescript
// command-logger hook
// Triggers on: command:* (all command actions)
// Output: ~/.openclaw/logs/commands.log (JSONL format)

const handler: HookHandler = async (event) => {
  if (event.type === 'command') {
    const logEntry = JSON.stringify({
      action: event.action,
      sessionKey: event.sessionKey,
      timestamp: event.timestamp
    });
    await appendFile(
      '~/.openclaw/logs/commands.log',
      logEntry + '\n'
    );
  }
};

The command-logger writes one JSON object per line to ~/.openclaw/logs/commands.log. It captures every command action (new, reset, stop) along with the session key and timestamp. The JSONL format makes these logs easy to parse, search, and analyze with standard tools like jq.

The bootstrap-extra-files hook injects additional files into the agent environment during bootstrap:

typescript
// bootstrap-extra-files hook
// Triggers on: agent:bootstrap
// Purpose: adds extra configuration or reference files

const handler: HookHandler = async (event) => {
  if (event.type === 'agent' && event.action === 'bootstrap') {
    const extraFiles = await loadExtraFiles();
    event.context.files = [
      ...(event.context.files || []),
      ...extraFiles
    ];
  }
};

This hook runs during agent:bootstrap and merges additional files into the context. This is useful for injecting project-wide configuration, coding standards, or reference documentation that the agent should have available from the start of every session.

The boot-md hook runs the contents of a BOOT.md file when the gateway starts:

typescript
// boot-md hook
// Triggers on: gateway:startup
// Purpose: executes BOOT.md as a startup automation script

const handler: HookHandler = async (event) => {
  if (event.type === 'gateway' && event.action === 'startup') {
    const bootFile = await findBootMd();
    if (bootFile) {
      await executeMarkdownScript(bootFile, event.context);
    }
  }
};

When the gateway starts, this hook searches for a BOOT.md file and executes its contents. This is analogous to shell startup scripts and lets you define initialization routines, environment checks, or setup procedures that run automatically.

Common Pitfalls

  • Assuming command-logger only tracks /new: The command-logger captures all command actions including reset and stop, not just new sessions.
  • Overlooking log file growth: The commands.log file grows indefinitely in JSONL format; in active environments you should implement log rotation.
  • Conflicting bootstrap files: If bootstrap-extra-files injects files that conflict with workspace files, the merge order can produce unexpected results.

Best Practices

  • Periodically review ~/.openclaw/logs/commands.log to audit session activity and debug unexpected behavior.
  • Keep BOOT.md scripts idempotent so they can safely re-run on every gateway startup without side effects.
  • Use openclaw hooks list to verify which bundled hooks are active before assuming their behavior is in effect.

Summary

  • session-memory persists context on command:new for cross-session continuity.
  • command-logger writes all command events as JSONL to ~/.openclaw/logs/commands.log.
  • bootstrap-extra-files injects additional files during agent:bootstrap to enrich the agent context.
  • boot-md executes a BOOT.md startup script on gateway:startup.
  • All four bundled hooks are located in dist/hooks/bundled/ and are active by default.
✓ Completed