openclaw hooks CLI reference

`openclaw hooks`

Handle agent hooks: event driven automations for commands including /new, /reset, and gateway startup. Running openclaw hooks by itself does the same thing as openclaw hooks list.

List hooks

openclaw hooks list [--eligible] [--json] [-v|--verbose]

Show hooks discovered from workspace, managed, extra, and bundled directories.

--eligible: only hooks whose dependencies are satisfied.
--json: output in structured format.
-v, --verbose: add a Missing column listing unmet dependencies.

Hooks (4/5 ready)

Ready:
  🚀 boot-md ✓ - Run BOOT.md on gateway startup
  📎 bootstrap-extra-files ✓ - Inject additional workspace bootstrap files during agent bootstrap
  📝 command-logger ✓ - Log all command events to a centralized audit file
  💾 session-memory ✓ - Save session context to memory when /new or /reset command is issued

Get hook info

openclaw hooks info <name> [--json]

Pass the hook name or hook key, for instance session-memory, as <name>. Displays the source, file and handler paths, homepage, events, and per requirement status (binaries, environment variables, configuration, operating system).

Check eligibility

openclaw hooks check [--json]

Outputs a count summary showing ready versus not ready hooks; for any hooks that are not ready, each one is listed along with the reason blocking it.

Enable a hook

openclaw hooks enable <name>

Adds or updates hooks.internal.entries.<name>.enabled = true in configuration and also turns on the hooks.internal.enabled master switch. Without at least one configured hook, the gateway will not load any internal hook handler. The command fails when the hook does not exist, is managed by a plugin, or is ineligible because requirements are missing.

Hooks under plugin management display plugin:<id> in hooks list and cannot be toggled here; instead, enable or disable the owning plugin.

After enabling, restart the gateway (restart the macOS menu bar app or restart your gateway process in development mode) so hooks are reloaded.

Disable a hook

openclaw hooks disable <name>

Sets hooks.internal.entries.<name>.enabled = false. Restart the gateway after doing so.

Install and update hook packs

openclaw plugins install <package>        # npm by default
openclaw plugins install npm:<package>    # npm only
openclaw plugins install <package> --pin  # pin resolved version
openclaw plugins install <path>           # local directory or archive
openclaw plugins install -l <path>        # link a local directory instead of copying

openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins update --dry-run

Hook packs are installed through the unified plugins installer/updater. The older openclaw hooks install and openclaw hooks update commands still work as deprecated aliases that show a warning and forward to the plugins commands.

Npm specifications are registry only: a package name plus an optional exact version or dist tag. Git, URL, and file specifications, along with semver ranges, are not accepted. Dependencies are installed project locally with --ignore-scripts.
Bare specifications and @latest remain on the stable track. If npm resolves to a prerelease, OpenClaw halts and asks you to explicitly opt in using @beta, @rc, or an exact prerelease version.
Supported archive formats: .zip, .tgz, .tar.gz, .tar.
-l, --link creates a symbolic link to a local directory instead of copying it, adding 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 the shared SQLite state.
Installation copies the pack into ~/.openclaw/hooks/<id>, enables its hooks under hooks.internal.entries.*, and records install provenance in the shared SQLite state.
When a stored integrity hash no longer matches the fetched artifact, OpenClaw warns and asks for confirmation before proceeding. Pass the global --yes flag to skip the prompt, for instance in CI.

Bundled hooks

Hook	Events	What it does
boot-md	`gateway:startup`	At gateway startup, `BOOT.md` executes for every configured agent scope
bootstrap-extra-files	`agent:bootstrap`	During agent bootstrap, extra bootstrap files (such as monorepo `AGENTS.md`/`TOOLS.md`) are injected
command-logger	`command`	Command events get logged to `~/.openclaw/logs/commands.log`
compaction-notifier	`session:compact:before`, `session:compact:after`	Visible chat notices are sent when session compaction starts and ends
session-memory	`command:new`, `command:reset`	Session context is saved to memory on `/new` or `/reset`

Activate any built-in hook using openclaw hooks enable <hook-name>. Complete documentation, configuration keys, and default values are at Bundled hooks.

command-logger log file

tail -n 20 ~/.openclaw/logs/commands.log        # recent commands
cat ~/.openclaw/logs/commands.log | jq .          # pretty-print
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .   # filter by action

Notes

Structured JSON is written directly to stdout by hooks list --json, info --json, and check --json.