Hooks¶

Hooks bieden een uitbreidbaar gebeurtenisgestuurd systeem voor het automatiseren van acties als reactie op agentopdrachten en gebeurtenissen. Hooks worden automatisch ontdekt vanuit mappen en kunnen via CLI-opdrachten worden beheerd, vergelijkbaar met hoe Skills werken in OpenClaw.

Gearchiveerd krijgen¶

Hooks zijn kleine scripts die worden uitgevoerd wanneer er iets gebeurt. Er zijn twee soorten:

Hooks (deze pagina): draaien binnen de Gateway wanneer agentgebeurtenissen plaatsvinden, zoals /new, /reset, /stop of levenscyclusgebeurtenissen.
Webhooks: externe HTTP-webhooks waarmee andere systemen werk kunnen triggeren in OpenClaw. Zie Webhook Hooks of gebruik openclaw webhooks voor Gmail-helperopdrachten.

Hooks kunnen ook worden gebundeld in plugins; zie Plugins.

Veelvoorkomende toepassingen:

Een geheugensnapshot opslaan wanneer je een sessie reset
Een audittrail van opdrachten bijhouden voor probleemoplossing of compliance
Vervolgautomatisering triggeren wanneer een sessie start of eindigt
Bestanden schrijven in de agent-werkruimte of externe API’s aanroepen wanneer gebeurtenissen plaatsvinden

Als je een kleine TypeScript-functie kunt schrijven, kun je een hook schrijven. Hooks worden automatisch ontdekt en je schakelt ze in of uit via de CLI.

Overzicht¶

Het hooks-systeem stelt je in staat om:

Sessiecontext op te slaan in het geheugen wanneer /new wordt uitgegeven
Alle opdrachten te loggen voor auditing
Aangepaste automatiseringen te triggeren bij levenscyclusgebeurtenissen van agents
Het gedrag van OpenClaw uit te breiden zonder de kerncode te wijzigen

Aan de slag¶

Gebundelde hooks¶

OpenClaw wordt geleverd met vier gebundelde hooks die automatisch worden ontdekt:

💾 session-memory: Slaat sessiecontext op in je agent-werkruimte (standaard ~/.openclaw/workspace/memory/) wanneer je /new uitvoert
📝 command-logger: Logt alle opdrachtevents naar ~/.openclaw/logs/commands.log
🚀 boot-md: Voert BOOT.md uit wanneer de gateway start (vereist interne hooks ingeschakeld)
😈 soul-evil: Verwisselt geïnjecteerde SOUL.md-inhoud met SOUL_EVIL.md tijdens een purge-venster of met willekeurige kans

Beschikbare hooks weergeven:

openclaw hooks list

Een hook inschakelen:

openclaw hooks enable session-memory

Hookstatus controleren:

openclaw hooks check

Gedetailleerde informatie ophalen:

openclaw hooks info session-memory

Aan de slag¶

Tijdens onboarding (openclaw onboard) word je gevraagd aanbevolen hooks in te schakelen. De wizard ontdekt automatisch in aanmerking komende hooks en presenteert ze ter selectie.

Hook-detectie¶

Hooks worden automatisch ontdekt vanuit drie mappen (in volgorde van prioriteit):

Werkruimte-hooks: <workspace>/hooks/ (per agent, hoogste prioriteit)
Beheerde hooks: ~/.openclaw/hooks/ (door de gebruiker geïnstalleerd, gedeeld over werkruimtes)
Gebundelde hooks: <openclaw>/dist/hooks/bundled/ (meegeleverd met OpenClaw)

Beheerde hookmappen kunnen óf een enkele hook zijn óf een hook pack (pakketmap).

Elke hook is een map die het volgende bevat:

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

Hook Packs (npm/archieven)¶

Hook packs zijn standaard npm-pakketten die één of meer hooks exporteren via openclaw.hooks in package.json. Installeer ze met:

openclaw hooks install <path-or-spec>

Voorbeeld package.json:

{
  "name": "@acme/my-hooks",
  "version": "0.1.0",
  "openclaw": {
    "hooks": ["./hooks/my-hook", "./hooks/other-hook"]
  }
}

Elke entry verwijst naar een hookmap met HOOK.md en handler.ts (of index.ts). Hook packs kunnen afhankelijkheden meeleveren; deze worden geïnstalleerd onder ~/.openclaw/hooks/<id>.

Hookstructuur¶

HOOK.md-indeling¶

