Hooks

Hooks provide an extensible event-driven system for automating actions in response to agent commands and events. Hooks are automatically discovered from directories and can be managed via CLI commands, similar to how skills work in OpenClaw.

Getting Oriented

Hooks are small scripts that run when something happens. There are two kinds:

Hooks (this page): run inside the Gateway when agent events fire, like /new, /reset, /stop, or lifecycle events.
Webhooks: external HTTP webhooks that let other systems trigger work in OpenClaw. See Webhook Hooks or use openclaw webhooks for Gmail helper commands.

Hooks can also be bundled inside plugins; see Plugins. Common uses:

Save a memory snapshot when you reset a session
Keep an audit trail of commands for troubleshooting or compliance
Trigger follow-up automation when a session starts or ends
Write files into the agent workspace or call external APIs when events fire

If you can write a small TypeScript function, you can write a hook. Hooks are discovered automatically, and you enable or disable them via the CLI.

Getting Started

Bundled Hooks

OpenClaw ships with five bundled hooks that are automatically discovered:

💾 session-memory: Saves session context to your agent workspace (default ~/.openclaw/workspace/memory/) when you issue /new
📔 session-journal: Writes a reflective LLM journal entry to the lane’s journal/ folder when an opted-in agent issues /new or /reset
📎 bootstrap-extra-files: Injects additional workspace bootstrap files from configured glob/path patterns during agent:bootstrap
📝 command-logger: Logs all command events to ~/.openclaw/logs/commands.log
🚀 boot-md: Runs BOOT.md when the gateway starts (requires internal hooks enabled)

List available hooks:

openclaw hooks list

Enable a hook:

openclaw hooks enable session-memory

Check hook status:

openclaw hooks check

Get detailed information:

openclaw hooks info session-memory

Onboarding

During onboarding (openclaw onboard), you’ll be prompted to enable recommended hooks. The wizard automatically discovers eligible hooks and presents them for selection.

Hook Discovery

Hooks are automatically discovered from three directories (in order of precedence):

Workspace hooks: <workspace>/hooks/ (per-agent, highest precedence)
Managed hooks: ~/.openclaw/hooks/ (user-installed, shared across workspaces)
Bundled hooks: <openclaw>/dist/hooks/bundled/ (shipped with OpenClaw)

Managed hook directories can be either a single hook or a hook pack (package directory). Each hook is a directory containing:

my-hook/
├── HOOK.md          # Metadata + documentation
└── handler.ts       # Handler implementation

Hook Packs (npm/archives)

Hook packs are standard npm packages that export one or more hooks via openclaw.hooks in package.json. Install them with:

openclaw hooks install <path-or-spec>

Npm specs are registry-only (package name + optional version/tag). Git/URL/file specs are rejected. Example package.json:

{
  "name": "@acme/my-hooks",
  "version": "0.1.0",
  "openclaw": {
    "hooks": ["./hooks/my-hook", "./hooks/other-hook"]
  }
}

Each entry points to a hook directory containing HOOK.md and handler.ts (or index.ts). Hook packs can ship dependencies; they will be installed under ~/.openclaw/hooks/<id>. Each openclaw.hooks entry must stay inside the package directory after symlink resolution; entries that escape are rejected. Security note: openclaw hooks install installs dependencies with npm install --ignore-scripts (no lifecycle scripts). Keep hook pack dependency trees “pure JS/TS” and avoid packages that rely on postinstall builds.

Hook Structure

HOOK.md Format

The HOOK.md file contains metadata in YAML frontmatter plus Markdown documentation:

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

# My Hook

Detailed documentation goes here...

## What It Does

- Listens for `/new` commands
- Performs some action
- Logs the result

## Requirements

- Node.js must be installed

## Configuration

No configuration needed.

Metadata Fields

The metadata.openclaw object supports:

emoji: Display emoji for CLI (e.g., "💾")
events: Array of events to listen for (e.g., ["command:new", "command:reset"])
export: Named export to use (defaults to "default")
homepage: Documentation URL
requires: Optional requirements
- bins: Required binaries on PATH (e.g., ["git", "node"])
- 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"])
always: Bypass eligibility checks (boolean)
install: Installation methods (for bundled hooks: [{"id":"bundled","kind":"bundled"}])

Handler Implementation

The handler.ts file exports a HookHandler function:

