Hooks

text

Copy

openclaw hooks

Manage agent hooks (event-driven automations for commands like

, , and gateway startup).

Running

with no subcommand is equivalent to .

Related:

• Hooks: Hooks
• Plugin hooks: Plugin hooks

List all hooks

bash
Copy
openclaw hooks list

List all discovered hooks from workspace, managed, extra, and bundled directories. Gateway startup does not load internal hook handlers until at least one internal hook is configured.

Options:

• text

  Copy

  --eligible
  : Show only eligible hooks (requirements met)
• text

  Copy

  --json
  : Output as JSON
• text

  Copy

  -v, --verbose
  : Show detailed information including missing requirements

Example output:

text
Copy
Hooks (4/4 ready)

Ready:
  🚀 boot-md ✓ - Run BOOT.md on gateway startup
  📎 bootstrap-extra-files ✓ - Inject extra 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

Example (verbose):

bash
Copy
openclaw hooks list --verbose

Shows missing requirements for ineligible hooks.

Example (JSON):

bash
Copy
openclaw hooks list --json

Returns structured JSON for programmatic use.

Get hook information

bash
Copy
openclaw hooks info <name>

Show detailed information about a specific hook.

Arguments:

• text

  Copy

  <name>
  : Hook name or hook key (e.g.,
  text

  Copy

  session-memory
  )

Options:

• text

  Copy

  --json
  : Output as JSON

Example:

bash
Copy
openclaw hooks info session-memory

Output:

text
Copy
💾 session-memory ✓ Ready

Save session context to memory when /new or /reset command is issued

Details:
  Source: openclaw-bundled
  Path: /path/to/openclaw/hooks/bundled/session-memory/HOOK.md
  Handler: /path/to/openclaw/hooks/bundled/session-memory/handler.ts
  Homepage: https://docs.openclaw.ai/automation/hooks#session-memory
  Events: command:new, command:reset

Requirements:
  Config: ✓ workspace.dir

Check hooks eligibility

bash
Copy
openclaw hooks check

Show summary of hook eligibility status (how many are ready vs. not ready).

Options:

• text

  Copy

  --json
  : Output as JSON

Example output:

text
Copy
Hooks Status

Total hooks: 4
Ready: 4
Not ready: 0

Enable a Hook

bash
Copy
openclaw hooks enable <name>

Enable a specific hook by adding it to your config (

by default).

Note: Workspace hooks are disabled by default until enabled here or in config. Hooks managed by plugins show

in and can’t be enabled/disabled here. Enable/disable the plugin instead.

Arguments:

• text

  Copy

  <name>
  : Hook name (e.g.,
  text

  Copy

  session-memory
  )

Example:

bash
Copy
openclaw hooks enable session-memory

Output:

text
Copy
✓ Enabled hook: 💾 session-memory

What it does:

• Checks if hook exists and is eligible
• Updates
  text

  Copy

  hooks.internal.entries.<name>.enabled = true
  in your config
• Saves config to disk

If the hook came from

, this opt-in step is required before the Gateway will load it.

After enabling:

• Restart the gateway so hooks reload (menu bar app restart on macOS, or restart your gateway process in dev).

Disable a Hook

bash
Copy
openclaw hooks disable <name>

Disable a specific hook by updating your config.

Arguments:

• text

  Copy

  <name>
  : Hook name (e.g.,
  text

  Copy

  command-logger
  )

Example:

bash
Copy
openclaw hooks disable command-logger

Output:

text
Copy
⏸ Disabled hook: 📝 command-logger

After disabling:

• Restart the gateway so hooks reload

Notes

• text

  Copy

  openclaw hooks list --json
  ,
  text

  Copy

  info --json
  , and
  text

  Copy

  check --json
  write structured JSON directly to stdout.
• Plugin-managed hooks cannot be enabled or disabled here; enable or disable the owning plugin instead.

Install hook packs

bash
Copy
openclaw plugins install <package>        # ClawHub first, then npm
openclaw plugins install npm:<package>    # npm only
openclaw plugins install <package> --pin  # pin version
openclaw plugins install <path>           # local path

Install hook packs through the unified plugins installer.

still works as a compatibility alias, but it prints a deprecation warning and forwards to .

Npm specs are registry-only (package name + optional exact version or dist-tag). Git/URL/file specs and semver ranges are rejected. Dependency installs run project-local with

for safety, even when your shell has global npm install settings.

Bare specs and

stay on the stable track. If npm resolves either of those to a prerelease, OpenClaw stops and asks you to opt in explicitly with a prerelease tag such as / or an exact prerelease version.

What it does:

• Copies the hook pack into
  text

  Copy

  ~/.openclaw/hooks/<id>
• Enables the installed hooks in
  text

  Copy

  hooks.internal.entries.*
• Records the install under
  text

  Copy

  hooks.internal.installs

Options:

• text

  Copy

  -l, --link
  : Link a local directory instead of copying (adds it to
  text

  Copy

  hooks.internal.load.extraDirs
  )
• text

  Copy

  --pin
  : Record npm installs as exact resolved
  text

  Copy

  name@version
  in
  text

  Copy

  hooks.internal.installs

Supported archives:

, , ,

Examples:

bash
Copy
# Local directory
openclaw plugins install ./my-hook-pack

# Local archive
openclaw plugins install ./my-hook-pack.zip

# NPM package
openclaw plugins install @openclaw/my-hook-pack

# Link a local directory without copying
openclaw plugins install -l ./my-hook-pack

Linked hook packs are treated as managed hooks from an operator-configured directory, not as workspace hooks.

Update hook packs

bash
Copy
openclaw plugins update <id>
openclaw plugins update --all

Update tracked npm-based hook packs through the unified plugins updater.

still works as a compatibility alias, but it prints a deprecation warning and forwards to .

Options:

• text

  Copy

  --all
  : Update all tracked hook packs
• text

  Copy

  --dry-run
  : Show what would change without writing

When a stored integrity hash exists and the fetched artifact hash changes, OpenClaw prints a warning and asks for confirmation before proceeding. Use global

to bypass prompts in CI/non-interactive runs.

Bundled hooks

session-memory

Saves session context to memory when you issue

or .

Enable:

bash
Copy
openclaw hooks enable session-memory

Output:

See: session-memory documentation

bootstrap-extra-files

Injects additional bootstrap files (for example monorepo-local

/ ) during .

Enable:

bash
Copy
openclaw hooks enable bootstrap-extra-files

See: bootstrap-extra-files documentation

command-logger

Logs all command events to a centralized audit file.

Enable:

bash
Copy
openclaw hooks enable command-logger

Output:

View logs:

bash
Copy
# Recent commands
tail -n 20 ~/.openclaw/logs/commands.log

# Pretty-print
cat ~/.openclaw/logs/commands.log | jq .

# Filter by action
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

See: command-logger documentation

boot-md

Runs

when the gateway starts (after channels start).

Events:

Enable:

bash
Copy
openclaw hooks enable boot-md

See: boot-md documentation

Related

• CLI reference
• Automation hooks