OpenClaw Hooks: La guía completa para desarrolladores (2026) — EasyClaw

Cómo funciona el descubrimiento de ganchos OpenClaw

La puerta de enlace utiliza escaneo automático de directorios para descubrir ganchos. Al iniciarse, escanea los directorios de enlaces configurados y carga cualquier paquete de enlaces válido que encuentre.

Dos requisitos previos importantes antes de que se activen los ganchos:

1. Hooks debe ser habilitado explícitamente — un directorio de enlace por sí solo no es suficiente
2. Al menos se debe configurar una entrada de gancho en la configuración de tu puerta de enlace

Cada paquete de gancho requiere exactamente dos archivos:

• HOOK.md — archivo de metadatos que declara el nombre, la versión, la descripción, las suscripciones a eventos del ciclo de vida y los permisos necesarios del gancho
• handler.ts (o handler.js): el archivo de implementación que contiene la lógica real que se ejecuta cuando se activa el evento.

Los cuatro eventos del ciclo de vida que todo desarrollador debería conocer

PreToolUse es el más poderoso: es el único evento que puede abortar una llamada a la herramienta antes de que se ejecute. Si su gancho devuelve una señal de rechazo durante PreToolUse, el agente nunca llama a la herramienta.

PostToolUse es el caballo de batalla para la automatización. ¿Archivo escrito? Ejecute su linter. ¿Prueba modificada? Ejecute la suite. ¿Código comprometido? Activa una construcción.

Step-by-Step: escribiendo su primer gancho personalizado desde cero

La mayoría de la documentación muestra comandos. Esto le muestra el camino completo desde la nada hasta un gancho que funciona.

Step 1: crea el directorio de enlace

mkdir -p .OpenClaw/hooks/auto-lint

Step 2: escribe los metadatos HOOK.md

# auto-lint

**Version:** 1.0.0
**Event:** PostToolUse
**Description:** Runs ESLint on any file written by the agent
**Tools:** write_file, edit_file

El campo Tools limita su enlace a llamadas de herramientas específicas. Sin él, el gancho sigue disparando. cada Evento PostToolUse: normalmente no es lo que desea.

Step 3: implementar handler.ts

import { PostToolUseEvent } from "@OpenClaw/sdk";
import { execSync } from "child_process";

export default function handler(event: PostToolUseEvent) {
  const filePath = event.toolResult?.path;
  if (!filePath) return;

  try {
    execSync(`npx eslint --fix "${filePath}"`, { stdio: "inherit" });
  } catch (err) {
    console.error(`[auto-lint] ESLint failed on ${filePath}`);
  }
}

Step 4: habilitar mediante CLI

OpenClaw hooks enable auto-lint

Step 5: verifica que esté cargado

OpenClaw hooks list

Deberías ver auto-lint con estado enabled. Inicie una sesión, escriba un archivo y observe cómo se activa el linter.

JavaScript frente a TypeScript para manipuladores de ganchos: qué elegir en 2026

El SDK se envía con tipificaciones TypeScript completas y, a partir de las versiones del SDK de 2026, TypeScript es el valor predeterminado recomendado para ganchos nuevos.

Si está escribiendo un enlace que se comprometerá con el control de versiones o lo compartirá con un equipo, use TypeScript. Para una barandilla local desechable, JavaScript simple está bien; simplemente asígnele el nombre handler.js y omita el paso de compilación.

OpenClaw Hooks CLI Reference

Managing Hook Packs: instalación, actualización y flujo de trabajo --dry-run

Los paquetes de ganchos agrupan varios ganchos relacionados como una única unidad instalable. El flujo de trabajo de instalación verifica una hash de integridad antes de escribir algo en el disco.

# Preview what would be installed without committing
OpenClaw hooks install productivity-pack --dry-run

# Install non-interactively (for CI environments)
OpenClaw hooks install productivity-pack --yes

# Update all installed packs
OpenClaw hooks update --all

Bundled Hooks Reference: Qué se envía con OpenClaw

Ejecute OpenClaw hooks inspect session-memory para ver sus opciones de configuración completas. La mayoría de los ganchos incluidos se envían con valores predeterminados razonables, pero exponen los campos de configuración para su personalización.

Casos de uso de ganchos del mundo real (con ejemplos prácticos)

1. File Protection Guardrail (PreToolUse)

Evite que el agente toque su archivo .env:

