OpenClaw Hooks: The Complete Developer Guide (2026)

How OpenClaw Hook Discovery Works

The Gateway uses automatic directory scanning to discover hooks. On startup, it scans configured hook directories and loads any valid hook packages it finds.

Two important prerequisites before hooks activate:

1. Hooks must be explicitly enabled — a hook directory alone is not enough
2. At least one hook entry must be configured in your Gateway settings

Each hook package requires exactly two files:

• HOOK.md — metadata file declaring the hook's name, version, description, lifecycle event subscriptions, and any required permissions
• handler.ts (or handler.js) — the implementation file containing the actual logic that runs when the event fires

The Four Lifecycle Events Every Developer Should Know

PreToolUse is the most powerful — it's the only event that can abort a tool call before it executes. If your hook returns a rejection signal during PreToolUse, the agent never calls the tool.

PostToolUse is the workhorse for automation. File written? Run your linter. Test modified? Execute the suite. Code committed? Trigger a build.

Step-by-Step: Writing Your First Custom Hook from Scratch

Most documentation shows you commands. This shows you the full path from nothing to a working hook.

Step 1 — Create the hook directory

mkdir -p .openclaw/hooks/auto-lint

Step 2 — Write the HOOK.md metadata

# auto-lint

**Version:** 1.0.0
**Event:** PostToolUse
**Description:** Runs ESLint on any file written by the agent
**Tools:** write_file, edit_file

The Tools field scopes your hook to specific tool calls. Without it, the hook fires on every PostToolUse event — usually not what you want.

Step 3 — Implement handler.ts

import { PostToolUseEvent } from "@openclaw/sdk";
import { execSync } from "child_process";

export default function handler(event: PostToolUseEvent) {
  const filePath = event.toolResult?.path;
  if (!filePath) return;

  try {
    execSync(`npx eslint --fix "${filePath}"`, { stdio: "inherit" });
  } catch (err) {
    console.error(`[auto-lint] ESLint failed on ${filePath}`);
  }
}

Step 4 — Enable via CLI

openclaw hooks enable auto-lint

Step 5 — Verify it loaded

openclaw hooks list

You should see auto-lint with status enabled. Start a session, write a file, and watch the linter fire.

JavaScript vs. TypeScript for Hook Handlers — What to Choose in 2026

The SDK ships with full TypeScript typings, and as of the 2026 SDK releases, TypeScript is the recommended default for new hooks.

If you're writing a hook you'll commit to version control or share with a team, use TypeScript. For a throwaway local guardrail, plain JavaScript is fine — just name it handler.js and skip the compile step.

OpenClaw Hooks CLI Reference

Managing Hook Packs — Install, Update, and the --dry-run Workflow

Hook packs bundle multiple related hooks as a single installable unit. The install workflow verifies an integrity hash before writing anything to disk.

# Preview what would be installed without committing
openclaw hooks install productivity-pack --dry-run

# Install non-interactively (for CI environments)
openclaw hooks install productivity-pack --yes

# Update all installed packs
openclaw hooks update --all

Bundled Hooks Reference: What Ships with OpenClaw

Run openclaw hooks inspect session-memory to see its full configuration options. Most bundled hooks ship with sensible defaults but expose config fields for customization.

Real-World Hook Use Cases (With Working Examples)

1. File Protection Guardrail (PreToolUse)

Prevent the agent from ever touching your .env file:

import { PreToolUseEvent } from "@openclaw/sdk";

export default function handler(event: PreToolUseEvent) {
  const target = event.toolInput?.path ?? "";
  if (target.includes(".env")) {
    return { abort: true, reason: "Modification of .env files is blocked by policy." };
  }
}

Drop this in .openclaw/hooks/protect-env/ with the matching HOOK.md subscribing to PreToolUse scoped to write_file and edit_file. The agent receives the rejection reason in its context and will not retry.

2. Slack Notification on Session Stop

import { StopEvent } from "@openclaw/sdk";

export default async function handler(event: StopEvent) {
  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `OpenClaw session ended. Files modified: ${event.session.filesModified ?? 0}`
    })
  });
}

Subscribe this hook to the Stop event. Every session end fires a Slack message with a summary. No external server needed — the Gateway process makes the outbound request directly.

3. Auto-Format + Test on PostToolUse

import { PostToolUseEvent } from "@openclaw/sdk";
import { execSync } from "child_process";

export default function handler(event: PostToolUseEvent) {
  const file = event.toolResult?.path;
  if (!file?.endsWith(".ts")) return;

  execSync(`prettier --write "${file}"`);
  execSync("npm test -- --passWithNoTests", { stdio: "inherit" });
}

This fires after every TypeScript file write, formats it, then runs your test suite. Slow on large projects — scope it tightly using the Tools field in HOOK.md.

Hooks for Teams — Enforcing Guardrails Across a Shared Project

Commit your .openclaw/hooks/ directory to version control. Every developer who clones the repo automatically has the same hook configuration.

• Lock critical hooks to enabled in project config — prevents teammates from accidentally disabling file guards
• Use HOOK.md descriptions to document intent — treat them like code comments, teammates will read them
• Scope hooks to tool-level granularity — broad hooks slow down all agent interactions, creating friction that causes teammates to disable them
• In monorepos, hooks in a parent directory apply to all nested projects unless overridden at the subdirectory level

CI/CD Integration — Running OpenClaw Hooks Non-Interactively

In GitHub Actions or any headless environment, the interactive confirmation prompt will hang your pipeline. Use --yes to skip it:

- name: Install hooks non-interactively
  run: openclaw hooks install qa-pack --yes

- name: Run OpenClaw session
  env:
    OPENCLAW_HOOKS_ENABLED: "true"
    SLACK_WEBHOOK_URL: secrets.SLACK_WEBHOOK_URL
  run: openclaw run --task "audit dependencies" --yes

Hook Security: What Runs, What It Can Access, and How to Stay Safe

This is the part most documentation skips entirely — and it's the most important section if you're installing community hook packs.

What hooks can access: Hook scripts inherit the full permissions of the Gateway process. If the Gateway runs as your user account, your hooks can read any file that account can read, make network requests, execute subprocesses, and access environment variables including secrets.

Hook Pack Audit Checklist

Run through this before installing any third-party pack:

The openclaw hooks inspect command shows you the full source path of an installed hook — use it to re-review handler code after updates.

Troubleshooting OpenClaw Hooks — When They Don't Fire

Frequently Asked Questions

Final Thoughts — Choosing the Right Hook Strategy for Your Workflow

Start with one hook that solves a real pain — a file guard or a post-write linter. Get it working end-to-end before layering more. The power of hooks compounds: a session with three well-scoped hooks running smoothly is significantly more reliable than one with ten poorly-scoped hooks you don't trust.