Hook

Gli hook sono piccoli script eseguiti all'interno del Gateway quando si verificano eventi dell'agente: comandi come /new, /reset, /stop, Compaction della sessione, ciclo di vita del Gateway e flusso dei messaggi. Vengono individuati nelle directory e gestiti con openclaw hooks. Il Gateway carica gli hook interni solo dopo che gli hook sono stati abilitati o è stata configurata almeno una voce hook, un pacchetto di hook, un gestore legacy o una directory di hook aggiuntiva.

In OpenClaw esistono due tipi di hook:

• Hook interni (questa pagina): vengono eseguiti all'interno del Gateway quando si verificano eventi dell'agente.
• Webhook: endpoint HTTP esterni che consentono ad altri sistemi di attivare attività in OpenClaw. Vedere Webhook.

Gli hook possono anche essere inclusi nei plugin. openclaw hooks list mostra sia gli hook autonomi sia quelli gestiti dai plugin (visualizzati come plugin:<id>).

Scegliere l'interfaccia appropriata

OpenClaw dispone di diverse interfacce di estensione che sembrano simili ma risolvono problemi differenti:

Usare gli hook interni per automazioni che si comportano come una piccola integrazione installata. Usare gli hook tipizzati dei plugin quando è necessario controllare il ciclo di vita in fase di esecuzione.

Avvio rapido

# Elenca gli hook disponibiliopenclaw hooks list # Abilita un hookopenclaw hooks enable session-memory # Controlla lo stato degli hookopenclaw hooks check # Ottieni informazioni dettagliateopenclaw hooks info session-memory

Tipi di evento

Gli hook si registrano a una chiave specifica di questa tabella oppure al solo nome di una famiglia (command, session, agent, gateway, message) per ricevere ogni azione di tale famiglia. Il nucleo di OpenClaw non emette altri eventi, quindi qualsiasi altro nome è quasi sempre un errore di battitura che lascia l'hook silenziosamente inattivo (solo un plugin che emette un evento personalizzato potrebbe attivarlo). Il caricatore degli hook registra un avviso per tali nomi (ad esempio command:nwe) e openclaw hooks info <name> li segnala, rendendo quindi diagnosticabile un hook che non viene mai eseguito.

Scrittura degli hook

Struttura di un hook

Ogni hook è una directory contenente due file:

my-hook/├── HOOK.md          # Metadati + documentazione└── handler.ts       # Implementazione del gestore

Il file del gestore può essere handler.ts, handler.js, index.ts o index.js.

Formato di HOOK.md

---name: my-hookdescription: "Breve descrizione della funzione di questo hook"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # Il mio hook La documentazione dettagliata va inserita qui.

Campi dei metadati (metadata.openclaw):

Implementazione del gestore

