# openclaw hooks

Gestisci gli hook degli agenti (automazioni guidate da eventi per comandi come /new, /reset e l'avvio del gateway).

Eseguire openclaw hooks senza sottocomando equivale a openclaw hooks list.

Correlati:

• Hook: Hook
• Hook dei Plugin: Hook dei Plugin

# Elencare tutti gli hook

openclaw hooks list

Elenca tutti gli hook rilevati dalle directory del workspace, gestite, extra e in bundle. L'avvio del Gateway non carica i gestori di hook interni finché non viene configurato almeno un hook interno.

Opzioni:

• --eligible: Mostra solo gli hook idonei (requisiti soddisfatti)
• --json: Output in JSON
• -v, --verbose: Mostra informazioni dettagliate, inclusi i requisiti mancanti

Output di esempio:

Hooks (4/4 ready)

Ready:
  🚀 boot-md ✓ - Run BOOT.md on gateway startup
  📎 bootstrap-extra-files ✓ - Inject extra workspace bootstrap files during agent bootstrap
  📝 command-logger ✓ - Log all command events to a centralized audit file
  💾 session-memory ✓ - Save session context to memory when /new or /reset command is issued

Esempio (dettagliato):

openclaw hooks list --verbose

Mostra i requisiti mancanti per gli hook non idonei.

Esempio (JSON):

openclaw hooks list --json

Restituisce JSON strutturato per l'uso programmatico.

# Ottenere informazioni su un hook

openclaw hooks info <name>

Mostra informazioni dettagliate su uno specifico hook.

Argomenti:

• <name>: Nome dell'hook o chiave dell'hook (ad esempio, session-memory)

Opzioni:

• --json: Output in JSON

Esempio:

openclaw hooks info session-memory

Output:

💾 session-memory ✓ Ready

Save session context to memory when /new or /reset command is issued

Details:
  Source: openclaw-bundled
  Path: /path/to/openclaw/hooks/bundled/session-memory/HOOK.md
  Handler: /path/to/openclaw/hooks/bundled/session-memory/handler.ts
  Homepage: https://docs.openclaw.ai/automation/hooks#session-memory
  Events: command:new, command:reset

Requirements:
  Config: ✓ workspace.dir

# Verificare l'idoneità degli hook

openclaw hooks check

Mostra il riepilogo dello stato di idoneità degli hook (quanti sono pronti rispetto a quanti non lo sono).

Opzioni:

• --json: Output in JSON

Output di esempio:

Hooks Status

Total hooks: 4
Ready: 4
Not ready: 0

# Abilitare un hook

openclaw hooks enable <name>

Abilita uno specifico hook aggiungendolo alla tua configurazione (~/.openclaw/openclaw.json per impostazione predefinita).

Nota: Gli hook del workspace sono disabilitati per impostazione predefinita finché non vengono abilitati qui o nella configurazione. Gli hook gestiti dai Plugin mostrano plugin:<id> in openclaw hooks list e non possono essere abilitati/disabilitati qui. Abilita/disabilita invece il Plugin.

Argomenti:

• <name>: Nome dell'hook (ad esempio, session-memory)

Esempio:

openclaw hooks enable session-memory

Output:

✓ Enabled hook: 💾 session-memory

Cosa fa:

• Verifica se l'hook esiste ed è idoneo
• Aggiorna hooks.internal.entries.<name>.enabled = true nella tua configurazione
• Salva la configurazione su disco

Se l'hook proviene da <workspace>/hooks/, questo passaggio di opt-in è richiesto prima che il Gateway lo carichi.

Dopo l'abilitazione:

• Riavvia il gateway in modo che gli hook vengano ricaricati (riavvio dell'app nella barra dei menu su macOS, oppure riavvio del processo gateway in sviluppo).

# Disabilitare un hook

openclaw hooks disable <name>

Disabilita uno specifico hook aggiornando la tua configurazione.

Argomenti:

• <name>: Nome dell'hook (ad esempio, command-logger)

Esempio:

openclaw hooks disable command-logger

Output:

⏸ Disabled hook: 📝 command-logger

Dopo la disabilitazione:

• Riavvia il gateway in modo che gli hook vengano ricaricati

# Note

• openclaw hooks list --json, info --json e check --json scrivono JSON strutturato direttamente su stdout.
• Gli hook gestiti dai Plugin non possono essere abilitati o disabilitati qui; abilita o disabilita invece il Plugin proprietario.

# Installare pacchetti di hook

openclaw plugins install <package>        # npm by default
openclaw plugins install npm:<package>    # npm only
openclaw plugins install <package> --pin  # pin version
openclaw plugins install <path>           # local path

Installa pacchetti di hook tramite il programma di installazione unificato dei plugins.

openclaw hooks install funziona ancora come alias di compatibilità, ma stampa un avviso di deprecazione e inoltra a openclaw plugins install.

Le specifiche npm sono solo registry (nome del pacchetto + versione esatta opzionale o dist-tag). Le specifiche Git/URL/file e gli intervalli semver vengono rifiutati. Le installazioni delle dipendenze vengono eseguite localmente al progetto con --ignore-scripts per sicurezza, anche quando la shell ha impostazioni globali di installazione npm.

Le specifiche bare e @latest restano sul canale stabile. Se npm risolve una di queste in una prerelease, OpenClaw si arresta e ti chiede di aderire esplicitamente con un tag prerelease come @beta/@rc o una versione prerelease esatta.

Cosa fa:

• Copia il pacchetto di hook in ~/.openclaw/hooks/<id>
• Abilita gli hook installati in hooks.internal.entries.*
• Registra l'installazione in hooks.internal.installs

Opzioni:

• -l, --link: Collega una directory locale invece di copiarla (la aggiunge a hooks.internal.load.extraDirs)
• --pin: Registra le installazioni npm come name@version risolto esatto in hooks.internal.installs

Archivi supportati: .zip, .tgz, .tar.gz, .tar

Esempi:

# Local directory
openclaw plugins install ./my-hook-pack

# Local archive
openclaw plugins install ./my-hook-pack.zip

# NPM package
openclaw plugins install @openclaw/my-hook-pack

# Link a local directory without copying
openclaw plugins install -l ./my-hook-pack

I pacchetti di hook collegati sono trattati come hook gestiti da una directory configurata dall'operatore, non come hook del workspace.

# Aggiornare pacchetti di hook

openclaw plugins update <id>
openclaw plugins update --all

Aggiorna i pacchetti di hook basati su npm tracciati tramite l'aggiornatore unificato dei plugins.

openclaw hooks update funziona ancora come alias di compatibilità, ma stampa un avviso di deprecazione e inoltra a openclaw plugins update.

Opzioni:

• --all: Aggiorna tutti i pacchetti di hook tracciati
• --dry-run: Mostra cosa cambierebbe senza scrivere

Quando esiste un hash di integrità memorizzato e l'hash dell'artefatto recuperato cambia, OpenClaw stampa un avviso e chiede conferma prima di procedere. Usa l'opzione globale --yes per bypassare i prompt in CI/esecuzioni non interattive.

# Hook in bundle

# session-memory

Salva il contesto della sessione in memoria quando usi /new o /reset.

Abilita:

openclaw hooks enable session-memory

Output: ~/.openclaw/workspace/memory/YYYY-MM-DD-HHMM.md per impostazione predefinita. Imposta hooks.internal.entries.session-memory.llmSlug: true per slug dei nomi file generati dal modello.

Vedi: documentazione di session-memory

# bootstrap-extra-files

Inietta file bootstrap aggiuntivi (ad esempio AGENTS.md / TOOLS.md locali al monorepo) durante agent:bootstrap.

Abilita:

openclaw hooks enable bootstrap-extra-files

Vedi: documentazione di bootstrap-extra-files

# command-logger

Registra tutti gli eventi di comando in un file di audit centralizzato.

Abilita:

openclaw hooks enable command-logger

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

Visualizza log:

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

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

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

Vedi: documentazione di command-logger

# boot-md

Esegue BOOT.md quando il gateway si avvia (dopo l'avvio dei canali).

Eventi: gateway:startup

Abilita:

openclaw hooks enable boot-md

Vedi: documentazione di boot-md

# Correlati

• Riferimento CLI
• Hook di automazione