OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Automation

Hooks

Hooks

Internal hooks are small JavaScript or TypeScript handlers that run in the Gateway process when OpenClaw emits an event. Use them to save session context, log reset commands, or perform short side effects during message and session lifecycle events. OpenClaw includes bundled hooks for common tasks; you do not need to write a plugin to use them.

Choose the right surface

You want to… Use
Save context on /new, log commands, or react to session and message events Internal hooks (HOOK.md plus a handler), described here
Modify prompts, intercept tools, control replies, or use lifecycle contracts with priorities and return values Plugin hooks through api.on(...)
Let another service start work through an HTTP request Webhooks
Export telemetry rather than change behavior Diagnostic events

These are separate systems. hooks.internal configures this page's event handlers; hooks.enabled configures HTTP ingress. Internal event names such as message:received are not typed plugin names such as message_received.

Quick start

Start with command-logger: it needs no extra binaries or model calls and gives you a concrete file to inspect. Run these commands on the Gateway host, with the same profile and config as that Gateway:

bash
openclaw hooks listopenclaw hooks info command-loggeropenclaw hooks enable command-logger

The default hybrid reload mode applies hook config changes without a restart. With reload mode off, run openclaw gateway restart, or restart a foreground Gateway yourself. Add --agent <id> when your configuration has multiple agents and no implicit owner.

In a conversation you can safely reset, send /new or /reset as an authorized user. Then inspect the log on the Gateway host:

bash
tail -n 5 ~/.openclaw/logs/commands.log

Look for a new JSON line with "action":"new" or "action":"reset", a recent timestamp, and that conversation's sessionKey. With a custom state directory, read <stateDir>/logs/commands.log instead. This proves that a handler ran; openclaw hooks check alone does not.

The log contains session and sender identifiers. Disable the hook after trying it if you do not want to retain those records:

bash
openclaw hooks disable command-logger

Eligible, enabled, and loaded

Keep these three checks separate:

  • Requirements satisfied: the hook's OS, binaries, environment, and config requirements pass on the host doing the check.
  • Enabled by config: the per-hook/source policy allows it. Workspace hooks require explicit opt-in; bundled and managed hooks do not require that per-hook flag when broad discovery is enabled.
  • Loaded: the running Gateway selected the hook, imported its handler, and registered its events. This also requires the master switch and configured name selection to allow it.

The CLI's ready, eligible, and loadable fields describe the first two checks plus a nonempty event list. They do not prove that the Gateway imported the handler, that the global selection includes it, or that its event has fired. After changes, check the actual side effect or hook-specific log.

Config reload prepares the selected handlers before replacing them together. If a selected handler cannot load, the previous handlers stay active. An event already running finishes with its original handlers; subsequent events use the new selection. Reload does not replay gateway:startup.

Local, remote, and agent scope

hooks list, info, and check request the selected Gateway's inventory. An implicit local Gateway can fall back to local discovery when unavailable or when it lacks the report method. A configured remote Gateway or explicit OPENCLAW_GATEWAY_URL does not fall back to your laptop's hooks on failure.

hooks enable and hooks disable always inspect and modify local config. They do not update a remote Gateway over RPC. Run them on the Gateway host to change that host's hooks.

--agent <id> selects the workspace to inspect, not an isolated hook registry. The saved hooks.internal.entries.<hookKey> entry is global. The Gateway loads directory hooks from its selected workspace into a process-wide registry; it does not load every agent's hooks/ directory merely because you inspected it. A loaded handler must filter the event's agent or session when it should only act for a particular agent. See Hook discovery.

Plugin hooks

Plugin-managed internal hooks appear as plugin:<id> in hooks list. They participate in this event system, but you enable or disable the owning plugin rather than toggling them with hooks enable or hooks disable. The directory loader's configured-name selection is not a policy gate for typed api.on hooks or a substitute for plugin activation.

The legacy api.registerHook API registers internal events. It does not invoke typed lifecycle names such as before_tool_call, message_received, or session_start; registering those names emits a warning directing authors to api.on(...). For new integrations needing typed lifecycle control, use the Plugin hooks reference.

Best practices

Handlers for one event run sequentially: family listeners first, then exact listeners, in registration order within each group. The dispatcher awaits each handler, catches and logs thrown errors, and continues to later handlers. There is no priority option for directory hooks.

This sequencing does not serialize different events. Message notifications, patch notifications, and automatic reset work can overlap with other events and agent processing. There is no general handler timeout, cancellation signal, durable event queue, automatic retry, or exactly-once guarantee. Restart or process exit can lose in-flight work.

Keep side effects short and bounded. Await the work that belongs to the handler, set timeouts on network calls, limit data sizes, and make repeatable operations idempotent. Do not use void doHeavyWork(event) as a general solution: that work escapes the handler's wait/error boundary and can outlive its session or process. If work needs a durable job lifecycle, use an automation or service that owns it.

Filter unrelated events early and avoid logging message bodies, whole config objects, or credentials. Message and session data can be private. Keep only the minimum needed for the side effect, protect output files, and set retention. Long-lived timers, watchers, sockets, and clients belong to a plugin service with an explicit shutdown lifecycle, not a request/event handler.

CLI reference

See openclaw hooks for every public report and toggle option, JSON output fields, exit behavior, and install/update aliases.

Detailed topics

These pages hold the reference and how-to material that used to follow the quick start on this page.

Page Read it when
Writing hooks You are writing a hook and need the file layout, handler contract, or HOOK.md fields.
Hook configuration and discovery You are enabling hooks, narrowing the selection, or tracing discovery across sources.
Bundled hooks You want a shipped hook and need its behavior, options, and checks.
Hook event types and context You need an event key's trigger, wait behavior, or context fields.
Hook troubleshooting A hook is not discovered, not eligible, or not executing.

Where each section moved

Every section heading from the previous single-page version keeps its anchor here, so an existing link such as /automation/hooks#session-memory still resolves. Each entry points at the page that now holds the content.

Was this useful?
On this page

On this page