const myHandler = async (event) => {
  // Only trigger on 'new' command
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log(`[my-hook] New command triggered`);
  console.log(`  Session: ${event.sessionKey}`);
  console.log(`  Timestamp: ${event.timestamp.toISOString()}`);

  // Your custom logic here

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

export default myHandler;

Event Context

Each event includes:

{
  type: 'command' | 'session' | 'agent' | 'gateway' | 'message',
  action: string,              // e.g., 'new', 'reset', 'stop', 'received', 'sent'
  sessionKey: string,          // Session identifier
  timestamp: Date,             // When the event occurred
  messages: string[],          // Push messages here to send to user
  context: {
    // Command events:
    sessionEntry?: SessionEntry,
    sessionId?: string,
    sessionFile?: string,
    commandSource?: string,    // e.g., 'whatsapp', 'telegram'
    senderId?: string,
    workspaceDir?: string,
    bootstrapFiles?: WorkspaceBootstrapFile[],
    cfg?: OpenClawConfig,
    // Message events (see Message Events section for full details):
    from?: string,             // message:received
    to?: string,               // message:sent
    content?: string,
    channelId?: string,
    success?: boolean,         // message:sent
  }
}

Event Types

Command Events

Triggered when agent commands are issued:

command: All command events (general listener)
command:new: When /new command is issued
command:reset: When /reset command is issued
command:stop: When /stop command is issued

Agent Events

agent:bootstrap: Before workspace bootstrap files are injected (hooks may mutate context.bootstrapFiles)

For lane-aware agents, agent:bootstrap receives context.workspaceLane only when lane resolution is allowed for that bootstrap pass. context.workspaceDir is the effective workspace. Use context.workspaceLane.personaWorkspaceDir when a hook deliberately needs the shared persona workspace. See Workspace Lanes.

event.context.workspaceLane?: WorkspaceLaneResolution;

Gateway Events

Triggered when the gateway starts:

gateway:startup: After channels start and hooks are loaded

Message Events

Triggered when messages are received or sent:

message: All message events (general listener)
message:received: When an inbound message is received from any channel. Fires early in processing before media understanding. Content may contain raw placeholders like <media:audio> for media attachments that haven’t been processed yet.
message:transcribed: When a message has been fully processed, including audio transcription and link understanding. At this point, transcript contains the full transcript text for audio messages. Use this hook when you need access to transcribed audio content.
message:preprocessed: Fires for every message after all media + link understanding completes, giving hooks access to the fully enriched body (transcripts, image descriptions, link summaries) before the agent sees it.
message:sent: When an outbound message is successfully sent

Message Event Context

Message events include rich context about the message:

// message:received context
{
  from: string,            // Sender identifier (phone number, user ID, etc.)
  content: string,         // Message content
  timestamp?: number,      // Unix timestamp when received
  channelId: string,       // Channel (e.g., "whatsapp", "telegram", "discord")
  accountId?: string,      // Provider account ID for multi-account setups
  conversationId?: string, // Legacy alias for channelConversationId
  channelConversationId?: string,
  messageProvider?: string,
  sessionId?: string,      // Present only if a real session is already known
  sessionKey?: string,
  runId?: string,          // Same value as turn.turnId in the v1 turn contract
  messageId?: string,      // Message ID from the provider
  senderId?: string,
  senderName?: string,
  senderUsername?: string,
  senderE164?: string,
  canonicalIdentity?: string,
  senderIsOwner?: boolean,
  runtimeIdentity?: PluginRuntimeIdentity,
  turn?: PluginTurnIdentity,
  metadata?: {             // Additional provider-specific data
    to?: string,
    provider?: string,
    surface?: string,
    threadId?: string,
    senderId?: string,
    senderName?: string,
    senderUsername?: string,
    senderE164?: string,
  }
}

// message:sent context
{
  to: string,             // Recipient identifier
  content: string,        // Message content that was sent
  success: boolean,       // Whether the send succeeded
  error?: string,         // Error message if sending failed
  channelId: string,      // Channel (e.g., "whatsapp", "telegram", "discord")
  accountId?: string,     // Provider account ID
  conversationId?: string, // Chat/conversation ID
  messageId?: string,     // Message ID returned by the provider
  isGroup?: boolean,      // Whether this outbound message belongs to a group/channel context
  groupId?: string,       // Group/channel identifier for correlation with message:received
}

// message:transcribed context
{
  body?: string,          // Raw inbound body before enrichment
  bodyForAgent?: string,  // Enriched body visible to the agent
  transcript: string,     // Audio transcript text
  channelId: string,      // Channel (e.g., "telegram", "whatsapp")
  conversationId?: string,
  messageId?: string,
}

// message:preprocessed context
{
  body?: string,          // Raw inbound body
  bodyForAgent?: string,  // Final enriched body after media/link understanding
  transcript?: string,    // Transcript when audio was present
  channelId: string,      // Channel (e.g., "telegram", "whatsapp")
  conversationId?: string,
  messageId?: string,
  isGroup?: boolean,
  groupId?: string,
}

Example: Message Logger Hook

const isMessageReceivedEvent = (event: { type: string; action: string }) =>
  event.type === "message" && event.action === "received";
const isMessageSentEvent = (event: { type: string; action: string }) =>
  event.type === "message" && event.action === "sent";

const handler = async (event) => {
  if (isMessageReceivedEvent(event as { type: string; action: string })) {
    console.log(`[message-logger] Received from ${event.context.from}: ${event.context.content}`);
  } else if (isMessageSentEvent(event as { type: string; action: string })) {
    console.log(`[message-logger] Sent to ${event.context.to}: ${event.context.content}`);
  }
};

export default handler;

Tool Result Hooks (Plugin API)

These hooks are not event-stream listeners; they let plugins synchronously adjust tool results before WednesdayAI persists them.

tool_result_persist: transform tool results before they are written to the session transcript. Must be synchronous; return the updated tool result payload or undefined to keep it as-is. See Agent Loop.

Plugin API Hooks (`api.on`)

Plugin hooks registered via api.on(hookName, handler) intercept the agent pipeline at specific points. Unlike the file-based hook system above, these hooks are registered in code inside a plugin’s register or activate function and are typed end-to-end.

Hook event reference

Event	Fires when	Context type	Return value
`before_model_resolve`	Before the model is resolved for a run	`PluginHookAgentContext`	`{ modelOverride?, providerOverride? }` or void
`before_prompt_build`	After session messages are prepared, before the prompt is assembled	`PluginHookAgentContext`	`{ systemPrompt?, prependContext? }` or void
`before_context_send`	Just before the full context is sent to the LLM	`PluginHookAgentContext`	`{ messages? }` or void
`before_agent_start`	Legacy combined hook (pre-session phase)	`PluginHookAgentContext`	`{ systemPrompt?, prependContext?, modelOverride?, providerOverride? }` or void
`llm_input`	Immediately before the LLM API call (observe only)	`PluginHookAgentContext`	void
`llm_output`	Immediately after the LLM API call (observe only)	`PluginHookAgentContext`	void
`transform_llm_input`	Before messages are sent to the LLM; handlers execute sequentially, each receiving the prior handler’s output	`PluginHookAgentContext`	`{ messages: AgentMessage[] }`
`transform_llm_output`	After the LLM returns; handlers execute sequentially	`PluginHookAgentContext`	`{ assistantTexts?: string[] }`
`agent_end`	When an agent run completes (success or error)	`PluginHookAgentContext`	void
`before_compaction`	Before compaction begins	`PluginHookAgentContext`	void
`after_compaction`	After compaction completes	`PluginHookAgentContext`	void
`before_reset`	When `/new` or `/reset` clears a session	`PluginHookAgentContext`	void
`message_received`	Inbound message received	`PluginHookMessageContext`	void
`message_sending`	Outbound message about to be sent	`PluginHookMessageContext`	`{ content?, cancel? }` or void
`message_sent`	Outbound message was sent	`PluginHookMessageContext`	void
`before_tool_call`	Before a tool is invoked	`PluginHookToolContext`	`{ params?, block?, blockReason? }` or void
`after_tool_call`	After a tool returns	`PluginHookToolContext`	void
`tool_result_persist`	Before a tool result is written to the JSONL transcript (synchronous)	`PluginHookToolResultPersistContext`	`{ message? }` or void
`before_message_write`	Before any agent message is written to the JSONL	`{ agentId?, sessionKey?, runtimeIdentity?, turn? }`	`{ block?, message? }` or void
`model_call_ended`	After an agent model-call attempt finishes	`PluginHookAgentContext`	void; handlers may update usage/proxy metadata
`storage.afterAppend`	After a conversation entry is appended to context storage	`ContextLifecycleContext`	void
`context.collect`	During context construction, before prompt assembly	`ContextLifecycleContext`	`PromptContribution` or void
`context.project`	During context projection, after collection	`ContextLifecycleContext`	`{ messages?, projection?, contribution? }` or void
`context.prune`	During context pruning	`ContextLifecycleContext`	`{ messages?, dropped?, contribution?, suppressCompaction? }` or void
`session_start`	A session begins (new or resumed)	`PluginHookSessionContext`	void
`session_end`	A session ends	`PluginHookSessionContext`	void
`subagent_spawning`	A sub-agent is about to be spawned	`PluginHookSubagentContext`	`{ status: "ok" \| "error", ... }` or void
`subagent_spawned`	A sub-agent was successfully spawned	`PluginHookSubagentContext`	void
`subagent_ended`	A sub-agent run finished	`PluginHookSubagentContext`	void
`gateway_start`	Gateway has started	`PluginHookGatewayContext`	void
`gateway_stop`	Gateway is stopping	`PluginHookGatewayContext`	void

Runtime and turn identity context

Most plugin API hooks receive optional nested identity objects when WednesdayAI has real identity for that point in the lifecycle:

type PluginRuntimeIdentity = {
  agentId?: string;
  agentName?: string;
  agentWorkspacePath?: string;
  agentWorkspaceName?: string;
  sessionId?: string;
  sessionKey?: string;
  channelConversationId?: string;
  providerConversationId?: string;
  hashedUserId?: string;
  senderId?: string;
  senderName?: string;
  senderUsername?: string;
  senderE164?: string;
  canonicalIdentity?: string;
  senderIsOwner?: boolean;
  messageProvider?: string;
  channelId?: string;
};

type PluginTurnIdentity = {
  turnId: string;
  runId?: string;
  sessionId?: string;
  sessionKey?: string;
  turnNumber?: number;
  inboundMessageId?: string;
  userEntryId?: string;
  assistantEntryId?: string;
  userSeq?: number;
  assistantSeq?: number;
  userGlobalSeq?: number;
  assistantGlobalSeq?: number;
};

In the v1 contract, turn.turnId is the same stable string value as runId. The value is minted before message_received on normal inbound dispatch, then carried by value through later hooks. Do not depend on the same object reference being reused across hooks. Important boundaries:

conversationId remains the legacy channel conversation id. It is an alias for channelConversationId, never for providerConversationId.
providerConversationId is opaque provider/cache identity. It is safe to store as an opaque correlation key, but plugins must not try to reverse or derive it.
Early hooks may not have sessionId or sessionKey; WednesdayAI omits those fields rather than fabricating session identity.
Public hook contexts do not expose raw identityLinks. Use ctx.runtimeIdentity.canonicalIdentity, ctx.runtimeIdentity.senderIsOwner, or api.runtime.identity.resolveCanonicalIdentity(...) for canonical sender resolution.

Storage append hooks can fire once for the user entry and once for the assistant entry. Both appends share the same turnId, so dedupe with the entry or cursor identity as well:

const key = `${ctx.turn?.turnId}:${event.entry.entryId ?? event.cursor?.entryId ?? event.entry.rawSha256}`;

The typed context lifecycle hooks (context.collect, context.project, context.prune, and storage.afterAppend) use ContextLifecycleContext. That context includes sessionId, sessionKey, runId, storage cursor data when available, sender identity fields, and the same optional runtimeIdentity and turn objects. Use context.collect for context contributions and storage.afterAppend for background capture or extraction queues. model_call_ended carries the completed runId and receives a context whose turn.turnId is aligned to that runId, so usage and provider metadata can be joined back to the same turn. Tool lifecycle hooks also receive foreground identity when it exists. In particular, the production agent tool wrapper passes runtimeIdentity and turn through to before_tool_call, so authorization, audit, and dedupe logic can use the same SDK-owned identity fields before and after a tool executes.

`PluginHookAgentContext`

The shared context passed to all agent-lifecycle hooks:

type PluginHookAgentContext = {
  agentId?: string;
  sessionKey?: string;
  sessionId?: string; // Ephemeral UUID; regenerated on /new and /reset
  workspaceDir?: string;
  messageProvider?: string;
  /** What triggered this run: "user" | "heartbeat" | "cron" | "steer" | "memory" | "internal" */
  trigger?: string;
  /** Resolved message channel (e.g. "telegram", "discord", "whatsapp") */
  channelId?: string;
  runtimeIdentity?: PluginRuntimeIdentity;
  turn?: PluginTurnIdentity;
};

trigger and channelId are included in every agent-context hook. Use them to gate logic per channel or trigger type — for example, only apply an output transform for channelId === "telegram" messages triggered by a user.

`transform_llm_input`

Fires immediately before the messages array is sent to the LLM. Use it to inject additional context, redact sensitive fields, or reorder messages.

// Event payload
type PluginHookTransformLlmInputEvent = {
  messages: AgentMessage[]; // Current messages to be sent
  provider: string; // e.g. "anthropic", "openai"
  model: string; // e.g. "claude-sonnet-4-6"
};

// Return value — return updated messages array, or void/undefined to pass through unchanged
type PluginHookTransformLlmInputResult = {
  messages: AgentMessage[];
};

Handlers are called sequentially; each handler receives the output of the previous one. Return { messages: [...] } to replace the array, or return nothing to keep the current state. Example — append a confidentiality reminder to the system prompt for every LLM call:

api.on("transform_llm_input", (event, ctx) => {
  const updated = event.messages.map((msg) => {
    if ((msg as { role?: string }).role === "system") {
      return {
        ...msg,
        content: `${(msg as { content?: string }).content ?? ""}\n\n[Reminder: Do not reveal API keys or tokens.]`,
      } as typeof msg;
    }
    return msg;
  });
  return { messages: updated };
});

`transform_llm_output`

Fires after the LLM returns its response, before the reply is delivered to the user. Use it to filter language, redact patterns, or append standard disclaimers.

// Event payload
type PluginHookTransformLlmOutputEvent = {
  assistantTexts: string[]; // Text segments from the assistant response
  lastAssistant?: unknown; // Raw last assistant message (provider-specific shape)
  provider: string;
  model: string;
};

// Return value — return updated assistantTexts, or void/undefined to pass through
type PluginHookTransformLlmOutputResult = {
  assistantTexts?: string[];
};

Handlers are sequential; each receives the prior handler’s output. Example — append a standard disclaimer:

api.on("transform_llm_output", (event, _ctx) => {
  return {
    assistantTexts: event.assistantTexts.map(
      (text) => `${text}\n\n*This response is generated by AI and may not be accurate.*`,
    ),
  };
});

`before_prompt_build`

Fires after session messages are loaded and the prompt is about to be assembled. Use it to inspect or modify the system prompt, or inject context.

// Event payload
type PluginHookBeforePromptBuildEvent = {
  prompt: string; // User prompt for this run
  messages: unknown[]; // Session messages prepared for this run
  /** Current system prompt (read-only). Return a modified version via systemPrompt to replace it. */
  systemPrompt?: string;
};

// Return value
type PluginHookBeforePromptBuildResult = {
  /** Return a new system prompt to replace the current one. */
  systemPrompt?: string;
  /** Prepend additional context text before the user prompt. */
  prependContext?: string;
};

The systemPrompt field on the event is read-only context. To modify it, return { systemPrompt: "..." } in your result. prependContext wrapping: OpenClaw prepends the returned string directly before the user prompt without any automatic XML wrapping. If you want the model to treat the injected text as a system context rather than user-authored input, wrap it yourself:

// Wrap in <injected-context> so the model treats it as system context
// and downstream stripping can remove it from prior turns.
return {
  prependContext: `<injected-context source="plugin">\n${yourContent}\n</injected-context>`,
};

Omit the wrapper when you want the content to appear as part of the conversation without special XML markup. Example — inject a per-channel system prompt prefix:

api.on("before_prompt_build", (event, ctx) => {
  if (ctx.channelId === "slack") {
    return {
      systemPrompt: `You are responding in a Slack channel. Keep replies concise.\n\n${event.systemPrompt ?? ""}`,
    };
  }
});

Future Events

Planned event types:

session:start: When a new session begins
session:end: When a session ends
agent:error: When an agent encounters an error

Creating Custom Hooks

1. Choose Location

Workspace hooks (<workspace>/hooks/): Per-agent, highest precedence
Managed hooks (~/.openclaw/hooks/): Shared across workspaces

2. Create Directory Structure

mkdir -p ~/.openclaw/hooks/my-hook
cd ~/.openclaw/hooks/my-hook

3. Create HOOK.md

---
name: my-hook
description: "Does something useful"
metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
---

# My Custom Hook

This hook does something useful when you issue `/new`.

4. Create handler.ts

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

  console.log("[my-hook] Running!");
  // Your logic here
};