Het bestand HOOK.md bevat metadata in YAML-frontmatter plus Markdown-documentatie:

---
name: my-hook
description: "Short description of what this hook does"
homepage: https://docs.openclaw.ai/hooks#my-hook
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

Detailed documentation goes here...

## What It Does

- Listens for `/new` commands
- Performs some action
- Logs the result

## Requirements

- Node.js must be installed

## Configuration

No configuration needed.

Metadatavelden¶

Het object metadata.openclaw ondersteunt:

emoji: Weergave-emoji voor de CLI (bijv. "💾")
events: Array van gebeurtenissen om naar te luisteren (bijv. ["command:new", "command:reset"])
export: Benoemde export om te gebruiken (standaard "default")
homepage: Documentatie-URL
requires: Optionele vereisten
bins: Vereiste binaries op PATH (bijv. ["git", "node"])
anyBins: Ten minste één van deze binaries moet aanwezig zijn
env: Vereiste omgevingsvariabelen
config: Vereiste configpaden (bijv. ["workspace.dir"])
os: Vereiste platforms (bijv. ["darwin", "linux"])
always: Geschiktheidscontroles omzeilen (boolean)
install: Installatiemethoden (voor gebundelde hooks: [{"id":"bundled","kind":"bundled"}])

Handler-implementatie¶

Het bestand handler.ts exporteert een functie HookHandler:

import type { HookHandler } from "../../src/hooks/hooks.js";

const myHandler: HookHandler = async (event) => {
  // Only trigger on 'new' command
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log(`[my-hook] New command triggered`);
  console.log(`  Session: ${event.sessionKey}`);
  console.log(`  Timestamp: ${event.timestamp.toISOString()}`);

  // Your custom logic here

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

export default myHandler;

Gebeurteniscontext¶

Elke gebeurtenis bevat:

{
  type: 'command' | 'session' | 'agent' | 'gateway',
  action: string,              // e.g., 'new', 'reset', 'stop'
  sessionKey: string,          // Session identifier
  timestamp: Date,             // When the event occurred
  messages: string[],          // Push messages here to send to user
  context: {
    sessionEntry?: SessionEntry,
    sessionId?: string,
    sessionFile?: string,
    commandSource?: string,    // e.g., 'whatsapp', 'telegram'
    senderId?: string,
    workspaceDir?: string,
    bootstrapFiles?: WorkspaceBootstrapFile[],
    cfg?: OpenClawConfig
  }
}

Gebeurtenistypen¶

Opdrachtevents¶

Getriggerd wanneer agentopdrachten worden uitgevoerd:

command: Alle opdrachtevents (algemene listener)
command:new: Wanneer de opdracht /new wordt uitgevoerd
command:reset: Wanneer de opdracht /reset wordt uitgevoerd
command:stop: Wanneer de opdracht /stop wordt uitgevoerd

Agentgebeurtenissen¶

agent:bootstrap: Vóórdat bootstrapbestanden in de werkruimte worden geïnjecteerd (hooks kunnen context.bootstrapFiles muteren)

Gateway-gebeurtenissen¶

Getriggerd wanneer de gateway start:

gateway:startup: Nadat kanalen zijn gestart en hooks zijn geladen

Toolresultaat-hooks (Plugin-API)¶

Deze hooks zijn geen event-streamlisteners; ze stellen plugins in staat toolresultaten synchroon aan te passen voordat OpenClaw ze opslaat.

tool_result_persist: Transformeert toolresultaten voordat ze naar het sessietranscript worden geschreven. Moet synchroon zijn; retourneer de bijgewerkte toolresultaat-payload of undefined om deze ongewijzigd te laten. Zie Agent Loop.

Toekomstige gebeurtenissen¶

Geplande gebeurtenistypen:

session:start: Wanneer een nieuwe sessie begint
session:end: Wanneer een sessie eindigt
agent:error: Wanneer een agent een fout tegenkomt
message:sent: Wanneer een bericht wordt verzonden
message:received: Wanneer een bericht wordt ontvangen

Aangepaste hooks maken¶

1. Locatie kiezen¶

Werkruimte-hooks (<workspace>/hooks/): Per agent, hoogste prioriteit
Beheerde hooks (~/.openclaw/hooks/): Gedeeld over werkruimtes

2. Mapstructuur maken¶

mkdir -p ~/.openclaw/hooks/my-hook
cd ~/.openclaw/hooks/my-hook

3. HOOK.md maken¶

---
name: my-hook
description: "Does something useful"
metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
---

# My Custom Hook

This hook does something useful when you issue `/new`.

4. handler.ts maken¶

import type { HookHandler } from "../../src/hooks/hooks.js";

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

  console.log("[my-hook] Running!");
  // Your logic here
};