import { PreToolUseEvent } from "@OpenClaw/sdk";

export default function handler(event: PreToolUseEvent) {
  const target = event.toolInput?.path ?? "";
  if (target.includes(".env")) {
    return { abort: true, reason: "Modification of .env files is blocked by policy." };
  }
}

Coloque esto en .OpenClaw/hooks/protect-env/ con el HOOK.md correspondiente suscribiéndose a PreToolUse con alcance a write_file y edit_file. El agente recibe el motivo del rechazo en su contexto y no volverá a intentarlo.

2. Slack Notification on Session Stop

import { StopEvent } from "@OpenClaw/sdk";

export default async function handler(event: StopEvent) {
  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `OpenClaw session ended. Files modified: ${event.session.filesModified ?? 0}`
    })
  });
}

Suscríbase a este enlace al evento Stop. Cada final de sesión activa un mensaje Slack con un resumen. No se necesita un servidor externo: el proceso de puerta de enlace realiza la solicitud de salida directamente.

3. Auto-Format + Test on PostToolUse

import { PostToolUseEvent } from "@OpenClaw/sdk";
import { execSync } from "child_process";

export default function handler(event: PostToolUseEvent) {
  const file = event.toolResult?.path;
  if (!file?.endsWith(".ts")) return;

  execSync(`prettier --write "${file}"`);
  execSync("npm test -- --passWithNoTests", { stdio: "inherit" });
}

Esto se activa después de cada escritura de archivo TypeScript, lo formatea y luego ejecuta su conjunto de pruebas. Lento en proyectos grandes: alcance un alcance estricto utilizando el campo Tools en HOOK.md.

Hooks para equipos: aplicación de barreras de seguridad en un proyecto compartido

Confirme su directorio .OpenClaw/hooks/ al control de versiones. Cada desarrollador que clona el repositorio automáticamente tiene la misma configuración de enlace.

• Bloquee los enlaces críticos a enabled en la configuración del proyecto — evita que los compañeros de equipo desactiven accidentalmente los protectores de archivos
• Utilice descripciones HOOK.md para documentar la intención — trátelos como comentarios de código, los compañeros de equipo los leerán
• Scope hooks to tool-level granularity — Los ganchos amplios ralentizan todas las interacciones de los agentes, creando fricción que hace que los compañeros de equipo los desactiven.
• En monorepos, los enlaces en un directorio principal se aplican a todos los proyectos anidados a menos que se anulen en el nivel del subdirectorio.

CI/CD Integration: ejecución de OpenClaw Hooks de forma no interactiva

En acciones GitHub o en cualquier entorno sin cabeza, el mensaje de confirmación interactivo bloqueará su canalización. Utilice --yes para omitirlo:

- name: Install hooks non-interactively
  run: OpenClaw hooks install qa-pack --yes

- name: Run OpenClaw session
  env:
    OpenClaw_HOOKS_ENABLED: "true"
    SLACK_WEBHOOK_URL: secrets.SLACK_WEBHOOK_URL
  run: OpenClaw run --task "audit dependencies" --yes

Hook Security: Qué se ejecuta, a qué puede acceder y cómo mantenerse seguro

Esta es la parte que la mayoría de la documentación omite por completo, y es la sección más importante si estás instalando paquetes de enlaces comunitarios.

A qué ganchos puede acceder: Los scripts de gancho heredan el permisos completos del proceso Gateway. Si Gateway se ejecuta como su cuenta de usuario, sus enlaces pueden leer cualquier archivo que esa cuenta pueda leer, realizar solicitudes de red, ejecutar subprocesos y acceder a variables de entorno, incluidos los secretos.

Hook Pack Audit Checklist

Ejecute esto antes de instalar cualquier paquete de terceros:

El comando OpenClaw hooks inspect le muestra la ruta de origen completa de un enlace instalado; utilícelo para volver a revisar el código del controlador después de las actualizaciones.

Troubleshooting OpenClaw Hooks — Cuando no disparan

Frequently Asked Questions

Reflexiones finales: elegir la estrategia de gancho adecuada para su flujo de trabajo

Comience con un gancho que resuelva un problema real: un protector de archivos o un linter posterior a la escritura. Haz que funcione de un extremo a otro antes de aplicar más capas. El poder de los ganchos se complica: una sesión con tres ganchos con buen alcance funcionando sin problemas es significativamente más confiable que una con diez ganchos con mal alcance en los que no confías.