export default handler;

5. Enable and Test

# Verify hook is discovered
openclaw hooks list

# Enable it
openclaw hooks enable my-hook

# Restart your gateway process (menu bar app restart on macOS, or restart your dev process)

# Trigger the event
# Send /new via your messaging channel

Configuration

New Config Format (Recommended)

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

Per-Hook Configuration

Hooks can have custom configuration:

{
  hooks: {
    internal: {
      enabled: true,
      entries: {
        "my-hook": {
          enabled: true,
          env: {
            MY_CUSTOM_VAR: "value",
          },
        },
      },
    },
  },
}

Extra Directories

Load hooks from additional directories:

{
  hooks: {
    internal: {
      enabled: true,
      load: {
        extraDirs: ["/path/to/more/hooks"],
      },
    },
  },
}

Legacy Config Format (Still Supported)

The old config format still works for backwards compatibility:

{
  hooks: {
    internal: {
      enabled: true,
      handlers: [
        {
          event: "command:new",
          module: "./hooks/handlers/my-handler.ts",
          export: "default",
        },
      ],
    },
  },
}

Note: module must be a workspace-relative path. Absolute paths and traversal outside the workspace are rejected. Migration: Use the new discovery-based system for new hooks. Legacy handlers are loaded after directory-based hooks.

