Complete reference for openclaw hooks, discovering, enabling, installing, and managing hook packs, plus a reference for the four bundled hooks that ship with OpenClaw.
What are Hooks?
Hooks are event-driven extensions that run in response to Gateway activity, things like session starts, commands, or agent turns. They let you inject behavior without modifying the core Gateway: save context to memory files, log all commands to an audit trail, inject extra workspace files at agent boot, or run a custom script when the Gateway starts up.
Hooks are discovered from three sources: your workspace directory, managed directories, and the bundled hooks that ship with OpenClaw. All hooks are disabled by default, you must explicitly enable them.
Finding the Right Command
If you’re exploring what hooks are available, start with hooks list and hooks check. To turn a hook on or off, use hooks enable / hooks disable, but remember to restart the Gateway after every toggle. For installing external hook packs from npm or local directories, go to Install & Update. If you want something that works immediately without installing anything, the four Bundled Hooks are ready to enable right now.
Listing & Inspecting Hooks
Discover available hooks and check whether your system meets their requirements before trying to enable them.
| openclaw hooks list Lists all discovered hooks from your workspace, managed directories, and bundled hooks. By default shows all hooks regardless of eligibility. –eligible | –verbose | –json –eligible filters to only hooks whose requirements are met. –verbose includes detailed info on why ineligible hooks fail their requirements, useful before enabling a hook that keeps showing as not ready. |
| openclaw hooks info <name> Shows detailed information about a specific hook: its source, path, listened events, and any missing requirements. Use this when a hook appears in hooks list as ineligible and you want to understand exactly what it needs. |
| openclaw hooks check Displays a high-level summary of your hook eligibility status, how many hooks are “Ready” vs “Not ready”. A quick overview before running hooks list –verbose for details. |
inspection examples
# High-level summary openclaw hooks check # List all hooks openclaw hooks list # List only eligible hooks openclaw hooks list --eligible # Show why ineligible hooks fail requirements openclaw hooks list --verbose # Detailed info for a specific hook openclaw hooks info session-memory
Enabling & Disabling Hooks
Hooks are disabled by default. Toggle them by name. Always restart the Gateway after any toggle, hooks are loaded at startup.
Gateway restart required after every enable or disable. Hooks are loaded when the Gateway boots, toggling one without restarting has no effect until the next start. Run openclaw gateway restart after making changes.
| openclaw hooks enable <name> Enables a hook by updating your ~/openclaw/config.json. The hook will be active the next time the Gateway starts. |
| openclaw hooks disable <name> Disables the specified hook in your configuration. The hook remains installed but will not run after the next Gateway restart. If a hook is managed by a plugin (shown as plugin:<id> in the list), you cannot enable or disable it via hooks enable / hooks disable. You must enable or disable the parent plugin instead. |
enable → restart pattern
# Enable a bundled hook openclaw hooks enable session-memory # Restart Gateway to load the newly enabled hook openclaw gateway restart # Disable a hook and restart openclaw hooks disable command-logger openclaw gateway restart
Installing & Updating Hook Packs
Install external hooks (“hook packs”) from npm, local folders, or archives. Installed hooks are automatically enabled and recorded.
openclaw hooks install <path-or-spec>
Installs a hook pack. Copies the files to ~/openclaw/hooks/<id>, automatically enables the hooks, and records the install. Supports npm registries, local directories, and archive formats.
| npm npm registry / scoped packages | local dir local path (copied or linked) | archive .zip .tgz .tar.gz .tar |
-l / –link | –pin
–link symlinks a local directory instead of copying, useful for developing a hook locally without reinstalling on every change. –pin records the exact name@version for npm installs, locking the version for reproducible setups.
openclaw hooks update <id>
Updates your installed npm hook packs to their latest versions. Pass a specific <id> to update one pack, or use –all to update every installed npm hook pack at once.
–all
install & update examples
# Install from npm openclaw hooks install @myorg/openclaw-hook-pack # Install from local directory (copy) openclaw hooks install ./my-hook-pack # Link a local directory for development (no copy) openclaw hooks install ./my-hook-pack --link # Install from archive openclaw hooks install ./hook-pack.tgz # Update a specific pack openclaw hooks update my-hook-pack # Update all npm hook packs openclaw hooks update --all
Use –link + a local directory when actively developing a hook. Changes to the linked directory take effect on the next Gateway restart without reinstalling. Switch to a regular install (without –link) when you’re ready to publish.
Bundled Hooks
OpenClaw ships with four built-in hooks you can enable immediately, no install required. Run openclaw hooks enable <name> then openclaw gateway restart.
| session-memory Saves session context to a memory file automatically when you issue the /new command. This hook is a core component of the OpenClaw Memory and Skills System, as it prevents context loss across session resets and allows your agent to “remember” previous interactions without manual intervention. | command-logger Logs all command events to a centralized audit file at ~/openclaw/logs/commands.log. Useful for auditing agent activity or debugging unexpected command behavior. |
| bootstrap-extra-files Injects additional workspace bootstrap files, like monorepo AGENTS.md files, during agent startup. Lets you provide extra context to the agent without modifying the core workspace structure. | boot-md Automatically runs a BOOT.md file from your workspace when the Gateway starts up. Use it to execute initialization instructions or inject startup context before the first agent turn. |
enable all bundled hooks
openclaw hooks enable session-memory openclaw hooks enable command-logger openclaw hooks enable bootstrap-extra-files openclaw hooks enable boot-md openclaw gateway restart # required to load all newly enabled hooks
