Hook Debugging & Management

Introduction

Hooks are powerful but can be difficult to troubleshoot when they misbehave. OpenClaw provides dedicated CLI commands for validating hook configurations, inspecting registered hooks, and diagnosing issues. This lesson covers the debugging tools, the distinction between legacy and new configuration formats, and common troubleshooting techniques.

Key Concepts

• openclaw hooks check: Validates all hook configurations and reports errors before runtime failures
• openclaw hooks info: Displays detailed information about all registered hooks, their event bindings, and source
• Legacy Config Format: The older hook configuration style using flat key-value pairs
• New Config Format: The current format using nested objects with handler, env, and array support
• Hook Validation: Checking that hook scripts exist, are executable, and match expected signatures

Real World Context

After updating an OpenClaw deployment, a team's message logging hook stops working. The engineer runs openclaw hooks check which reports that the hook script path changed due to a directory restructuring. They update the path and run the check again to confirm the fix. The debugging session takes two minutes instead of an hour of log diving.

Deep Dive

Validating Hooks

The hooks check command validates your entire hook configuration:

bash
openclaw hooks check

This command verifies that all referenced hook scripts exist on disk, are executable, export expected function signatures, and have valid configuration. It reports errors and warnings clearly.

Inspecting Hook Registration

The hooks info command shows all registered hooks:

bash
openclaw hooks info

This displays a table of every hook, which event it is bound to, whether it comes from local configuration or an npm hook pack, and its current status.

Legacy vs New Config Format

The legacy format used flat strings:

json
{
  "hooks": {
    "onMessageReceived": "./hooks/log.js",
    "onAgentBootstrap": "./hooks/init.js"
  }
}

The new format uses nested objects with explicit event types:

json
{
  "hooks": {
    "message": {
      "received": "./hooks/log.js"
    },
    "agent": {
      "bootstrap": "./hooks/init.js"
    }
  }
}

The new format supports hook chaining and per-hook configuration. OpenClaw still supports legacy format but emits deprecation warnings.

Troubleshooting Sequence

When hooks are not firing as expected:

bash
# Step 1: Validate configuration
openclaw hooks check

# Step 2: List all registered hooks
openclaw hooks info

# Step 3: Check Gateway logs for hook errors
openclaw logs --filter hooks

The first command catches configuration errors. The second confirms hooks are registered to correct events. The third filters log output to show only hook-related entries.

Common Pitfalls

• Not running hooks check after configuration changes: A typo in a hook path silently fails at runtime. Always validate after changes.
• Mixing legacy and new config formats: Using both in the same configuration leads to unpredictable behavior.
• Ignoring deprecation warnings: Legacy format support will eventually be removed.

Best Practices

• Run openclaw hooks check in your CI pipeline to catch errors before deployment.
• Migrate from legacy to new format proactively.
• Use openclaw hooks info after deployments to verify all hooks are registered and active.

Summary

• openclaw hooks check validates hook configurations and reports errors before runtime
• openclaw hooks info displays all registered hooks with their event bindings
• The legacy config uses flat key-value pairs; the new format uses nested objects with chaining
• Follow a three-step diagnostic sequence: check config, inspect registration, filter logs
• Always validate hooks after configuration changes and run checks in CI