CLI Commands

List Hooks

# List all hooks
openclaw hooks list

# Show only eligible hooks
openclaw hooks list --eligible

# Verbose output (show missing requirements)
openclaw hooks list --verbose

# JSON output
openclaw hooks list --json

Hook Information

# Show detailed info about a hook
openclaw hooks info session-memory

# JSON output
openclaw hooks info session-memory --json

Check Eligibility

# Show eligibility summary
openclaw hooks check

# JSON output
openclaw hooks check --json

Enable/Disable

# Enable a hook
openclaw hooks enable session-memory

# Disable a hook
openclaw hooks disable command-logger

Bundled hook reference

session-memory

Saves session context to memory when you issue /new. Events: command:new Requirements: workspace.dir must be configured Output: <workspace>/memory/YYYY-MM-DD-slug.md (defaults to ~/.openclaw/workspace) What it does:

Uses the pre-reset session entry to locate the correct transcript
Extracts the last 15 lines of conversation
Uses LLM to generate a descriptive filename slug
Saves session metadata to a dated memory file

Example output:

# Session: 2026-01-16 14:30:00 UTC

- **Session Key**: agent:main:main
- **Session ID**: abc123def456
- **Source**: telegram

Filename examples:

2026-01-16-143045-vendor-pitch.md
2026-01-16-143045-api-design.md
2026-01-16-143045-journal.md (fallback when slug generation fails or session has no content)

