OpenClaw hook configuration and discovery

The hooks that run are the product of two decisions: which sources the Gateway scans and which names it selects. OpenClaw makes the safe shape easy, enable named hooks rather than turning on broad discovery, and the docs spell out exactly how the master switch, named entries, extra directories and tracked packs combine. Here is the selection table, the per-hook settings and env rule, the retired key and its migration, the five discovery sources and how collisions resolve, what counts as a pack versus a collection, and how packs are installed.

Selection

• With the master switch off, internal hooks are off; with no master flag and no enabled entries, extra directories or tracked installs, the Gateway skips directory-hook loading entirely.
• Named entries with the master flag omitted or true form an allowlist, and a true master flag does not broaden it; an entry without an explicit false contributes its name. A true master flag with no named entries or named installs means open-ended discovery of eligible hooks, and so does a non-empty extra-directories list or a tracked install without a hook-name list.
• Tracked hook packs that declare hook names join the selection, while an explicit per-hook false still disables a non-plugin hook; workspace hooks always need an explicit enable even under open-ended discovery, and adding the first named entry can narrow a previously broad selection, so inspect existing hooks before changing it.
• Entries accept arbitrary handler-defined fields, with only the enabled boolean and the env map typed by core; per-hook env satisfies eligibility checks but does not mutate the process environment, and a handler reads it from the config carried on events that include one, since other events do not promise a config field.

Only add trusted directories: any extra path opens hook-name selection across discovery sources beyond named entries, even when that path selects a single hook or pack.

Discovery sources

Directory discovery merges hooks by name across five sources. Bundled hooks ship with OpenClaw; plugin hook directories declared by active plugins can replace bundled names; the managed directory under the state directory can replace bundled and plugin names; extra directories follow the same policy as managed hooks, later ones winning over earlier ones and the managed directory winning over all of them; and the workspace hooks folder can add names but never replace bundled, plugin or managed ones, and requires explicit opt-in. Bundled, managed, workspace and plugin locations are collection directories whose immediate children are inspected for hooks or packages declaring hooks in their package manifest. An explicit extra-directories path can instead be a pack root, which loads only its declared hook paths without recursing into other packs or collections and stays empty when it declares no valid hooks, or a single-hook root, which loads its own hook manifest and handler; only an ordinary collection root gets the immediate-child scan. Handler files must stay within their hook directory and package hook paths within their package root, with escaping symlinks rejected. Hook config and selected-workspace changes reload discovery in hybrid mode, including config written by a new pack install, but hook files and metadata are not watched, so editing existing hook code needs a restart followed by checking the handler’s actual side effect.

Migration and packs

• The old handlers key is retired and fails normal validation: before running the doctor fix, migrate each registered module into a managed or workspace hook directory with a hook manifest and a handler, because doctor removes the old registrations without creating executable files; for a legacy-only config with the master flag on, doctor also removes that flag to avoid broad discovery, while named entries, non-empty extra directories and explicit disables are preserved.
• A hook pack is a package whose manifest declares hook directories, installed as a reviewed package or local directory through the unified plugin installer; installation and update flags, npm restrictions, linked-root trust and the deprecated hooks install aliases are documented with the CLI.
• For predictable behaviour the docs recommend the allowlist shape: master switch on, each wanted hook named and enabled, unwanted bundled ones named and disabled, and no extra directories unless you accept that they widen selection across every source.

OpenClaw hooks and webhooks is the guide this configuration serves, and OpenClaw plugins the installer hook packs go through and the source that can override bundled names.

Why the order matters

The replace rules are a trust order: managed beats plugin beats bundled, and the workspace can only add, which keeps a file the agent writes into its own workspace from silently replacing a hook the operator installed. OpenClaw doctor performs the migration of the retired key, and The OpenClaw agent workspace explains the workspace folder that gets the add-only rule.

On Diali

On Diali the managed and workspace hook directories live on the assistant’s volume, and the named-entry allowlist is the safer shape here too, since open-ended discovery would pick up anything the assistant itself writes into its workspace hooks folder. Hosted OpenClaw on Diali is the assistant and Diali security describes the boundary around it.

• Name the hooks you want; do not open discovery.
• Managed beats plugin beats bundled; workspace only adds.
• Env satisfies eligibility; it never touches the process.