​

Hooks

​

Getting Oriented

• Hooks (cette page) : s’exécutent à l’intérieur de la Gateway (passerelle) lorsque des événements d’agent se déclenchent, comme /new, /reset, /stop, ou des événements du cycle de vie.
• Webhooks : webhooks HTTP externes permettant à d’autres systèmes de déclencher du travail dans OpenClaw. Voir Webhook Hooks ou utiliser openclaw webhooks pour les commandes d’assistance Gmail.

• Enregistrer un instantané de mémoire lorsque vous réinitialisez une session
• Conserver une piste d’audit des commandes pour le dépannage ou la conformité
• Déclencher des automatisations de suivi lorsqu’une session démarre ou se termine
• Écrire des fichiers dans l’espace de travail de l’agent ou appeler des API externes lorsque des événements se produisent

​

Overview

• Enregistrer le contexte de session en mémoire lorsque /new est émis
• Journaliser toutes les commandes à des fins d’audit
• Déclencher des automatisations personnalisées lors des événements du cycle de vie de l’agent
• Étendre le comportement d’OpenClaw sans modifier le code cœur

​

Démarrage

​

Hooks inclus

• 💾 session-memory : enregistre le contexte de session dans l’espace de travail de votre agent (par défaut ~/.openclaw/workspace/memory/) lorsque vous émettez /new
• 😈 soul-evil : remplace le contenu injecté SOUL.md par SOUL_EVIL.md pendant une fenêtre de purge ou de manière aléatoire
• 📝 command-logger : journalise tous les événements de commande dans ~/.openclaw/logs/commands.log
• 🚀 boot-md : exécute BOOT.md lorsque la gateway (passerelle) démarre (nécessite l’activation des hooks internes)

openclaw hooks list

openclaw hooks enable session-memory

openclaw hooks check

openclaw hooks info session-memory

​

Onboarding

​

Découverte des hooks

1. Hooks d’espace de travail : <workspace>/hooks/ (par agent, priorité la plus élevée)
2. Hooks gérés : ~/.openclaw/hooks/ (installés par l’utilisateur, partagés entre les espaces de travail)
3. Hooks intégrés : <openclaw>/dist/hooks/bundled/ (fournis avec OpenClaw)

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

​

Packs de hooks (npm/archives)

openclaw hooks install <path-or-spec>

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

​

Hook Structure

​

HOOK.md Format

---
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.

​

Metadata Fields

• emoji : emoji d’affichage pour la CLI (par ex. "💾")
• Prise en main
• export : export nommé à utiliser (par défaut "default")
• homepage : URL de documentation
• requires : exigences optionnelles
  • bins : binaires requis sur le PATH (par ex. ["git", "node"])
  • anyBins : au moins un de ces binaires doit être présent
  • env : variables d’environnement requises
  • soul-evil
  • os : plateformes requises (par ex. ["darwin", "linux"])
• always : contourner les vérifications d’éligibilité (booléen)
• install : méthodes d’installation (pour les hooks intégrés : [{"id":"bundled","kind":"bundled"}])

​

Handler Implementation

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;

​

Event Context

{
  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
  }
}

​

Event Types

​

Command Events

• command : tous les événements de commande (écouteur général)
• command:new : lorsque la commande /new est émise
• command:reset : lorsque la commande /reset est émise
• command:stop : lorsque la commande /stop est émise

​

Agent Events

• agent:bootstrap : avant que les fichiers de bootstrap de l’espace de travail ne soient injectés (les hooks peuvent modifier context.bootstrapFiles)

​

Gateway Events

• gateway:startup : après le démarrage des canaux et le chargement des hooks

​

Tool Result Hooks (Plugin API)

• tool_result_persist : transformer les résultats des outils avant qu’ils ne soient écrits dans la transcription de session. Doit être synchrone ; retourner la charge utile du résultat d’outil mise à jour ou undefined pour la conserver telle quelle. Voir Agent Loop.

​

Future Events

• session:start : lorsqu’une nouvelle session commence
• session:end : lorsqu’une session se termine
• agent:error : lorsqu’un agent rencontre une erreur
• message:sent : lorsqu’un message est envoyé
• message:received : lorsqu’un message est reçu

​

Creating Custom Hooks

​

1. Choose Location

• Hooks d’espace de travail (<workspace>/hooks/) : par agent, priorité la plus élevée
• Hooks gérés (~/.openclaw/hooks/) : partagés entre les espaces de travail

​

2. Create Directory Structure

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

​

3. Create HOOK.md

---
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. Create handler.ts

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. Enable and Test

# 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

​

Configuration

​

New Config Format (Recommended)

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

​

Per-Hook Configuration

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

​

Extra Directories

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

​

Legacy Config Format (Still Supported)

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

​

CLI Commands

​

List Hooks

# 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

​

Hook Information

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

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

​

Check Eligibility

# Show eligibility summary
openclaw hooks check