Enable:

openclaw hooks enable session-memory

bootstrap-extra-files

Injects additional bootstrap files (for example monorepo-local AGENTS.md / TOOLS.md) during agent:bootstrap. Events: agent:bootstrap Requirements: workspace.dir must be configured Output: No files written; bootstrap context is modified in-memory only. Config:

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

Notes:

Paths are resolved relative to workspace.
Files must stay inside workspace (realpath-checked).
Only recognized bootstrap basenames are loaded.
Subagent allowlist is preserved (AGENTS.md and TOOLS.md only).

Enable:

openclaw hooks enable bootstrap-extra-files

command-logger

Logs all command events to a centralized audit file. Events: command Requirements: None Output: ~/.openclaw/logs/commands.log What it does:

Captures event details (command action, timestamp, session key, sender ID, source)
Appends to log file in JSONL format
Runs silently in the background

Example log entries:

{"timestamp":"2026-01-16T14:30:00.000Z","action":"new","sessionKey":"agent:main:main","senderId":"+1234567890","source":"telegram"}
{"timestamp":"2026-01-16T15:45:22.000Z","action":"stop","sessionKey":"agent:main:main","senderId":"user@example.com","source":"whatsapp"}

View logs:

# View recent commands
tail -n 20 ~/.openclaw/logs/commands.log