export default handler;

5. Inschakelen en testen¶

# Verify hook is discovered
openclaw hooks list

# Enable it
openclaw hooks enable my-hook

# Restart your gateway process (menu bar app restart on macOS, or restart your dev process)

# Trigger the event
# Send /new via your messaging channel

Configuratie¶

Nieuw configformaat (aanbevolen)¶

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

Per-hookconfiguratie¶

Hooks kunnen een aangepaste configuratie hebben:

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

Extra mappen¶

Laad hooks uit aanvullende mappen:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "load": {
        "extraDirs": ["/path/to/more/hooks"]
      }
    }
  }
}

Verouderd configformaat (nog ondersteund)¶

Het oude configformaat werkt nog steeds voor achterwaartse compatibiliteit:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "handlers": [
        {
          "event": "command:new",
          "module": "./hooks/handlers/my-handler.ts",
          "export": "default"
        }
      ]
    }
  }
}

Migratie: Gebruik het nieuwe op detectie gebaseerde systeem voor nieuwe hooks. Verouderde handlers worden geladen na mapgebaseerde hooks.

CLI-opdrachten¶

Hooks weergeven¶

# List all hooks
openclaw hooks list

# Show only eligible hooks
openclaw hooks list --eligible

# Verbose output (show missing requirements)
openclaw hooks list --verbose

# JSON output
openclaw hooks list --json

Hookinformatie¶

# Show detailed info about a hook
openclaw hooks info session-memory

# JSON output
openclaw hooks info session-memory --json

Geschiktheid controleren¶

# Show eligibility summary
openclaw hooks check

# JSON output
openclaw hooks check --json

In-/uitschakelen¶

# Enable a hook
openclaw hooks enable session-memory

# Disable a hook
openclaw hooks disable command-logger

Referentie voor gebundelde hooks¶

session-memory¶

Slaat sessiecontext op in het geheugen wanneer je /new uitvoert.

Gebeurtenissen: command:new

Vereisten: workspace.dir moet zijn geconfigureerd

Uitvoer: <workspace>/memory/YYYY-MM-DD-slug.md (standaard ~/.openclaw/workspace)

Wat het doet:

Gebruikt de pre-reset sessie-entry om het juiste transcript te vinden
Extraheert de laatste 15 regels van het gesprek
Gebruikt een LLM om een beschrijvende bestandsnaam-slug te genereren
Slaat sessiemetadata op in een gedateerd geheugenbestand

Voorbeelduitvoer:

# Session: 2026-01-16 14:30:00 UTC

- **Session Key**: agent:main:main
- **Session ID**: abc123def456
- **Source**: telegram

Voorbeelden van bestandsnamen:

2026-01-16-vendor-pitch.md
2026-01-16-api-design.md
2026-01-16-1430.md (fallback-tijdstempel als slug-generatie mislukt)

Inschakelen:

openclaw hooks enable session-memory

command-logger¶

Logt alle opdrachtevents naar een gecentraliseerd auditbestand.

Gebeurtenissen: command

Vereisten: Geen

Uitvoer: ~/.openclaw/logs/commands.log

Wat het doet:

Legt gebeurtenisdetails vast (opdrachtactie, tijdstempel, sessiesleutel, afzender-ID, bron)
Voegt toe aan het logbestand in JSONL-formaat
Draait stil op de achtergrond

Voorbeeldlogregels:

{"timestamp":"2026-01-16T14:30:00.000Z","action":"new","sessionKey":"agent:main:main","senderId":"+1234567890","source":"telegram"}
{"timestamp":"2026-01-16T15:45:22.000Z","action":"stop","sessionKey":"agent:main:main","senderId":"user@example.com","source":"whatsapp"}

Logs bekijken:

# View recent commands
tail -n 20 ~/.openclaw/logs/commands.log

# Pretty-print with jq
cat ~/.openclaw/logs/commands.log | jq .

# Filter by action
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

Inschakelen:

openclaw hooks enable command-logger

soul-evil¶

Verwisselt geïnjecteerde SOUL.md-inhoud met SOUL_EVIL.md tijdens een purge-venster of met willekeurige kans.