# JSON output
openclaw hooks check --json

​

Enable/Disable

# Enable a hook
openclaw hooks enable session-memory

# Disable a hook
openclaw hooks disable command-logger

​

Bundled hook reference

​

session-memory

1. Utilise l’entrée de session pré-réinitialisation pour localiser la transcription correcte
2. Extrait les 15 dernières lignes de la conversation
3. Utilise un LLM pour générer un slug de nom de fichier descriptif
4. Enregistre les métadonnées de session dans un fichier de mémoire daté

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

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

• 2026-01-16-vendor-pitch.md
• 2026-01-16-api-design.md
• 2026-01-16-1430.md (horodatage de secours si la génération du slug échoue)

openclaw hooks enable session-memory

​

bootstrap-extra-files

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

• Les chemins sont résolus par rapport au workspace.
• Les fichiers doivent rester dans le workspace (vérifiés via realpath).
• Seuls les noms de base bootstrap reconnus sont chargés.
• La liste blanche des sous-agents est préservée (AGENTS.md et TOOLS.md uniquement).

openclaw hooks enable bootstrap-extra-files

​

command-logger

1. Capture les détails de l’événement (action de commande, horodatage, clé de session, ID de l’expéditeur, source)
2. Ajoute au fichier de log au format JSONL
3. S’exécute silencieusement en arrière-plan

{"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":"[email protected]","source":"whatsapp"}

# 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 .

openclaw hooks enable command-logger

​

boot-md

1. Lit BOOT.md depuis votre espace de travail
2. Exécute les instructions via l’agent runner
3. Envoie tout message sortant demandé via l’outil de messagerie

openclaw hooks enable boot-md

​

Best Practices

​

Keep Handlers Fast

// ✓ 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);
};

​

Handle Errors Gracefully

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 Events Early

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

  // Your logic here
};

​

Use Specific Event Keys

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

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

​

Debugging

​

Enable Hook Logging

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

​

Check Discovery

openclaw hooks list --verbose

​

Check Registration

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

​

Verify Eligibility

openclaw hooks info my-hook

​

Testing

​

Gateway Logs

# macOS
./scripts/clawlog.sh -f

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

​

Test Hooks Directly

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
});

​

Architecture

​

Core Components

• src/hooks/types.ts : définitions de types
• src/hooks/workspace.ts : analyse et chargement des répertoires
• src/hooks/frontmatter.ts : analyse des métadonnées HOOK.md
• src/hooks/config.ts : vérification de l’éligibilité
• src/hooks/hooks-status.ts : reporting de statut
• src/hooks/loader.ts : chargeur de modules dynamique
• src/cli/hooks-cli.ts : commandes CLI
• src/gateway/server-startup.ts : charge les hooks au démarrage de la gateway
• src/auto-reply/reply/commands-core.ts : déclenche les événements de commande

​

Discovery 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

​

Event Flow

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

​

Troubleshooting

​

Hook Not Discovered

1. Vérifiez la structure des répertoires :
   ls -la ~/.openclaw/hooks/my-hook/
   # Should show: HOOK.md, handler.ts
   
2. Vérifiez le format de HOOK.md :
   cat ~/.openclaw/hooks/my-hook/HOOK.md
   # Should have YAML frontmatter with name and metadata
   
3. Listez tous les hooks découverts :
   openclaw hooks list
   

​

Hook Not Eligible

openclaw hooks info my-hook

• Binaires (vérifiez le PATH)
• Variables d’environnement
• Valeurs de configuration
• Compatibilité du système d’exploitation

​

Hook Not Executing

1. Vérifiez que le hook est activé :
   openclaw hooks list
   # Should show ✓ next to enabled hooks
   
2. Redémarrez le processus de la gateway afin que les hooks soient rechargés.
3. Vérifiez les logs de la gateway pour des erreurs :
   ./scripts/clawlog.sh | grep hook
   

​

Handler Errors

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

​

Migration Guide

​

From Legacy Config to Discovery

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

1. Créez le répertoire du hook :
   mkdir -p ~/.openclaw/hooks/my-hook
   mv ./hooks/handlers/my-handler.ts ~/.openclaw/hooks/my-hook/handler.ts
   
2. Créez HOOK.md :
   ---
   name: my-hook
   description: "My custom hook"
   metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
   ---
   
   # My Hook
   
   Does something useful.
   
3. Mettez à jour la configuration :
   {
     "hooks": {
       "internal": {
         "enabled": true,
         "entries": {
           "my-hook": { "enabled": true }
         }
       }
     }
   }
   
4. Vérifiez et redémarrez le processus de la gateway :
   openclaw hooks list
   # Should show: 🎯 my-hook ✓
   

• Découverte automatique
• Gestion via la CLI
• Vérification de l’éligibilité
• Meilleure documentation
• Structure cohérente

​

See Also

• CLI Reference: hooks
• Bundled Hooks README
• Webhook Hooks
• Configuration