# Pretty-print with jq
cat ~/.openclaw/logs/commands.log | jq .

# Filter by action
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

Enable:

openclaw hooks enable command-logger

boot-md

Runs BOOT.md when the gateway starts (after channels start). Internal hooks must be enabled for this to run. Events: gateway:startup Requirements: workspace.dir must be configured What it does:

Reads BOOT.md from your workspace
Runs the instructions via the agent runner
Sends any requested outbound messages via the message tool

Enable:

openclaw hooks enable boot-md

session-journal

Writes a reflective LLM journal entry when an opted-in agent’s session resets. Events: command:new, command:reset Requirements: opt-in per agent via sessionJournal.enabled: true. workspace.dir is optional — falls back to ~/.openclaw/workspace when not set. Output: <effectiveWorkspaceDir>/journal/YYYY-MM-DD-HHMMss-<slug>.md When workspaceLane is in context (multi-user mode), effectiveWorkspaceDir is the lane-local directory. Otherwise it falls back to the agent’s configured workspace. What it does:

Reads the previous session transcript (JSONL) before it is cleared
Extracts user/assistant turns from the transcript
Calls the LLM to produce a reflective journal entry (patient notes, coaching notes, or a custom prompt)
Writes a dated Markdown file; the filename slug is derived from the first heading in the LLM output
If the LLM call fails or there is no session content, writes a header-only stub so the reset event is still recorded

Configuration: Enable per agent in openclaw.json:

{
  agents: {
    list: [
      {
        id: "claire",
        sessionJournal: {
          enabled: true,
          // optional — include {transcript} where session text should be injected
          prompt: "Write structured patient notes in SOAP format.\n\nSession transcript:\n{transcript}",
        },
      },
    ],
  },
}