const handler = async (event) => {  if (event.type !== "command" || event.action !== "new") {    return;  }   console.log(`[my-hook] New command triggered`);  // Your logic here   // Optionally send a reply on replyable surfaces  event.messages.push("Hook executed!");}; export default handler;

Ogni evento include: type, action, sessionKey, timestamp, messages e context (dati specifici dell'evento). I contesti degli hook tipizzati dei plugin per gli hook di agente e strumenti possono includere anche trace, un contesto di traccia diagnostica di sola lettura compatibile con W3C che i plugin possono passare ai log strutturati per la correlazione OTEL.

Le stringhe aggiunte a event.messages vengono recapitate alla chat solo per command:new e command:reset (instradate come risposta alla conversazione di origine) e per session:compact:before / session:compact:after (inviate come notifiche sullo stato della Compaction). Tutti gli altri eventi, inclusi command:stop, message:*, agent:bootstrap, session:patch e gateway:*, ignorano i messaggi aggiunti.

Elementi principali del contesto degli eventi

Eventi di comando (command:new, command:reset): context.sessionEntry, context.previousSessionEntry, context.commandSource, context.senderId, context.workspaceDir, context.cfg.

Eventi di comando (command:stop): context.sessionEntry, context.sessionId, context.commandSource, context.senderId.

Eventi di messaggio (message:received): context.from, context.content, context.channelId, context.metadata (dati specifici del provider, inclusi senderId, senderName, guildId). Per i messaggi simili a comandi, context.content preferisce il corpo non vuoto del comando, quindi usa come ripiego il corpo grezzo in entrata e quello generico; non include arricchimenti riservati all'agente, come la cronologia del thread o i riepiloghi dei collegamenti.

Eventi di messaggio (message:sent): context.to, context.content, context.success, context.channelId, oltre a context.error quando l'invio non riesce.

Eventi di messaggio (message:transcribed): context.transcript, context.from, context.channelId, context.mediaPath.

Eventi di messaggio (message:preprocessed): context.bodyForAgent (corpo finale arricchito), context.from, context.channelId.

Eventi di bootstrap (agent:bootstrap): context.bootstrapFiles (array modificabile), context.agentId.

Eventi di modifica della sessione (session:patch): context.sessionEntry, context.patch (solo i campi modificati), context.cfg. Solo i client privilegiati possono attivare eventi di modifica; il contesto è un clone, pertanto i gestori non possono modificare la voce della sessione attiva.

Eventi di Compaction: session:compact:before include messageCount, tokenCount. session:compact:after aggiunge compactedCount, summaryLength, tokensBefore, tokensAfter.

command:stop rileva quando l'utente impartisce /stop; riguarda l'annullamento e il ciclo di vita del comando, non è un punto di controllo per la finalizzazione dell'agente. I plugin che devono esaminare una risposta finale naturale e chiedere all'agente un ulteriore passaggio devono invece usare l'hook tipizzato del plugin before_agent_finalize. Vedere Hook dei plugin.

Eventi del ciclo di vita del Gateway: gateway:shutdown include reason e restartExpectedMs e viene attivato quando inizia l'arresto del Gateway. gateway:pre-restart include lo stesso contesto, ma viene attivato solo quando l'arresto fa parte di un riavvio previsto e viene fornito un valore finito di restartExpectedMs. Durante l'arresto, l'attesa per ciascun hook del ciclo di vita avviene secondo il principio del massimo sforzo ed è limitata, affinché l'arresto prosegua se un gestore si blocca. Il limite di attesa predefinito è di 5 secondi per gateway:shutdown e di 10 secondi per gateway:pre-restart.

Usare gateway:pre-restart per brevi notifiche di riavvio mentre i canali sono ancora disponibili:

  const execFileAsync = promisify(execFile); export default async function handler(event) {  if (event.type !== "gateway" || event.action !== "pre-restart") {    return;  }   const restartInSeconds = Math.ceil(event.context.restartExpectedMs / 1000);  await execFileAsync("openclaw", [    "system",    "event",    "--mode",    "now",    "--text",    `Gateway restarting in ~${restartInSeconds}s (${event.context.reason}). Checkpoint now.`,  ]);}

Tra l'evento gateway:shutdown (o gateway:pre-restart) e il resto della sequenza di arresto, il Gateway attiva anche un hook tipizzato del plugin session_end per ogni sessione che era ancora attiva al momento dell'arresto del processo. Il valore reason dell'evento è shutdown per un normale arresto SIGTERM/SIGINT e restart quando la chiusura è stata pianificata nell'ambito di un riavvio previsto. Questo svuotamento è limitato, affinché un gestore session_end lento non possa bloccare l'uscita del processo; le sessioni già finalizzate tramite sostituzione, reimpostazione, eliminazione o Compaction vengono ignorate per evitare una doppia attivazione.

Individuazione degli hook

Gli hook vengono individuati da quattro origini:

1. Hook inclusi: distribuiti con OpenClaw
2. Hook dei plugin: inclusi nei plugin installati; possono sostituire gli hook inclusi con lo stesso nome
3. Hook gestiti: ~/.openclaw/hooks/ (installati dall'utente e condivisi tra gli spazi di lavoro); possono sostituire gli hook inclusi e quelli dei plugin. Le directory aggiuntive definite in hooks.internal.load.extraDirs condividono questa precedenza.
4. Hook dello spazio di lavoro: <workspace>/hooks/ (specifici dell'agente, disabilitati per impostazione predefinita finché non vengono abilitati esplicitamente)

Gli hook dello spazio di lavoro possono aggiungere nuovi nomi di hook, ma non possono sostituire hook inclusi, gestiti o forniti dai plugin con lo stesso nome.

All'avvio, il Gateway omette l'individuazione degli hook interni finché questi non vengono configurati. Abilitare un hook incluso o gestito con openclaw hooks enable <name>, installare un pacchetto di hook oppure impostare hooks.internal.enabled=true per effettuare l'attivazione. Quando viene abilitato un singolo hook denominato, il Gateway carica solo il gestore di quell'hook; hooks.internal.enabled=true, le directory di hook aggiuntive e i gestori legacy attivano l'individuazione estesa.

Pacchetti di hook

I pacchetti di hook sono pacchetti npm che esportano hook tramite openclaw.hooks in package.json. Installare con:

openclaw plugins install <path-or-spec>

Le specifiche npm sono limitate al registro (nome del pacchetto + versione esatta o dist-tag facoltativi). Le specifiche Git/URL/file e gli intervalli semver vengono rifiutati. I precedenti comandi openclaw hooks install e openclaw hooks update sono alias deprecati di openclaw plugins install / openclaw plugins update.

Hook inclusi

Abilita un qualsiasi hook incluso:

openclaw hooks enable <hook-name>

Dettagli di session-memory

Estrae gli ultimi messaggi dell'utente e dell'assistente (15 per impostazione predefinita, configurabili con hooks.internal.entries.session-memory.messages) e li salva in <workspace>/memory/YYYY-MM-DD-HHMM.md usando la data locale dell'host. L'acquisizione della memoria viene eseguita in background, in modo che le conferme di /new e /reset non subiscano ritardi dovuti alla lettura della trascrizione o alla generazione facoltativa dello slug. Imposta hooks.internal.entries.session-memory.llmSlug: true per generare slug descrittivi per i nomi dei file e, facoltativamente, imposta hooks.internal.entries.session-memory.model su un alias configurato come sonnet, un ID modello semplice del provider predefinito dell'agente oppure un riferimento provider/model. Quando model è omesso, la generazione dello slug usa il modello predefinito dell'agente e, se non è disponibile, ricorre a slug basati sul timestamp. Richiede che workspace.dir sia configurato.

Configurazione di bootstrap-extra-files

{  "hooks": {    "internal": {      "entries": {        "bootstrap-extra-files": {          "enabled": true,          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]        }      }    }  }}

patterns e files sono accettati come alias di paths. I percorsi vengono risolti relativamente allo spazio di lavoro e devono rimanere al suo interno. Vengono caricati solo i nomi di base di bootstrap riconosciuti (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md).

Dettagli di command-logger

Registra ogni comando slash come una riga JSON (timestamp, azione, chiave di sessione, ID del mittente, origine) in ~/.openclaw/logs/commands.log.

Dettagli di compaction-notifier

Invia brevi messaggi di stato nella conversazione corrente quando OpenClaw inizia e termina la Compaction della trascrizione della sessione. Ciò rende meno ambigui i turni lunghi nelle interfacce di chat, perché l'utente può vedere che l'assistente sta riepilogando il contesto e continuerà dopo la Compaction.

Dettagli di boot-md

Esegue BOOT.md all'avvio del Gateway per ogni ambito agente configurato, se il file esiste nello spazio di lavoro risolto dell'agente.

Hook dei Plugin

I Plugin possono registrare hook tipizzati tramite l'SDK dei Plugin per un'integrazione più profonda: intercettare le chiamate agli strumenti, modificare i prompt, controllare il flusso dei messaggi e altro ancora. Usa gli hook dei Plugin quando sono necessari before_tool_call, before_agent_reply, before_install o altri hook del ciclo di vita interni al processo.

Gli hook interni gestiti dai Plugin sono diversi: partecipano al sistema generale di eventi dei comandi e del ciclo di vita descritto in questa pagina e compaiono in openclaw hooks list come plugin:<id>. Usali per gli effetti collaterali e la compatibilità con i pacchetti di hook, non per middleware ordinati o controlli delle policy.

Per il riferimento completo sugli hook dei Plugin, consulta Hook dei Plugin.

Configurazione

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

I valori di ambiente specifici per ogni hook soddisfano i controlli di idoneità requires.env dell'hook (insieme all'ambiente del processo) e i gestori possono leggerli dalla voce di configurazione dell'hook:

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

Directory aggiuntive degli hook:

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

Riferimento CLI

# Elenca tutti gli hook (aggiungi --eligible, --verbose o --json)openclaw hooks list # Mostra informazioni dettagliate su un hookopenclaw hooks info <hook-name> # Mostra il riepilogo dell'idoneitàopenclaw hooks check # Abilita/disabilitaopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

Procedure consigliate

• Mantieni veloci i gestori. Gli hook vengono eseguiti durante l'elaborazione dei comandi. Avvia le operazioni pesanti senza attenderne il completamento con void processInBackground(event).
• Gestisci gli errori correttamente. Racchiudi le operazioni rischiose in try/catch; non generare eccezioni, affinché gli altri gestori possano essere eseguiti.
• Filtra tempestivamente gli eventi. Termina immediatamente se il tipo o l'azione dell'evento non è pertinente.
• Usa chiavi evento specifiche. Preferisci "events": ["command:new"] a "events": ["command"] per ridurre il sovraccarico.

Risoluzione dei problemi

Hook non rilevato

# Verifica la struttura della directoryls -la ~/.openclaw/hooks/my-hook/# Dovrebbe mostrare: HOOK.md, handler.ts # Elenca tutti gli hook rilevatiopenclaw hooks list

Hook non idoneo

openclaw hooks info my-hook

Verifica la presenza di binari mancanti (PATH), variabili di ambiente, valori di configurazione o problemi di compatibilità con il sistema operativo.

Hook non eseguito

1. Verifica che l'hook sia abilitato: openclaw hooks list
2. Riavvia il processo del Gateway per ricaricare gli hook.
3. Controlla i log del Gateway: openclaw logs --follow | grep -i hook

Argomenti correlati

• Riferimento CLI: hook
• Webhook
• Hook dei Plugin — hook del ciclo di vita dei Plugin interni al processo
• Configurazione