Hooks

Los hooks son scripts pequeños que se ejecutan cuando sucede algo dentro del Gateway. Se descubren automáticamente desde directorios y se pueden inspeccionar con openclaw hooks. Hay dos tipos de hooks en OpenClaw:

Hooks internos (esta página): se ejecutan dentro del Gateway cuando se activan eventos del agente, como /new, /reset, /stop o eventos del ciclo de vida.
Webhooks: endpoints HTTP externos que permiten que otros sistemas activen trabajo en OpenClaw. Consulta Webhooks.

Los hooks también pueden incluirse dentro de plugins. openclaw hooks list muestra tanto hooks independientes como hooks administrados por plugins.

Inicio rápido

# Listar hooks disponibles
openclaw hooks list

# Habilitar un hook
openclaw hooks enable session-memory

# Verificar el estado del hook
openclaw hooks check

# Obtener información detallada
openclaw hooks info session-memory

Tipos de eventos

Evento	Cuándo se activa
`command:new`	Se emite el comando `/new`
`command:reset`	Se emite el comando `/reset`
`command:stop`	Se emite el comando `/stop`
`command`	Cualquier evento de comando (listener general)
`session:compact:before`	Antes de que la compactación resuma el historial
`session:compact:after`	Después de que se completa la compactación
`session:patch`	Cuando se modifican las propiedades de la sesión
`agent:bootstrap`	Antes de inyectar los archivos bootstrap del workspace
`gateway:startup`	Después de iniciar los canales y cargar los hooks
`message:received`	Mensaje entrante desde cualquier canal
`message:transcribed`	Después de completar la transcripción de audio
`message:preprocessed`	Después de completar todo el procesamiento de medios y enlaces
`message:sent`	Mensaje saliente entregado

Escribir hooks

Estructura de un hook

Cada hook es un directorio que contiene dos archivos:

my-hook/
├── HOOK.md          # Metadatos + documentación
└── handler.ts       # Implementación del handler

Formato de HOOK.md

---
name: my-hook
description: "Breve descripción de lo que hace este hook"
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

La documentación detallada va aquí.

Campos de metadatos (metadata.openclaw):

Campo	Descripción
`emoji`	Emoji mostrado para la CLI
`events`	Array de eventos que se escucharán
`export`	Export nombrado que se usará (por defecto `"default"`)
`os`	Plataformas requeridas (p. ej., `["darwin", "linux"]`)
`requires`	Rutas requeridas de `bins`, `anyBins`, `env` o `config`
`always`	Omite las comprobaciones de elegibilidad (boolean)
`install`	Métodos de instalación

Implementación del handler

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

  console.log(`[my-hook] New command triggered`);
  // Your logic here

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

export default handler;

Cada evento incluye: type, action, sessionKey, timestamp, messages (haz push para enviarlos al usuario) y context (datos específicos del evento).

Aspectos destacados del contexto de eventos

Eventos de comando (command:new, command:reset): context.sessionEntry, context.previousSessionEntry, context.commandSource, context.workspaceDir, context.cfg. Eventos de mensaje (message:received): context.from, context.content, context.channelId, context.metadata (datos específicos del proveedor, incluidos senderId, senderName, guildId). Eventos de mensaje (message:sent): context.to, context.content, context.success, context.channelId. Eventos de mensaje (message:transcribed): context.transcript, context.from, context.channelId, context.mediaPath. Eventos de mensaje (message:preprocessed): context.bodyForAgent (cuerpo final enriquecido), context.from, context.channelId. Eventos bootstrap (agent:bootstrap): context.bootstrapFiles (array mutable), context.agentId. Eventos de parche de sesión (session:patch): context.sessionEntry, context.patch (solo campos modificados), context.cfg. Solo los clientes privilegiados pueden activar eventos de parche. Eventos de compactación: session:compact:before incluye messageCount, tokenCount. session:compact:after agrega compactedCount, summaryLength, tokensBefore, tokensAfter.

Descubrimiento de hooks

Los hooks se descubren desde estos directorios, en orden de precedencia creciente de sobrescritura:

Hooks incluidos: enviados con OpenClaw
Hooks de plugins: hooks incluidos dentro de plugins instalados
Hooks administrados: ~/.openclaw/hooks/ (instalados por el usuario, compartidos entre workspaces). Los directorios adicionales de hooks.internal.load.extraDirs comparten esta precedencia.
Hooks del workspace: <workspace>/hooks/ (por agente, deshabilitados por defecto hasta que se habilitan explícitamente)

Los hooks del workspace pueden agregar nombres de hooks nuevos, pero no pueden sobrescribir hooks incluidos, administrados o proporcionados por plugins con el mismo nombre.

Paquetes de hooks

Los paquetes de hooks son paquetes npm que exportan hooks mediante openclaw.hooks en package.json. Instálalos con:

openclaw plugins install <path-or-spec>

Las especificaciones npm son solo de registro (nombre del paquete + versión exacta opcional o dist-tag). Se rechazan las especificaciones Git/URL/file y los rangos semver.

Hooks incluidos