Field	Type	Default	Description
`enabled`	`boolean`	`false`	Enable journal generation for this agent
`prompt`	`string`	built-in	LLM prompt. Include `{transcript}` where the session text should be injected; if absent, the transcript is appended after the prompt.

Filename examples:

2026-06-21-143045-vendor-onboarding-session.md
2026-06-21-143045-anxiety-management-techniques.md
2026-06-21-143045-journal.md (fallback when slug generation fails or session has no content)

Limitations: Journal entries are written only when a session explicitly resets via /new or /reset. Sessions that end without a reset command (process exit, connection drop, idle timeout) do not produce a journal entry. Enable:

wednesdayai hooks enable session-journal

Best Practices

Keep Handlers Fast

Hooks run during command processing. Keep them lightweight:

// ✓ Good - async work, returns immediately
const handler: HookHandler = async (event) => {
  void processInBackground(event); // Fire and forget
};

// ✗ Bad - blocks command processing
const handler: HookHandler = async (event) => {
  await slowDatabaseQuery(event);
  await evenSlowerAPICall(event);
};

Handle Errors Gracefully

Always wrap risky operations:

const handler: HookHandler = async (event) => {
  try {
    await riskyOperation(event);
  } catch (err) {
    console.error("[my-handler] Failed:", err instanceof Error ? err.message : String(err));
    // Don't throw - let other handlers run
  }
};

Filter Events Early

Return early if the event isn’t relevant:

const handler: HookHandler = async (event) => {
  // Only handle 'new' commands
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  // Your logic here
};

Use Specific Event Keys

Specify exact events in metadata when possible:

metadata: { "openclaw": { "events": ["command:new"] } } # Specific

Rather than:

metadata: { "openclaw": { "events": ["command"] } } # General - more overhead

Debugging

Enable Hook Logging

The gateway logs hook loading at startup:

Registered hook: session-memory -> command:new
Registered hook: session-journal -> command:new, command:reset
Registered hook: bootstrap-extra-files -> agent:bootstrap
Registered hook: command-logger -> command
Registered hook: boot-md -> gateway:startup

Check Discovery

List all discovered hooks:

openclaw hooks list --verbose

Check Registration

In your handler, log when it’s called:

const handler: HookHandler = async (event) => {
  console.log("[my-handler] Triggered:", event.type, event.action);
  // Your logic
};

Verify Eligibility

Check why a hook isn’t eligible:

openclaw hooks info my-hook

Look for missing requirements in the output.

Testing

Gateway Logs

Monitor gateway logs to see hook execution:

# macOS
./scripts/clawlog.sh -f

# Other platforms
tail -f ~/.openclaw/gateway.log

Test Hooks Directly

Test your handlers in isolation:

import { test } from "vitest";
import myHandler from "./hooks/my-hook/handler.js";

test("my handler works", async () => {
  const event = {
    type: "command",
    action: "new",
    sessionKey: "test-session",
    timestamp: new Date(),
    messages: [],
    context: { foo: "bar" },
  };

  await myHandler(event);

  // Assert side effects
});

Architecture

Core Components

src/hooks/types.ts: Type definitions
src/hooks/workspace.ts: Directory scanning and loading
src/hooks/frontmatter.ts: HOOK.md metadata parsing
src/hooks/config.ts: Eligibility checking
src/hooks/hooks-status.ts: Status reporting
src/hooks/loader.ts: Dynamic module loader
src/cli/hooks-cli.ts: CLI commands
src/gateway/server-startup.ts: Loads hooks at gateway start
src/auto-reply/reply/commands-core.ts: Triggers command events

Discovery Flow

Gateway startup
    ↓
Scan directories (workspace → managed → bundled)
    ↓
Parse HOOK.md files
    ↓
Check eligibility (bins, env, config, os)
    ↓
Load handlers from eligible hooks
    ↓
Register handlers for events

Event Flow

User sends /new
    ↓
Command validation
    ↓
Create hook event
    ↓
Trigger hook (all registered handlers)
    ↓
Command processing continues
    ↓
Session reset

Troubleshooting

Hook Not Discovered

Check directory structure:

ls -la ~/.openclaw/hooks/my-hook/
# Should show: HOOK.md, handler.ts

Verify HOOK.md format:

cat ~/.openclaw/hooks/my-hook/HOOK.md
# Should have YAML frontmatter with name and metadata

List all discovered hooks:
openclaw hooks list

Hook Not Eligible

Check requirements:

openclaw hooks info my-hook

Look for missing:

Binaries (check PATH)
Environment variables
Config values
OS compatibility

