Skip to main content

​
openclaw hooks

Manage agent hooks (event-driven automations for commands like /new, /reset, and gateway startup). Bare openclaw hooks is equivalent to openclaw hooks list. Related: Hooks - Plugin hooks

​
List hooks

Lists hooks discovered from workspace, managed, extra, and bundled directories.
  • --eligible: only hooks whose requirements are met.
  • --json: structured output.
  • -v, --verbose: include a Missing column with unmet requirements.

​
Get hook info

<name> is the hook name or hook key (for example session-memory). Shows source, file/handler paths, homepage, events, and per-requirement status (binaries, env, config, OS).

​
Check eligibility

Prints a ready/not-ready count summary; with hooks not ready, lists each with its blocking reason.

​
Enable a hook

Adds/updates hooks.internal.entries.<name>.enabled = true in config and also flips the hooks.internal.enabled master switch on (the gateway does not load any internal hook handler until at least one is configured). Fails if the hook does not exist, is plugin-managed, or is not eligible (missing requirements). Plugin-managed hooks show plugin:<id> in hooks list and cannot be enabled/disabled here; enable or disable the owning plugin instead. Restart the gateway after enabling (macOS menu bar app restart, or restart your gateway process in dev) so it reloads hooks.

​
Disable a hook

Sets hooks.internal.entries.<name>.enabled = false. Restart the gateway afterward.

​
Install and update hook packs

Hook packs install through the unified plugins installer/updater; openclaw hooks install / openclaw hooks update still work as deprecated aliases that print a warning and forward to the plugins commands.
  • Npm specs are registry-only: package name plus an optional exact version or dist-tag. Git/URL/file specs and semver ranges are rejected. Dependency installs run project-local with --ignore-scripts.
  • Bare specs and @latest stay on the stable track; if npm resolves to a prerelease, OpenClaw stops and asks you to opt in explicitly (@beta, @rc, or an exact prerelease version).
  • Supported archives: .zip, .tgz, .tar.gz, .tar.
  • -l, --link links a local directory instead of copying it (adds it to hooks.internal.load.extraDirs); linked hook packs are managed hooks from an operator-configured directory, not workspace hooks.
  • --pin records npm installs as an exact resolved name@version in hooks.internal.installs.
  • Install copies the pack into ~/.openclaw/hooks/<id>, enables its hooks under hooks.internal.entries.*, and records the install under hooks.internal.installs.
  • If a stored integrity hash no longer matches the fetched artifact, OpenClaw warns and prompts before continuing; pass global --yes to bypass the prompt (for example in CI).

​
Bundled hooks

Enable any bundled hook with openclaw hooks enable <hook-name>. Full details, config keys, and defaults: Bundled hooks.

​
command-logger log file

​
Notes

  • hooks list --json, info --json, and check --json write structured JSON directly to stdout.