OpenClaw hooks and webhooks

The word hook covers three different things in OpenClaw, and the docs open the hooks page with a table to keep them apart. Internal hooks are small handlers that run inside the Gateway process when an event fires; plugin hooks are typed handlers that modify prompts, intercept tools or control replies from inside the agent loop; webhooks are HTTP ingress, a way for another service to start work with a request. Here is which is for what, the bundled hook the docs suggest trying first, what the three status words actually prove, and the rules about where a hook is enabled and loaded.

Three surfaces

• Internal hooks, a hook file plus a handler: save context on a new-session command, log commands, react to session and message events. They run with the Gateway’s filesystem, network and environment access, so the docs say to review the code before enabling one.
• Plugin hooks, registered through the plugin API: modify prompts, intercept tools, claim or silence replies, with priorities and return values; they appear in the hooks list with a plugin prefix and are toggled by enabling the owning plugin.
• Webhooks, configured separately from internal hooks: they accept external requests that trigger work rather than subscribing to loop events, and they live on the cron page.
• Diagnostic events are a fourth surface for telemetry that changes nothing.

Internal hooks are trusted code, not sandboxed scripts.

The quick start

The docs start with the bundled command logger because it needs no binaries and no model calls and leaves a file you can inspect: list the hooks, read its info, enable it, on the Gateway host with the Gateway’s profile. The default hybrid reload applies the change without a restart. Send a new or reset command in a conversation you can safely reset, then read the last lines of the commands log under the OpenClaw directory and look for a JSON line with the action, a recent timestamp and that conversation’s session key. That proves a handler ran; the check command alone does not. The log holds session and sender identifiers, so disable the hook afterwards if you do not want those records.

Eligible, enabled, loaded

• Requirements satisfied: the hook’s OS, binaries, environment and config requirements pass on the host doing the check.
• Enabled by config: the per-hook policy allows it; workspace hooks need explicit opt-in, bundled and managed ones do not once broad discovery is on.
• Loaded: the running Gateway selected it, imported the handler and registered its events. The CLI’s ready, eligible and loadable fields cover the first two checks and a nonempty event list; they never prove the Gateway imported the handler or that an event fired, so check the side effect.

OpenClaw automations covers cron, the other half of event-driven work, and OpenClaw plugins the mechanism plugin hooks ride on.

Scope

The list, info and check commands ask the selected Gateway for its inventory, and a configured remote Gateway does not fall back to your laptop’s hooks; enable and disable always change local config, so run them on the Gateway host. The agent flag selects a workspace to inspect, not a separate registry: the saved entry is global, the Gateway loads directory hooks from its selected workspace into one process-wide registry, and a handler that should act for one agent has to filter the event itself. Config reload prepares the new handlers before swapping them, keeps the old ones if one fails to load, and never replays the startup event. OpenClaw as an AI agent shows where in the loop the plugin variety fires.

On Diali

On Diali the Gateway process is ours, which is why hooks that run as trusted code inside it are not something you upload: the event-driven work you can set up is automations and skills, and the boundary is the point. Hosted OpenClaw on Diali is the assistant.

• Internal hooks run in the Gateway; plugin hooks run in the loop; webhooks come from outside.
• Command logger first: it leaves a file that proves the handler ran.
• Ready and eligible are not loaded; the side effect is the proof.