Gebeurtenissen: agent:bootstrap

Documentatie: SOUL Evil Hook

Uitvoer: Er worden geen bestanden geschreven; verwisselingen gebeuren alleen in het geheugen.

Inschakelen:

openclaw hooks enable soul-evil

Config:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "soul-evil": {
          "enabled": true,
          "file": "SOUL_EVIL.md",
          "chance": 0.1,
          "purge": { "at": "21:00", "duration": "15m" }
        }
      }
    }
  }
}

boot-md¶

Voert BOOT.md uit wanneer de gateway start (nadat kanalen zijn gestart). Interne hooks moeten zijn ingeschakeld om dit te laten werken.

Gebeurtenissen: gateway:startup

Vereisten: workspace.dir moet zijn geconfigureerd

Wat het doet:

Leest BOOT.md uit je werkruimte
Voert de instructies uit via de agent-runner
Verstuurt eventuele gevraagde uitgaande berichten via de message-tool

Inschakelen:

openclaw hooks enable boot-md

Best practices¶

Houd handlers snel¶

Hooks draaien tijdens de verwerking van opdrachten. Houd ze lichtgewicht:

// ✓ Good - async work, returns immediately
const handler: HookHandler = async (event) => {
  void processInBackground(event); // Fire and forget
};

// ✗ Bad - blocks command processing
const handler: HookHandler = async (event) => {
  await slowDatabaseQuery(event);
  await evenSlowerAPICall(event);
};

Ga netjes om met fouten¶

Omwikkel risicovolle bewerkingen altijd:

const handler: HookHandler = async (event) => {
  try {
    await riskyOperation(event);
  } catch (err) {
    console.error("[my-handler] Failed:", err instanceof Error ? err.message : String(err));
    // Don't throw - let other handlers run
  }
};

Filter gebeurtenissen vroegtijdig¶

Keer vroegtijdig terug als de gebeurtenis niet relevant is:

const handler: HookHandler = async (event) => {
  // Only handle 'new' commands
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  // Your logic here
};

Gebruik specifieke gebeurtenissleutels¶

Specificeer waar mogelijk exacte gebeurtenissen in de metadata:

metadata: { "openclaw": { "events": ["command:new"] } } # Specific

In plaats van:

metadata: { "openclaw": { "events": ["command"] } } # General - more overhead

Debuggen¶

Hook-logging inschakelen¶

De gateway logt het laden van hooks bij het opstarten:

Registered hook: session-memory -> command:new
Registered hook: command-logger -> command
Registered hook: boot-md -> gateway:startup

Detectie controleren¶

Alle ontdekte hooks weergeven:

openclaw hooks list --verbose

Registratie controleren¶

const handler: HookHandler = async (event) => {
  console.log("[my-handler] Triggered:", event.type, event.action);
  // Your logic
};

Geschiktheid verifiëren¶

Controleer waarom een hook niet geschikt is:

openclaw hooks info my-hook

Zoek in de uitvoer naar ontbrekende vereisten.

Testen¶

Gateway-logs¶

Monitor gateway-logs om de uitvoering van hooks te zien:

# macOS
./scripts/clawlog.sh -f

# Other platforms
tail -f ~/.openclaw/gateway.log

Hooks direct testen¶

Test je handlers geïsoleerd:

import { test } from "vitest";
import { createHookEvent } from "./src/hooks/hooks.js";
import myHandler from "./hooks/my-hook/handler.js";

test("my handler works", async () => {
  const event = createHookEvent("command", "new", "test-session", {
    foo: "bar",
  });

  await myHandler(event);

  // Assert side effects
});

Architectuur¶

Kerncomponenten¶

src/hooks/types.ts: Typedefinities
src/hooks/workspace.ts: Mappen scannen en laden
src/hooks/frontmatter.ts: Parsing van HOOK.md-metadata
src/hooks/config.ts: Geschiktheidscontrole
src/hooks/hooks-status.ts: Statusrapportage
src/hooks/loader.ts: Dynamische moduleloader
src/cli/hooks-cli.ts: CLI-opdrachten
src/gateway/server-startup.ts: Laadt hooks bij het starten van de gateway
src/auto-reply/reply/commands-core.ts: Triggert opdrachtevents

Ontdekking Flow¶

Gateway startup
    ↓
Scan directories (workspace → managed → bundled)
    ↓
Parse HOOK.md files
    ↓
