Bundled Hooks

This directory contains hooks that ship with OpenClaw. These hooks are automatically discovered and can be enabled/disabled via CLI or configuration.

Available Hooks

💾 session-memory

Automatically saves session context to memory when you issue /new or /reset.

Events: command:new, command:reset What it does: Creates a dated memory file with LLM-generated slug based on conversation content. Output: <workspace>/memory/YYYY-MM-DD-slug.md (defaults to ~/.openclaw/workspace)

Enable:

openclaw hooks enable session-memory

📎 bootstrap-extra-files

Injects extra bootstrap files (for example monorepo AGENTS.md/TOOLS.md) during prompt assembly.

Events: agent:bootstrap What it does: Expands configured workspace glob/path patterns and appends matching bootstrap files to injected context. Output: No files written; context is modified in-memory only.

Enable:

openclaw hooks enable bootstrap-extra-files

📝 command-logger

Logs all command events to a centralized audit file.

Events: command (all commands) What it does: Appends JSONL entries to command log file. Output: ~/.openclaw/logs/commands.log

Enable:

openclaw hooks enable command-logger

🚀 boot-md

Runs BOOT.md whenever the gateway starts (after channels start).

Events: gateway:startup What it does: Executes BOOT.md instructions via the agent runner. Output: Whatever the instructions request (for example, outbound messages).

Enable:

openclaw hooks enable boot-md

Hook Structure

Each hook is a directory containing:

• HOOK.md: Metadata and documentation in YAML frontmatter + Markdown
• handler.ts: The hook handler function (default export)

Example structure:

session-memory/
├── HOOK.md          # Metadata + docs
└── handler.ts       # Handler implementation

HOOK.md Format

---
name: my-hook
description: "Short description"
homepage: https://docs.openclaw.ai/automation/hooks#my-hook
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---
# Hook Title

Documentation goes here...

Metadata Fields

• emoji: Display emoji for CLI
• events: Array of events to listen for (e.g., ["command:new", "session:start"])
• requires: Optional requirements
  • bins: Required binaries on PATH
  • anyBins: At least one of these binaries must be present
  • env: Required environment variables
  • config: Required config paths (e.g., ["workspace.dir"])
  • os: Required platforms (e.g., ["darwin", "linux"])
• install: Installation methods (for bundled hooks: [{"id":"bundled","kind":"bundled"}])

Creating Custom Hooks

To create your own hooks, place them in:

• Workspace hooks: <workspace>/hooks/ (highest precedence)
• Managed hooks: ~/.openclaw/hooks/ (shared across workspaces)

Custom hooks follow the same structure as bundled hooks.

Managing Hooks

List all hooks:

openclaw hooks list

Show hook details:

openclaw hooks info session-memory

Check hook status:

openclaw hooks check

Enable/disable:

openclaw hooks enable session-memory
openclaw hooks disable command-logger

Configuration

Hooks can be configured in ~/.openclaw/openclaw.json:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "session-memory": {
          "enabled": true
        },
        "command-logger": {
          "enabled": false
        }
      }
    }
  }
}

Event Types

Currently supported events:

• command: All command events
• command:new: /new command specifically
• command:reset: /reset command
• command:stop: /stop command
• agent:bootstrap: Before workspace bootstrap files are injected
• gateway:startup: Gateway startup (after channels start)
• session:compact:before: Pre-compaction snapshot before the embedded runner rewrites session context
• session:compact:after: Post-compaction snapshot after the runner replaces session context
• message:received: Inbound channel message accepted for dispatch
• message:sent: Outbound channel message delivered (canonical payload only)

Handler API

Hook handlers receive an InternalHookEvent object:

interface InternalHookEvent {
  type: "command" | "session" | "agent" | "gateway" | "message";
  action: string; // e.g., 'new', 'reset', 'stop', 'compact:before', 'received', 'sent'
  sessionKey: string;
  context: Record<string, unknown>;
  timestamp: Date;
  messages: string[]; // Push messages here to send to user
}

Example handler:

import type { HookHandler } from "../../src/hooks/hooks.js";

const myHandler: HookHandler = async (event) => {
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  // Your logic here
  console.log("New command triggered!");

  // Optionally send message to user
  event.messages.push("✨ Hook executed!");
};

export default myHandler;

Testing

Test your hooks by:

1. Place hook in workspace hooks directory
2. Restart gateway: pkill -9 -f 'openclaw.*gateway' && pnpm openclaw gateway
3. Enable the hook: openclaw hooks enable my-hook
4. Trigger the event (e.g., send /new command)
5. Check gateway logs for hook execution

Documentation

Full documentation: https://docs.openclaw.ai/automation/hooks