OpenClaw Hooks: Event-Driven Automation

What Are Hooks?

Hooks are shell commands that execute in response to OpenClaw events. They let you extend OpenClaw's behavior without modifying its code.

Hook Types

Message Hooks

Triggered when messages are sent or received:

• on_message_received — When a message arrives from any channel
• on_message_sent — When OpenClaw sends a response
• on_message_error — When message processing fails

Tool Hooks

Triggered around tool execution:

• before_tool — Before a tool runs (can block execution)
• after_tool — After a tool completes

Lifecycle Hooks

Triggered on gateway events:

• on_start — When OpenClaw starts
• on_stop — When OpenClaw shuts down
• on_channel_connect — When a channel connects
• on_channel_disconnect — When a channel drops

Configuring Hooks

In openclaw.json:

{
  "hooks": {
    "on_message_received": "echo 'Message received' >> ~/openclaw.log",
    "on_start": "notify-send 'OpenClaw is running'",
    "before_tool": {
      "command": "python3 ~/scripts/validate-tool.py",
      "blocking": true
    }
  }
}

Use Cases

Logging

{
  "hooks": {
    "on_message_received": "echo $(date) >> ~/openclaw-activity.log"
  }
}

Notifications

{
  "hooks": {
    "on_channel_disconnect": "osascript -e 'display notification "OpenClaw channel disconnected" with title "Alert"'"
  }
}

Security Validation

{
  "hooks": {
    "before_tool": {
      "command": "python3 ~/scripts/check-tool-safety.py",
      "blocking": true
    }
  }
}

A blocking hook that returns a non-zero exit code prevents the action from executing.

Integration

{
  "hooks": {
    "on_message_sent": "curl -X POST https://your-webhook.com/log -d '{"event": "message_sent"}'"
  }
}

Hook Environment

Hooks receive event data through environment variables:

• OPENCLAW_EVENT — The event type
• OPENCLAW_CHANNEL — The channel involved
• OPENCLAW_TOOL — The tool name (for tool hooks)

Tips

• Keep hooks lightweight — they run synchronously by default
• Use blocking: false for non-critical hooks
• Test hooks manually before adding to configuration
• Log hook output for debugging