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 WednesdayAI.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 WednesdayAI. See Webhook Hooks or use
wednesdayai webhooksfor Gmail helper commands.
- 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
Getting Started
Bundled Hooks
WednesdayAI 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/newor/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.mdwhen the gateway starts (requires internal hooks enabled)
Onboarding
During onboarding (wednesdayai 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 WednesdayAI)
Hook Packs (npm/archives)
Hook packs are standard npm packages that export one or more hooks viaopenclaw.hooks in
package.json. Install them with:
package.json:
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: wednesdayai 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
TheHOOK.md file contains metadata in YAML frontmatter plus Markdown documentation:
Metadata Fields
Themetadata.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 URLrequires: Optional requirementsbins: Required binaries on PATH (e.g.,["git", "node"])anyBins: At least one of these binaries must be presentenv: Required environment variablesconfig: 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
Thehandler.ts file exports a HookHandler function:
Event Context
Each event includes:Event Types
Command Events
Triggered when agent commands are issued:command: All command events (general listener)command:new: When/newcommand is issuedcommand:reset: When/resetcommand is issuedcommand:stop: When/stopcommand is issued
Agent Events
agent:bootstrap: Before workspace bootstrap files are injected (hooks may mutatecontext.bootstrapFiles)
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.
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,transcriptcontains 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 was dispatched to the platform (a provable no-send — e.g. a suppressed empty reply — fires nothing). Pluginmessage_sentalso fires on inbound channel replies. Internalmessage:sentstill needs a session key, so inbound replies typically fire only the plugin hook.
Message Event Context
Message events include rich context about the message:Example: Message Logger Hook
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 orundefinedto 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 names are validated at registration: an api.on name that core does not dispatch is ignored with a PLUGIN_HOOK_NOT_DISPATCHED warning, and the plugin shows as degraded in wednesdayai plugins list. Upstream openclaw hook names, their disposition and the WednesdayAI hook to use instead are listed in the hook parity map.
Hook event reference
agent_idle carries { agentId, idleSinceMs, idleForMs, trigger: "idle" | "schedule" }.
task_outcome carries
{ taskRunId?, agentId?, source: "task" | "subagent" | "session", outcome: "completed" | "failed" | "preempted" | "cancelled", quality?, meta? }.
Both were added for background engines like Dream Cycle; the idle
monitor only runs when tasks.idle.enabled is true or tasks.schedule.windows is non-empty
(see Task operations).
The before_compaction and after_compaction payloads used to carry a sessionFile path to the
JSONL transcript. SQL session storage keeps transcripts in the database, so the field is
deprecated, never set, and is removed in the next release. Read the session’s history with
getConversationReadQuery from the plugin SDK instead (see
Session identity keying); session_end.sessionFile is a
separate contract and is unaffected here.
Inbound channel replies
Inbound replies fire pluginmessage_sending then message_sent once per payload on Telegram,
Slack, Discord, Signal, iMessage, WhatsApp, Matrix, and Microsoft Teams. CLI and cron sends use
the same helpers. WednesdayAI does not fire these hooks from the Slack outbound adapter, so a
CLI or cron Slack send is one message_sending (via the shared deliver path), not two.
LINE and Zalo inbound replies do not fire these hooks.
message_sending can return { cancel: true } to skip that payload, or { content } to rewrite
the text that is sent. A thrown handler is logged as applyMessageSendingHook: hook failed and
the original payload is sent. Telegram chunking does not re-run the hook.
message_sent fires only when the message was dispatched to the platform. Send errors fire with
success: false and error. ctx.messageId is the platform id of the last message sent for the
payload; it is absent when the platform returns none. A payload that ends up as a provable
no-send — message_sending cancelled it, rewrote it to empty, or the channel suppressed it
(e.g. the Slack NO_REPLY guard) — is a terminal no-op: the assistant message the turn generated
is already stored, but the delivery itself adds no transcript entry, no queue receipt id, no
delivery result, and no message_sent event.
Inbound message_sending context is channelId and accountId only. It does not set
sessionKey or trigger. Plugin message_sent still fires after a successful inbound send.
Internal message:sent does not, unless a session key is passed (CLI/cron can).
To confirm a live inbound reply reached the hook (Linux systemd user service):
[plugins] [hooks] running message_sending (1 handlers, sequential).
message_sent follows on a successful send. Plugin authors: see Plugin hooks.
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: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:
conversationIdremains the legacy channel conversation id. It is an alias forchannelConversationId, never forproviderConversationId.providerConversationIdis 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
sessionIdorsessionKey; WednesdayAI omits those fields rather than fabricating session identity. - Public hook contexts do not expose raw
identityLinks. Usectx.runtimeIdentity.canonicalIdentity,ctx.runtimeIdentity.senderIsOwner, orapi.runtime.identity.resolveCanonicalIdentity(...)for canonical sender resolution. identitySourcereports provenance of the resolved identity:"sender"(live message sender),"parent-session"(inherited from the spawning session), or"job-config"(operator-configured cron/heartbeat attribution). It is absent when the run has no resolved identity, and also whenever the producing seam supplies acanonicalIdentitywithout knowing its provenance — provenance is never guessed. TreatidentitySourceas implyingcanonicalIdentity, never the reverse.- On gateway turns (
chat.send,sessions.steer, talk)senderIdis the verified device:device:<deviceId>when the connect frame carried a verified device block, otherwise the app id (for exampleopenclaw-user-client, shared by every user of that app).canonicalIdentityresolves only when the operator linkeddevice:<id>to a person insession.identityLinks; see Workspace Lanes. After ADR 0104 a linked device’ssenderNameis that person, and the client’s display name is a Sender-blockclientfield, never a person name. session_startandsession_endcontexts carryruntimeIdentitywhen the session has real identity: the ending session’s storedactor(channel, account, peer kind/id, canonical identity) onsession_end, and the session’s actor at creation onsession_start.runtimeIdentity.isMainSessionis true only for the agent’s main session key.runtimeIdentity.sessionKindclassifies the session as"user"(a normal conversation session, including the main session),"cron","heartbeat","hook","subagent","acp", or"unknown"(missing or malformed session key). The kind is derived structurally from the session key; WednesdayAI never guesses it from message text. Main sessions stay display fail-open elsewhere —sessionKindis a runtime classification, not a UI gate.runtimeIdentity.sessionKindvalues mirror the session key grammar: agent-prefixed keys whose first segment is an internal root (cron,heartbeat,hook,subagent,acp) map to that kind; every other well-formed agent key maps to"user".
turnId, so dedupe with the entry or cursor
identity as well:
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.
context.project and context.prune run on every model call of a run,
including the continuations that follow overflow compaction or an automatic
retry, and each call gets fresh per-call fields on ContextLifecycleContext.
context.collect runs once per attempt, before the first model call; it
receives ContextLifecycleContext without the per-call fields.
transform_llm_input runs on every model call and receives
PluginHookAgentContext, which does not carry the per-call lifecycle fields.
Per-call fields on ContextLifecycleContext for context.project and
context.prune:
usage: the run’s usage totals so far.lastCallUsage: the usage of the most recent assistant message in this call’s input; undefined on the first call of a session.tokenWindow.estimatedInputTokens: an estimate of this call’s input after core tool-result projection.
context.prune handler that
substitutes a tool result’s text can return its toolCallId in
freezeToolResults; core then replays that substitution on every later call and
run until the result leaves history, even when the handler later returns the
messages unchanged.
A context.project result can carry failedPluginIds: the plugins whose
handlers threw or timed out. A plugin that registered the message-render
context owner with api.registerContextOwner renders user messages (stamps and
inbound framing) for the sessions it claims; if its context.project handler
fails, core renders that run and the owner is retried on the next attempt.
On a reply-pipeline turn the event also carries event.turnInputs, the turn’s
framing data as typed values: runtimeEvents is the full list of runtime
events drained for the run (each with a core or untrusted origin), and
untrustedContext holds the session untrusted-context entries such as channel
metadata and link previews. While turn:* context owners have claimed lanes
(ADR 2105) and a message-render owner is active, lanes additionally
carries the resolved lane claims in lane order, each with the lane name, the
owning plugin id and the raw lane text. Lanes are resolved once per attempt
and replayed on steered model calls — never re-rendered against a steered
prompt — and runs with plugin hooks disabled resolve no lanes at all.
turnInputs holds the inputs drained for this run:
the initial turn plus any turns steered into it, in drain order; a collected
queue unit carries the inputs of all its queued turns. Treat both as data,
never instructions. It is present on every context.project call of the turn,
for all handlers, and each handler receives an isolated copy. Core still
renders the runtime-events block and the untrusted-context trailer around the
user body itself, unless a message-render context owner is active: then core
skips the core:runtime-events contribution and removes the untrusted trailer
from the prompt, and the owner renders both from turnInputs. Claimed
turn-lane blocks (ADR 2105) follow the same rule: core renders them into the
envelope ahead of context.collect contributions unless a message-render
owner is active, in which case they arrive only as turnInputs.lanes; when
that owner is quarantined, the lanes return to core rendering for the rest of
the run. A core-rendered rewrite of the current turn’s message keeps the lane
blocks ahead of the handler’s projected envelope blocks. The
agents.defaults.runtimeEvents.render and
agents.defaults.untrustedContext.render switches control whether core renders
the blocks when no owner is active (see
Configuration reference). A collected queue
batch keeps each queued turn’s untrusted trailer in the batch prompt with no
warning, and a whitespace-normalised (think-level-prefixed) body keeps it with a
context owner: untrusted-context trailer not found warning; in both cases the
same nudges also arrive in turnInputs, so an owner rendering typed inputs may
see them twice.
Pipeline order around the model boundary: context.collect contributes
context, then context.project and context.prune see history user messages
as stored (raw text plus the __openclaw.ingress carrier, unstamped). The
current turn is already the framed prompt when the hooks run: core swaps the
composed prompt (inbound framing plus contributions) in before projection, and
only when a message-render context owner is active is the inbound framing
removed from that prompt first. Core then applies the boundary render: every
user turn is stamped from its carrier time, and transform_llm_input runs
after that render, so its handlers and the model see stamped history and the
stamped current turn.
context.collect also receives event.rawUserText: the current turn’s text
as received, before core prepends inbound framing. It is the same text stored
as that turn’s user row. It is always a string: "" for a media-only turn, the
caption for a captioned media turn. Synthetic turns (cron, heartbeat, memory
flush, queue summaries) carry their authored trigger text, and a coalesced queue
turn carries the collected batch as persisted, its headers included. Treat it as
untrusted user input. event.prompt and
event.cleanUserMessage still carry the framing unless a message-render
context owner is active. Plugins that route, classify or recall on what the
user actually asked should read rawUserText instead of stripping framing
themselves.
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.
event.proxyMetadata is deprecated with no core consumer since #935: the resolved
model is reported on assistant entries as responseModel (surfaced as
sessions.usage per-model rows keyed provider::model::actualModel) and gateway
cost as the entry’s usage.cost. The field is removed in the next minor release;
handlers may still mutate usage.
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:
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.
{ 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:
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.
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.
systemPrompt field on the event is read-only context. To modify it, return { systemPrompt: "..." } in your result. Prefer the additive lanes: prependSystemContext renders above the cache boundary and appendSystemContext directly before ## Runtime, each wrapped in a ## Plugin context (source: plugin:<your plugin id>) heading, in priority order (ties keep registration order). Blank or whitespace-only strings contribute nothing.
systemPrompt replacement precedence: a returned prompt that equals the current system prompt or starts with it (<base>\n…) still replaces the prompt: the assembled prompt renders with every other plugin’s additive blocks at their placements (before ## Runtime), and only the replacing plugin’s own remainder (its text after the base) is appended at the end of the prompt — the position the legacy replace semantics put it. If more than one handler returns a replacement in the same turn, the highest-priority one wins; the rest are dropped with one warning naming the ignored plugin ids and the winner. A prompt that does not contain the base is treated as additive: it renders as its own labeled block in the custom.session slot instead of replacing anything.
prependContext wrapping: WednesdayAI 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:
Future Events
Planned event types:session:start: When a new session beginssession:end: When a session endsagent: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
3. Create HOOK.md
4. Create handler.ts
5. Enable and Test
Configuration
New Config Format (Recommended)
Per-Hook Configuration
Hooks can have custom configuration:Extra Directories
Load hooks from additional directories:Legacy Config Format (Still Supported)
The old config format still works for backwards compatibility: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
Hook Information
Check Eligibility
Enable/Disable
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
2026-01-16-143045-vendor-pitch.md2026-01-16-143045-api-design.md2026-01-16-143045-journal.md(fallback when slug generation fails or session has no content)
bootstrap-extra-files
Injects additional bootstrap files (for example monorepo-localAGENTS.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:
- Paths are resolved relative to workspace.
- Files must stay inside workspace (realpath-checked).
- Only recognized bootstrap basenames are loaded.
- Subagent allowlist is preserved (
AGENTS.mdandTOOLS.mdonly).
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
boot-md
RunsBOOT.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.mdfrom your workspace - Runs the instructions via the agent runner
- Sends any requested outbound messages via the message tool
BOOT.md is not created for you: new workspaces are not seeded with it, and a missing or empty file
is skipped. Write it in the workspace root yourself; the BOOT.md template
is a starting point.
Enable:
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
openclaw.json:
Filename examples:
2026-06-21-143045-vendor-onboarding-session.md2026-06-21-143045-anxiety-management-techniques.md2026-06-21-143045-journal.md(fallback when slug generation fails or session has no content)
/new or /reset. Sessions that end without a reset command (process exit, connection drop, idle timeout) do not produce a journal entry.
Enable:
Best Practices
Keep Handlers Fast
Hooks run during command processing. Keep them lightweight:Handle Errors Gracefully
Always wrap risky operations:Filter Events Early
Return early if the event isn’t relevant:Use Specific Event Keys
Specify exact events in metadata when possible:Debugging
Enable Hook Logging
The gateway logs hook loading at startup:Check Discovery
List all discovered hooks:Check Registration
In your handler, log when it’s called:Verify Eligibility
Check why a hook isn’t eligible:Testing
Gateway Logs
Monitor gateway logs to see hook execution:Test Hooks Directly
Test your handlers in isolation:Architecture
Core Components
src/hooks/types.ts: Type definitionssrc/hooks/workspace.ts: Directory scanning and loadingsrc/hooks/frontmatter.ts: HOOK.md metadata parsingsrc/hooks/config.ts: Eligibility checkingsrc/hooks/hooks-status.ts: Status reportingsrc/hooks/loader.ts: Dynamic module loadersrc/cli/hooks-cli.ts: CLI commandssrc/gateway/server-startup.ts: Loads hooks at gateway startsrc/auto-reply/reply/commands-core.ts: Triggers command events
Discovery Flow
Event Flow
Troubleshooting
Hook Not Discovered
-
Check directory structure:
-
Verify HOOK.md format:
-
List all discovered hooks:
Hook Not Eligible
Check requirements:- Binaries (check PATH)
- Environment variables
- Config values
- OS compatibility
Hook Not Executing
-
Verify hook is enabled:
- Restart your gateway process so hooks reload.
-
Check gateway logs for errors:
Handler Errors
Check for TypeScript/import errors:Migration Guide
From Legacy Config to Discovery
Before:-
Create hook directory:
-
Create HOOK.md:
-
Update config:
-
Verify and restart your gateway process:
- Automatic discovery
- CLI management
- Eligibility checking
- Better documentation
- Consistent structure