Automatiza OpenClaw: Crea y gestiona Hooks en minutos

A veces, integrar lógica personalizada en tu flujo de trabajo se siente como intentar encajar piezas de un rompecabezas que no fueron diseñadas para estar juntas. Si alguna vez has deseado que tu entorno de desarrollo reaccionara automáticamente a ciertos eventos sin tener que modificar el núcleo de tu aplicación, los hooks son la solución que estabas buscando.

Con OpenClaw, puedes automatizar tareas y extender la funcionalidad de tu Gateway de forma sencilla. Los hooks son pequeños scripts que se ejecutan cuando ocurre algo dentro del sistema, permitiéndote reaccionar a eventos del agente o del ciclo de vida de la aplicación de manera eficiente.

Inicio rápido

Para empezar a trabajar con hooks, primero necesitas saber cuáles tienes disponibles y cómo activarlos. Sigue estos pasos para gestionar tus hooks desde la CLI:

1. Lista los hooks disponibles:

# List available hooks
openclaw hooks list

# Enable a hook
openclaw hooks enable session-memory

# Check hook status
openclaw hooks check

# Get detailed information
openclaw hooks info session-memory

Tipos de eventos

El Gateway dispara diferentes eventos a lo largo de su ejecución que puedes capturar. Aquí tienes una tabla de referencia con los eventos principales:

Event	When it fires
command:new	/new command issued
command:reset	/reset command issued
command:stop	/stop command issued
command	Any command event (general listener)
session:compact:before	Before compaction summarizes history
session:compact:after	After compaction completes
session:patch	When session properties are modified
agent:bootstrap	Before workspace bootstrap files are injected
gateway:startup	After channels start and hooks are loaded
message:received	Inbound message from any channel
message:transcribed	After audio transcription completes
message:preprocessed	After all media and link understanding completes
message:sent	Outbound message delivered

Escribir hooks

Para crear tus propios hooks, solo necesitas definir una estructura de directorio específica. Cada hook requiere un archivo de metadatos y la implementación de su lógica en Node.js:

1. Crea una carpeta con el nombre de tu hook y añade los archivos necesarios:

my-hook/
├── HOOK.md          # Metadata + documentation
└── handler.ts       # Handler implementation

2. Define los metadatos en HOOK.md:

---
name: my-hook
description: "Short description of what this hook does"
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

Detailed documentation goes here.

3. Implementa la lógica en handler.ts:

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;

Descubrimiento de hooks

El sistema busca hooks en diferentes ubicaciones siguiendo un orden de prioridad. Asegúrate de colocar tus scripts en el lugar correcto para que el Gateway pueda detectarlos:

1. Bundled hooks: incluidos con OpenClaw.
2. Plugin hooks: integrados en plugins instalados.
3. Managed hooks: ubicados en ~/.openclaw/hooks/.
4. Workspace hooks: ubicados en <workspace>/hooks/.

Hooks incluidos

OpenClaw ya viene con varios hooks útiles que puedes habilitar directamente. Aquí tienes los más comunes:

Hook	Events	What it does
session-memory	command:new, command:reset	Saves session context to <workspace>/memory/
bootstrap-extra-files	agent:bootstrap	Injects additional bootstrap files from glob patterns
command-logger	command	Logs all commands to ~/.openclaw/logs/commands.log
boot-md	gateway:startup	Runs BOOT.md when the gateway starts

1. Habilita cualquier hook incluido con:

openclaw hooks enable <hook-name>

Hooks de plugins

Los plugins pueden registrar sus propios hooks mediante el SDK para una integración más profunda. Esto te permite interceptar llamadas a herramientas, modificar prompts o controlar el flujo de mensajes.

1. Consulta la arquitectura de plugins para ver la referencia completa de hooks disponibles en Plugin Architecture.

Configuración

Puedes gestionar tus hooks a través del archivo de configuración principal. Aquí te muestro cómo habilitar hooks específicos o definir variables de entorno personalizadas:

1. Edita tu configuración en formato JSON:

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

2. Añade variables de entorno si tu hook las requiere:

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

Referencia de la CLI

La CLI es tu mejor aliada para gestionar el ciclo de vida de los hooks. Utiliza estos comandos para mantener el control total:

# List all hooks (add --eligible, --verbose, or --json)
openclaw hooks list

# Show detailed info about a hook
openclaw hooks info <hook-name>

# Show eligibility summary
openclaw hooks check

# Enable/disable
openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>

Mejores prácticas

Para mantener un rendimiento óptimo, sigue estos consejos al desarrollar tus propios hooks:

1. Mantén los manejadores rápidos; delega las tareas pesadas a procesos en segundo plano.
2. Gestiona los errores con bloques try/catch para evitar que un fallo detenga otros hooks.
3. Filtra los eventos lo antes posible para reducir la carga innecesaria.
4. Utiliza claves de evento específicas en lugar de escuchas genéricas.

Solución de problemas

Si algo no funciona como esperas, sigue estos pasos para diagnosticar el problema:

1. Verifica la estructura de directorios:

# Verify directory structure
ls -la ~/.openclaw/hooks/my-hook/
# Should show: HOOK.md, handler.ts

# List all discovered hooks
openclaw hooks list

2. Comprueba la elegibilidad del hook:

openclaw hooks info my-hook

3. Si el hook no se ejecuta, asegúrate de que esté habilitado, reinicia el Gateway y revisa los logs.

Relacionado

• CLI Reference: hooks
• Webhooks
• Plugin Architecture

Si necesitas ayuda adicional, puedes consultar nuestro AI Setup Assistant.

openclaw plugins install <path-or-spec>

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

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