Hook	Eventos	Qué hace
session-memory	`command:new`, `command:reset`	Guarda el contexto de la sesión en `<workspace>/memory/`
bootstrap-extra-files	`agent:bootstrap`	Inyecta archivos bootstrap adicionales a partir de patrones glob
command-logger	`command`	Registra todos los comandos en `~/.openclaw/logs/commands.log`
boot-md	`gateway:startup`	Ejecuta `BOOT.md` cuando se inicia el gateway

Habilita cualquier hook incluido:

openclaw hooks enable <hook-name>

Detalles de session-memory

Extrae los últimos 15 mensajes de usuario/asistente, genera un slug descriptivo de nombre de archivo mediante un LLM y lo guarda en <workspace>/memory/YYYY-MM-DD-slug.md. Requiere que workspace.dir esté configurado.

Configuración de bootstrap-extra-files

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

Las rutas se resuelven en relación con el workspace. Solo se cargan nombres base bootstrap reconocidos (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md).

Detalles de command-logger

Registra cada comando con barra en ~/.openclaw/logs/commands.log.

Detalles de boot-md

Ejecuta BOOT.md desde el workspace activo cuando se inicia el gateway.

Hooks de plugins

Los plugins pueden registrar hooks mediante el Plugin SDK para una integración más profunda: interceptar llamadas a herramientas, modificar prompts, controlar el flujo de mensajes y más. El Plugin SDK expone 28 hooks que cubren la resolución de modelos, el ciclo de vida del agente, el flujo de mensajes, la ejecución de herramientas, la coordinación de subagentes y el ciclo de vida del gateway. Para la referencia completa de hooks de plugins, incluidos before_tool_call, before_agent_reply, before_install y todos los demás hooks de plugins, consulta Plugin Architecture.

Configuración

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

Variables de entorno por hook:

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

Directorios de hooks adicionales:

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

El formato heredado de configuración de array hooks.internal.handlers todavía es compatible por compatibilidad con versiones anteriores, pero los hooks nuevos deben usar el sistema basado en descubrimiento.

Referencia de la CLI

# Listar todos los hooks (agrega --eligible, --verbose o --json)
openclaw hooks list

# Mostrar información detallada sobre un hook
openclaw hooks info <hook-name>

# Mostrar resumen de elegibilidad
openclaw hooks check

# Habilitar/deshabilitar
openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>

Buenas prácticas

Mantén los handlers rápidos. Los hooks se ejecutan durante el procesamiento de comandos. Ejecuta en segundo plano el trabajo pesado con void processInBackground(event).
Maneja los errores con cuidado. Envuelve las operaciones riesgosas en try/catch; no lances errores para que otros handlers puedan ejecutarse.
Filtra eventos pronto. Haz return inmediatamente si el tipo/acción del evento no es relevante.
Usa claves de evento específicas. Prefiere "events": ["command:new"] en lugar de "events": ["command"] para reducir la sobrecarga.

Solución de problemas

Hook no descubierto

# Verificar la estructura del directorio
ls -la ~/.openclaw/hooks/my-hook/
# Debe mostrar: HOOK.md, handler.ts

# Listar todos los hooks descubiertos
openclaw hooks list

Hook no elegible

openclaw hooks info my-hook

Comprueba si faltan binarios (PATH), variables de entorno, valores de configuración o compatibilidad del SO.

Hook no se ejecuta

Verifica que el hook esté habilitado: openclaw hooks list
Reinicia tu proceso gateway para que los hooks se recarguen.
Revisa los logs del gateway: ./scripts/clawlog.sh | grep hook

Relacionado

CLI Reference: hooks
Webhooks
Plugin Architecture — referencia completa de hooks de plugins
Configuration

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Hooks

Hooks

Inicio rápido

Tipos de eventos

Escribir hooks

Estructura de un hook

Formato de HOOK.md

Implementación del handler

Aspectos destacados del contexto de eventos

Descubrimiento de hooks

Paquetes de hooks

Hooks incluidos

Detalles de session-memory

Configuración de bootstrap-extra-files

Detalles de command-logger

Detalles de boot-md

Hooks de plugins

Configuración

Referencia de la CLI

Buenas prácticas

Solución de problemas

Hook no descubierto

Hook no elegible

Hook no se ejecuta

Relacionado

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

​Hooks

​Inicio rápido

​Tipos de eventos

​Escribir hooks

​Estructura de un hook

​Formato de HOOK.md

​Implementación del handler

​Aspectos destacados del contexto de eventos

​Descubrimiento de hooks

​Paquetes de hooks

​Hooks incluidos

​Detalles de session-memory

​Configuración de bootstrap-extra-files

​Detalles de command-logger

​Detalles de boot-md

​Hooks de plugins

​Configuración

​Referencia de la CLI

​Buenas prácticas

​Solución de problemas

​Hook no descubierto

​Hook no elegible

​Hook no se ejecuta

​Relacionado

Hooks

Inicio rápido

Tipos de eventos

Escribir hooks

Estructura de un hook

Formato de HOOK.md

Implementación del handler

Aspectos destacados del contexto de eventos

Descubrimiento de hooks

Paquetes de hooks

Hooks incluidos

Detalles de session-memory

Configuración de bootstrap-extra-files

Detalles de command-logger

Detalles de boot-md

Hooks de plugins

Configuración

Referencia de la CLI

Buenas prácticas

Solución de problemas

Hook no descubierto

Hook no elegible

Hook no se ejecuta

Relacionado