Hooks

Hooks are small scripts that run when something happens inside the Gateway. They can be discovered from directories and inspected with

There are two kinds of hooks in OpenClaw:

• Internal hooks (this page): run inside the Gateway when agent events fire, like
  text

  Copy

  /new
  ,
  text

  Copy

  /reset
  ,
  text

  Copy

  /stop
  , or lifecycle events.
• Webhooks: external HTTP endpoints that let other systems trigger work in OpenClaw. See Webhooks.

Hooks can also be bundled inside plugins.

Quick start

bash
Copy
# List available hooks
openclaw hooks list

# Enable a hook
openclaw hooks enable session-memory

# Check hook status
openclaw hooks check

# Get detailed information
openclaw hooks info session-memory

Event types

Writing hooks

Hook structure

Each hook is a directory containing two files:

text
Copy
my-hook/
├── HOOK.md          # Metadata + documentation
└── handler.ts       # Handler implementation

HOOK.md format

markdown
Copy
---
name: my-hook
description: "Short description of what this hook does"
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

Detailed documentation goes here.

Metadata fields (

Handler implementation

typescript
Copy
const handler = async (event) => {
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log(`[my-hook] New command triggered`);
  // Your logic here

  // Optionally send message to user
  event.messages.push("Hook executed!");
};

export default handler;

Each event includes:

Event context highlights

Command events (

Message events (

Message events (

Message events (

Message events (

Bootstrap events (

Session patch events (

Compaction events:

Gateway lifecycle events:

Hook discovery

Hooks are discovered from these directories, in order of increasing override precedence:

1. Bundled hooks: shipped with OpenClaw
2. Plugin hooks: hooks bundled inside installed plugins
3. Managed hooks:
   text

   Copy

   ~/.openclaw/hooks/
   (user-installed, shared across workspaces). Extra directories from
   text

   Copy

   hooks.internal.load.extraDirs
   share this precedence.
4. Workspace hooks:
   text

   Copy

   <workspace>/hooks/
   (per-agent, disabled by default until explicitly enabled)

Workspace hooks can add new hook names but cannot override bundled, managed, or plugin-provided hooks with the same name.

The Gateway skips internal hook discovery on startup until internal hooks are configured. Enable a bundled or managed hook with

Hook packs

Hook packs are npm packages that export hooks via

bash
Copy
openclaw plugins install <path-or-spec>

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

Bundled hooks

Enable any bundled hook:

bash
Copy
openclaw hooks enable <hook-name>

json
Copy
{
  "hooks": {
    "internal": {
      "entries": {
        "bootstrap-extra-files": {
          "enabled": true,
          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
        }
      }
    }
  }
}

For the complete plugin hook reference, see Plugin hooks.

Configuration

json
Copy
{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "session-memory": { "enabled": true },
        "command-logger": { "enabled": false }
      }
    }
  }
}

Per-hook environment variables:

json
Copy
{
  "hooks": {
    "internal": {
      "entries": {
        "my-hook": {
          "enabled": true,
          "env": { "MY_CUSTOM_VAR": "value" }
        }
      }
    }
  }
}

Extra hook directories:

json
Copy
{
  "hooks": {
    "internal": {
      "load": {
        "extraDirs": ["/path/to/more/hooks"]
      }
    }
  }
}

CLI reference

bash
Copy
# List all hooks (add --eligible, --verbose, or --json)
openclaw hooks list

# Show detailed info about a hook
openclaw hooks info <hook-name>

# Show eligibility summary
openclaw hooks check

# Enable/disable
openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>

Best practices

• Keep handlers fast. Hooks run during command processing. Fire-and-forget heavy work with
  text

  Copy

  void processInBackground(event)
  .
• Handle errors gracefully. Wrap risky operations in try/catch; do not throw so other handlers can run.
• Filter events early. Return immediately if the event type/action is not relevant.
• Use specific event keys. Prefer
  text

  Copy

  "events": ["command:new"]
  over
  text

  Copy

  "events": ["command"]
  to reduce overhead.

Troubleshooting

Hook not discovered

bash
Copy
# Verify directory structure
ls -la ~/.openclaw/hooks/my-hook/
# Should show: HOOK.md, handler.ts

# List all discovered hooks
openclaw hooks list

Hook not eligible

bash
Copy
openclaw hooks info my-hook

Check for missing binaries (PATH), environment variables, config values, or OS compatibility.

Hook not executing

1. Verify the hook is enabled:
   text

   Copy

   openclaw hooks list
2. Restart your gateway process so hooks reload.
3. Check gateway logs:
   text

   Copy

   ./scripts/clawlog.sh | grep hook

Related

• CLI Reference: hooks
• Webhooks
• Plugin hooks — in-process plugin lifecycle hooks
• Configuration