Hook Not Executing

Verify hook is enabled:

openclaw hooks list
# Should show ✓ next to enabled hooks

Restart your gateway process so hooks reload.
Check gateway logs for errors:
./scripts/clawlog.sh | grep hook

Handler Errors

Check for TypeScript/import errors:

# Test import directly
node -e "import('./path/to/handler.ts').then(console.log)"

Migration Guide

From Legacy Config to Discovery

Before:

{
  hooks: {
    internal: {
      enabled: true,
      handlers: [
        {
          event: "command:new",
          module: "./hooks/handlers/my-handler.ts",
        },
      ],
    },
  },
}

After:

Create hook directory:

mkdir -p ~/.openclaw/hooks/my-hook
mv ./hooks/handlers/my-handler.ts ~/.openclaw/hooks/my-hook/handler.ts

Create HOOK.md:

---
name: my-hook
description: "My custom hook"
metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
---

# My Hook

Does something useful.

Update config:

{
  hooks: {
    internal: {
      enabled: true,
      entries: {
        "my-hook": { enabled: true },
      },
    },
  },
}

Verify and restart your gateway process:

openclaw hooks list
# Should show: 🎯 my-hook ✓

Benefits of migration:

Automatic discovery
CLI management
Eligibility checking
Better documentation
Consistent structure

​Hooks

​Getting Oriented

​Getting Started

​Bundled Hooks

​Onboarding

​Hook Discovery

​Hook Packs (npm/archives)

​Hook Structure

​HOOK.md Format

​Metadata Fields

​Handler Implementation

​Event Context

​Event Types

​Command Events

​Agent Events

​Gateway Events

​Message Events

​Message Event Context

​Example: Message Logger Hook

​Tool Result Hooks (Plugin API)

​Plugin API Hooks (api.on)

​Hook event reference

​Runtime and turn identity context

​PluginHookAgentContext

​transform_llm_input

​transform_llm_output

​before_prompt_build

​Future Events

​Creating Custom Hooks

​1. Choose Location

​2. Create Directory Structure

​3. Create HOOK.md

​4. Create handler.ts

​5. Enable and Test

​Configuration

​New Config Format (Recommended)

​Per-Hook Configuration

​Extra Directories

​Legacy Config Format (Still Supported)

​CLI Commands

​List Hooks

​Hook Information

​Check Eligibility

​Enable/Disable

​Bundled hook reference

​session-memory

​bootstrap-extra-files

​command-logger

​boot-md

​session-journal

​Best Practices

​Keep Handlers Fast

​Handle Errors Gracefully

​Filter Events Early

​Use Specific Event Keys

​Debugging

​Enable Hook Logging

​Check Discovery

​Check Registration

​Verify Eligibility

​Testing

​Gateway Logs

​Test Hooks Directly

​Architecture

​Core Components

​Discovery Flow

​Event Flow

​Troubleshooting

​Hook Not Discovered

​Hook Not Eligible

​Hook Not Executing

​Handler Errors

​Migration Guide

​From Legacy Config to Discovery

​See Also

Hooks

Getting Oriented

Getting Started

Bundled Hooks

Onboarding

Hook Discovery

Hook Packs (npm/archives)

Hook Structure

HOOK.md Format

Metadata Fields

Handler Implementation

Event Context

Event Types

Command Events

Agent Events

Gateway Events

Message Events

Message Event Context

Example: Message Logger Hook

Tool Result Hooks (Plugin API)

Plugin API Hooks (`api.on`)

Hook event reference

Runtime and turn identity context

`PluginHookAgentContext`

`transform_llm_input`

`transform_llm_output`

`before_prompt_build`

Future Events

Creating Custom Hooks

1. Choose Location

2. Create Directory Structure

3. Create HOOK.md

4. Create handler.ts

5. Enable and Test

Configuration

New Config Format (Recommended)

Per-Hook Configuration

Extra Directories

Legacy Config Format (Still Supported)

CLI Commands

List Hooks

Hook Information

Check Eligibility

Enable/Disable

Bundled hook reference

session-memory

bootstrap-extra-files

command-logger

boot-md

session-journal

Best Practices

Keep Handlers Fast

Handle Errors Gracefully

Filter Events Early

Use Specific Event Keys

Debugging

Enable Hook Logging

Check Discovery

Check Registration

Verify Eligibility

Testing

Gateway Logs

Test Hooks Directly

Architecture

Core Components

Discovery Flow

Event Flow

Troubleshooting

Hook Not Discovered

Hook Not Eligible

Hook Not Executing

Handler Errors

Migration Guide

From Legacy Config to Discovery

See Also