OpenClaw Hooks: la guida completa per gli sviluppatori (2026)

Come funziona la scoperta degli hook OpenClaw

Il Gateway utilizza scansione automatica delle directory per scoprire i ganci. All'avvio, esegue la scansione delle directory di hook configurate e carica tutti i pacchetti di hook validi che trova.

Due prerequisiti importanti prima dell'attivazione degli hook:

1. Hooks deve essere abilitato esplicitamente — una directory hook da sola non è sufficiente
2. Almeno è necessario configurare una voce hook nelle impostazioni del tuo Gateway

Ogni pacchetto hook richiede esattamente due file:

• HOOK.md — file di metadati che dichiara il nome dell'hook, la versione, la descrizione, le sottoscrizioni agli eventi del ciclo di vita e tutte le autorizzazioni richieste
• handler.ts (o handler.js) — il file di implementazione contenente la logica effettiva che viene eseguita quando si attiva l'evento

I quattro eventi del ciclo di vita che ogni sviluppatore dovrebbe conoscere

PreToolUse è il più potente: è l'unico evento che può farlo interrompere una chiamata allo strumento prima che venga eseguita. Se il tuo hook restituisce un segnale di rifiuto durante PreToolUse, l'agente non chiamerà mai lo strumento.

PostToolUse è il cavallo di battaglia per l'automazione. File scritto? Esegui il tuo linter. Prova modificata? Esegui la suite. Codice impegnato? Attiva una build.

Step-by-Step: scrivere il tuo primo hook personalizzato da zero

La maggior parte della documentazione mostra i comandi. Questo ti mostra il percorso completo dal nulla a un hook funzionante.

Step 1: crea la directory hook

mkdir -p .openclaw/hooks/auto-lint

Step 2: scrive i metadati HOOK.md

# auto-lint

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

Il campo Tools definisce l'ambito del tuo hook per chiamate di strumenti specifici. Senza di esso, il gancio si accende ogni Evento PostToolUse: di solito non è quello che desideri.

Step 3: implementazione 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: abilita tramite CLI

openclaw hooks enable auto-lint

Step 5: verifica che sia caricato

openclaw hooks list

Dovresti vedere auto-lint con lo stato enabled. Avvia una sessione, scrivi un file e osserva il fuoco del linter.

JavaScript vs. TypeScript per gestori di ganci: cosa scegliere nel 2026

L'SDK viene fornito con digitazioni TypeScript complete e, a partire dalle versioni dell'SDK del 2026, TypeScript è l'impostazione predefinita consigliata per nuovi ganci.

Se stai scrivendo un hook che ti impegnerai nel controllo della versione o che condividerai con un team, usa TypeScript. Per un guardrail locale usa e getta, il semplice JavaScript va bene: chiamalo semplicemente handler.js e salta il passaggio di compilazione.

OpenClaw Hooks CLI Reference

Managing Hook Packs: installazione, aggiornamento e flusso di lavoro --dry-run

I pacchetti di ganci raggruppano più ganci correlati come un'unica unità installabile. Il flusso di lavoro di installazione verifica un file hash di integrità prima di scrivere qualsiasi cosa sul disco.

Bundled Hooks Reference: cosa viene fornito con OpenClaw

Esegui openclaw hooks inspect session-memory per vedere le sue opzioni di configurazione complete. La maggior parte degli hook in bundle vengono forniti con impostazioni predefinite ragionevoli ma espongono campi di configurazione per la personalizzazione.

Casi d'uso degli hook nel mondo reale (con esempi funzionanti)

1. File Protection Guardrail (PreToolUse)

Impedisci all'agente di toccare il tuo file .env:

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." };
  }
}

Rilascialo in .openclaw/hooks/protect-env/ con la sottoscrizione HOOK.md corrispondente a PreToolUse con ambito write_file e edit_file. L'agente riceve il motivo del rifiuto nel relativo contesto e non riproverà.

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

Sottoscrivi questo hook all'evento Stop. Ogni fine sessione genera un messaggio Slack con un riepilogo. Non è necessario alcun server esterno: il processo Gateway effettua direttamente la richiesta in uscita.

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

Questo si attiva dopo ogni scrittura del file TypeScript, lo formatta, quindi esegue la suite di test. Lento nei progetti di grandi dimensioni: adattalo strettamente utilizzando il campo Tools in HOOK.md.

Hooks for Teams: applicazione dei guardrail in un progetto condiviso

Affida la tua directory .openclaw/hooks/ al controllo della versione. Ogni sviluppatore che clona il repository ha automaticamente la stessa configurazione di hook.

• Blocca gli hook critici su enabled nella configurazione del progetto - impedisce ai compagni di squadra di disabilitare accidentalmente le protezioni dei file
• Utilizza le descrizioni HOOK.md per documentare l'intento - trattali come commenti in codice, i compagni di squadra li leggeranno
• Scope hooks to tool-level granularity - Gli hook ampi rallentano tutte le interazioni degli agenti, creando attriti che inducono i compagni di squadra a disabilitarli
• In monorepos, gli hook in una directory padre si applicano a tutti i progetti annidati a meno che non vengano sovrascritti a livello di sottodirectory

CI/CD Integration — Esecuzione di OpenClaw Hooks in modo non interattivo

Nelle azioni GitHub o in qualsiasi ambiente headless, la richiesta di conferma interattiva bloccherà la pipeline. Utilizza --yes per saltarlo:

- 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: cosa funziona, a cosa può accedere e come rimanere al sicuro

Questa è la parte che la maggior parte della documentazione salta completamente ed è la sezione più importante se stai installando hook pack della comunità.

A quali hook può accedere: Gli script hook ereditano il file autorizzazioni complete del processo Gateway. Se il Gateway viene eseguito come account utente, i tuoi hook possono leggere qualsiasi file che l'account può leggere, effettuare richieste di rete, eseguire sottoprocessi e accedere alle variabili di ambiente inclusi i segreti.

Hook Pack Audit Checklist

Eseguilo prima di installare qualsiasi pacchetto di terze parti:

Il comando openclaw hooks inspect mostra il percorso sorgente completo di un hook installato: utilizzalo per rivedere il codice del gestore dopo gli aggiornamenti.

Troubleshooting OpenClaw Hooks — Quando non sparano

Frequently Asked Questions

Considerazioni finali: scegliere la strategia di hook giusta per il flusso di lavoro

Inizia con un hook che risolve un vero problema: una protezione file o un linter post-scrittura. Fallo funzionare end-to-end prima di stratificare di più. La potenza degli hook è composta: una sessione con tre hook con un buon ambito che funziona senza intoppi è significativamente più affidabile di una con dieci hook con un ambito scarso di cui non ti fidi.