Check eligibility (bins, env, config, os)
    ↓
Load handlers from eligible hooks
    ↓
Register handlers for events

Gebeurtenis flow¶

User sends /new
    ↓
Command validation
    ↓
Create hook event
    ↓
Trigger hook (all registered handlers)
    ↓
Command processing continues
    ↓
Session reset

Problemen oplossen¶

Hook niet ontdekt¶

Controleer de mapstructuur:

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

Verifieer het HOOK.md-formaat:

bash cat ~/.openclaw/hooks/my-hook/HOOK.md # Should have YAML frontmatter with name and metadata

Toon alle ontdekte hooks:

bash openclaw hooks list

Hook niet geschikt¶

Controleer vereisten:

openclaw hooks info my-hook

Zoek naar ontbrekende:

Binaries (controleer PATH)
Omgevingsvariabelen
Configwaarden
OS-compatibiliteit

Hook wordt niet uitgevoerd¶

Verifieer dat de hook is ingeschakeld:

bash openclaw hooks list # Should show ✓ next to enabled hooks

Start je gatewayproces opnieuw zodat hooks opnieuw worden geladen.
Controleer gateway-logs op fouten:

bash ./scripts/clawlog.sh | grep hook

Handlerfouten¶

Controleer op TypeScript-/importfouten:

# Test import directly
node -e "import('./path/to/handler.ts').then(console.log)"

Migratiegids¶

Van verouderde config naar detectie¶

Voor:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "handlers": [
        {
          "event": "command:new",
          "module": "./hooks/handlers/my-handler.ts"
        }
      ]
    }
  }
}

Na:

Maak een hookmap:

bash mkdir -p ~/.openclaw/hooks/my-hook mv ./hooks/handlers/my-handler.ts ~/.openclaw/hooks/my-hook/handler.ts

Maak HOOK.md:

```markdown

name: my-hook description: "My custom hook" metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }

# My Hook

Does something useful. ```

Config bijwerken:

json { "hooks": { "internal": { "enabled": true, "entries": { "my-hook": { "enabled": true } } } } }

Verifieer en start je gatewayproces opnieuw:

bash openclaw hooks list # Should show: 🎯 my-hook ✓

Voordelen van migratie:

Automatische detectie
CLI-beheer
Geschiktheidscontrole
Betere documentatie
Consistente structuur

Overview

Built-in tools

Browser

Agent coordination

Skills

Extensions

Automation

Media and devices

Hooks¶

Gearchiveerd krijgen¶

Overzicht¶

Aan de slag¶

Gebundelde hooks¶

Aan de slag¶

Hook-detectie¶

Hook Packs (npm/archieven)¶

Hookstructuur¶

HOOK.md-indeling¶

Metadatavelden¶

Handler-implementatie¶

Gebeurteniscontext¶

Gebeurtenistypen¶

Opdrachtevents¶

Agentgebeurtenissen¶

Gateway-gebeurtenissen¶

Toolresultaat-hooks (Plugin-API)¶

Toekomstige gebeurtenissen¶

Aangepaste hooks maken¶

1. Locatie kiezen¶

2. Mapstructuur maken¶

3. HOOK.md maken¶

4. handler.ts maken¶

5. Inschakelen en testen¶

Configuratie¶

Nieuw configformaat (aanbevolen)¶

Per-hookconfiguratie¶

Extra mappen¶

Verouderd configformaat (nog ondersteund)¶

CLI-opdrachten¶

Hooks weergeven¶

Hookinformatie¶

Geschiktheid controleren¶

In-/uitschakelen¶

Referentie voor gebundelde hooks¶

session-memory¶

command-logger¶

soul-evil¶

boot-md¶

Best practices¶

Houd handlers snel¶

Ga netjes om met fouten¶

Filter gebeurtenissen vroegtijdig¶

Gebruik specifieke gebeurtenissleutels¶

Debuggen¶

Hook-logging inschakelen¶

Detectie controleren¶

Registratie controleren¶

Geschiktheid verifiëren¶

Testen¶

Gateway-logs¶

Hooks direct testen¶

Architectuur¶

Kerncomponenten¶

Ontdekking Flow¶

Gebeurtenis flow¶

Problemen oplossen¶

Hook niet ontdekt¶

Hook niet geschikt¶

Hook wordt niet uitgevoerd¶

Handlerfouten¶

Migratiegids¶

Van verouderde config naar detectie¶

Zie ook¶