Hooks
Los hooks son scripts pequeños que se ejecutan cuando ocurre algo dentro del Gateway. Se descubren automáticamente desde directorios y pueden inspeccionarse con openclaw hooks.
Hay dos tipos de hooks en OpenClaw:
- Hooks internos (esta página): se ejecutan dentro del Gateway cuando se disparan 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 gestionados por plugins.
Inicio rápido
# Listar hooks disponibles
openclaw hooks list
# Habilitar un hook
openclaw hooks enable session-memory
# Comprobar el estado del hook
openclaw hooks check
# Obtener información detallada
openclaw hooks info session-memory
Tipos de eventos
| Evento | Cuándo se dispara |
|---|
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 complete 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 que se inicien los canales y se carguen los hooks |
message:received | Mensaje entrante desde cualquier canal |
message:transcribed | Después de que se complete la transcripción de audio |
message:preprocessed | Después de que se complete 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
---
name: my-hook
description: "Descripción breve de lo que hace este hook"
metadata:
{ "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---
# Mi Hook
La documentación detallada va aquí.
metadata.openclaw):
| Campo | Descripción |
|---|
emoji | Emoji que se muestra en la CLI |
events | Array de eventos que se deben escuchar |
export | Exportación con nombre que se debe usar (por defecto "default") |
os | Plataformas requeridas (por ejemplo, ["darwin", "linux"]) |
requires | Rutas de bins, anyBins, env o config requeridas |
always | Omite las comprobaciones de elegibilidad (booleano) |
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;
type, action, sessionKey, timestamp, messages (haz push para enviar al usuario) y context (datos específicos del evento).
Puntos destacados del contexto del evento
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 los campos modificados), context.cfg. Solo los clientes con privilegios 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: se distribuyen con OpenClaw
- Hooks de plugins: hooks incluidos dentro de plugins instalados
- Hooks gestionados:
~/.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 nuevos nombres de hook, pero no pueden sobrescribir hooks incluidos, gestionados 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>
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 |
openclaw hooks enable <hook-name>
Detalles de session-memory
Extrae los últimos 15 mensajes de usuario/asistente, genera un slug descriptivo para el nombre de archivo mediante un LLM y lo guarda en <workspace>/memory/YYYY-MM-DD-slug.md. Requiere que workspace.dir esté configurado.
{
"hooks": {
"internal": {
"entries": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
}
}
}
}
}
AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md).
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 }
}
}
}
}
{
"hooks": {
"internal": {
"entries": {
"my-hook": {
"enabled": true,
"env": { "MY_CUSTOM_VAR": "value" }
}
}
}
}
}
{
"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 (añade --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 el trabajo pesado en segundo plano sin esperar con
void processInBackground(event).
- Maneja los errores correctamente. Envuelve las operaciones arriesgadas en try/catch; no lances excepciones para que otros handlers puedan ejecutarse.
- Filtra los eventos pronto. Devuelve 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
Hook no se ejecuta
- Verifica que el hook esté habilitado:
openclaw hooks list
- Reinicia tu proceso de gateway para que los hooks se recarguen.
- Revisa los logs del gateway:
./scripts/clawlog.sh | grep hook
Relacionado
