Hooks de Plugin

​

Inicio rápido

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "tool-preflight",
  name: "Tool Preflight",
  register(api) {
    api.on(
      "before_tool_call",
      async (event) => {
        if (event.toolName !== "web_search") {
          return;
        }

        return {
          requireApproval: {
            title: "Run web search",
            description: `Allow search query: ${String(event.params.query ?? "")}`,
            severity: "info",
            timeoutMs: 60_000,
            timeoutBehavior: "deny",
          },
        };
      },
      { priority: 50 },
    );
  },
});

{
  "plugins": {
    "entries": {
      "my-plugin": {
        "hooks": {
          "timeoutMs": 30000,
          "timeouts": {
            "before_prompt_build": 90000,
            "agent_end": 60000
          }
        }
      }
    }
  }
}

​

Catálogo de hooks

• subagent_spawned / subagent_ended - observar el inicio y la finalización de subagentes.
• subagent_delivery_target - hook de compatibilidad para la entrega de finalización cuando ningún enlace de sesión del núcleo puede proyectar una ruta.
• subagent_spawning - hook de compatibilidad obsoleto. El núcleo ahora prepara enlaces de subagente thread: true mediante adaptadores de enlace de sesión de canal antes de que se dispare subagent_spawned.
• subagent_spawned incluye resolvedModel y resolvedProvider cuando OpenClaw ha resuelto el modelo nativo de la sesión hija antes del inicio.
• subagent_ended lleva targetSessionKey (identidad - coincide con subagent_spawned.childSessionKey), targetKind ("subagent" o "acp"), reason, outcome opcional ("ok", "error", "timeout", "killed", "reset" o "deleted"), error opcional, runId, endedAt, accountId y sendFarewell. No incluye agentId ni childSessionKey; usa targetSessionKey para correlacionarlo con el evento subagent_spawned correspondiente.

​

Solicitudes de emparejamiento de canal

api.on("channel_pairing_requested", async (event) => {
  await notifyOperator({
    text: `New ${event.channel} pairing request from ${event.senderId}: ${event.code}`,
  });
});

​

Hooks de runtime de depuración

​

Política de llamadas a herramientas

• event.toolName
• event.params
• event.toolKind y event.toolInputKind opcionales, discriminadores autoritativos del host para herramientas que comparten nombres de forma intencional; por ejemplo, las llamadas exec externas de modo código usan toolKind: "code_mode_exec" e incluyen toolInputKind: "javascript" | "typescript" cuando se conoce el lenguaje de entrada
• event.derivedPaths opcional, pistas de rutas de destino derivadas por el host con el mejor esfuerzo para envoltorios de herramientas conocidos como apply_patch; estas rutas pueden estar incompletas o sobreaproximar lo que la herramienta tocará realmente (por ejemplo, con entradas mal formadas o parciales)
• event.runId opcional
• event.toolCallId opcional
• campos de contexto como ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.toolKind, ctx.toolInputKind y ctx.trace de diagnóstico

type BeforeToolCallResult = {
  params?: Record<string, unknown>;
  block?: boolean;
  blockReason?: string;
  requireApproval?: {
    title: string;
    description: string;
    severity?: "info" | "warning" | "critical";
    timeoutMs?: number;
    timeoutBehavior?: "allow" | "deny";
    allowedDecisions?: Array<"allow-once" | "allow-always" | "deny">;
    pluginId?: string;
    onResolution?: (
      decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled",
    ) => Promise<void> | void;
  };
};

• block: true es terminal y omite los controladores de menor prioridad.
• block: false se trata como ausencia de decisión.
• params reescribe los parámetros de la herramienta para la ejecución.
• requireApproval pausa la ejecución del agente y pregunta al usuario mediante aprobaciones de Plugin. /approve puede aprobar tanto aprobaciones exec como de Plugin. En retransmisiones nativas PreToolUse de modo informe de app-server de Codex, esto se delega a la solicitud de aprobación correspondiente de app-server; consulta runtime del arnés de Codex.
• Un block: true de menor prioridad todavía puede bloquear después de que un hook de mayor prioridad haya solicitado aprobación.
• onResolution recibe la decisión resuelta: allow-once, allow-always, deny, timeout o cancelled.

​

Hook de entorno exec

• event.sessionKey
• event.toolName, actualmente siempre "exec"
• event.host, uno de "gateway", "sandbox" o "node"
• campos de contexto como ctx.agentId, ctx.sessionKey, ctx.messageProvider y ctx.channelId

​

Persistencia de resultados de herramientas

• OpenClaw elimina toolResult.details antes de la reproducción del proveedor y la entrada de Compaction para que los metadatos no se conviertan en contexto del modelo.
• Las entradas de sesión persistidas conservan solo details acotados. Los detalles sobredimensionados se reemplazan por un resumen compacto y persistedDetailsTruncated: true.
• tool_result_persist y before_message_write se ejecutan antes del límite final de persistencia. Mantén pequeños los details devueltos y evita colocar texto relevante para el prompt solo en details; coloca la salida de herramienta visible para el modelo en content.

​

Hooks de prompt y modelo

• before_model_resolve: recibe solo el prompt actual y los metadatos de adjuntos. Devuelve providerOverride o modelOverride.
• agent_turn_prepare: recibe el prompt actual, los mensajes de sesión preparados y cualquier inyección encolada de exactamente una vez drenada para esta sesión. Devuelve prependContext o appendContext.
• before_prompt_build: recibe el prompt actual y los mensajes de sesión. Devuelve prependContext, appendContext, systemPrompt, prependSystemContext o appendSystemContext.
• heartbeat_prompt_contribution: se ejecuta solo para turnos Heartbeat y devuelve prependContext o appendContext. Está pensado para monitores en segundo plano que necesitan resumir el estado actual sin cambiar turnos iniciados por el usuario.

• ctx.senderId: ID del remitente con ámbito de canal (por ejemplo, open_id de Feishu, ID de usuario de Discord). Se rellena cuando la ejecución se origina en un mensaje de usuario con metadatos de remitente conocidos.
• ctx.chatId: identificador de conversación nativo del transporte (por ejemplo, chat_id de Feishu, chat_id de Telegram). Se rellena cuando el canal de origen proporciona un ID de conversación nativo.
• ctx.channelContext.sender.id: el mismo ID de remitente que ctx.senderId, bajo un objeto propiedad del canal que los Plugins pueden ampliar con campos específicos del canal.
• ctx.channelContext.chat.id: el mismo ID de conversación que ctx.chatId, bajo un objeto propiedad del canal que los Plugins pueden ampliar con campos específicos del canal.

declare module "openclaw/plugin-sdk/channel-inbound" {
  interface PluginHookChannelSenderContext {
    unionId?: string;
    userId?: string;
  }
}

buildChannelInboundEventContext({
  // ...
  channelContext: {
    sender: { id: senderOpenId, unionId, userId },
    chat: { id: chatId },
  },
});

type BeforeAgentFinalizeRetry = {
  instruction: string;
  idempotencyKey?: string;
  maxAttempts?: number;
};

{
  "plugins": {
    "entries": {
      "my-plugin": {
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  }
}

​

Extensiones de sesión e inyecciones de siguiente turno

​

Hooks de mensajes

• message_received: observa contenido entrante, remitente, threadId, messageId, senderId, correlación opcional de ejecución/sesión y metadatos.
• message_sending: reescribe content o devuelve { cancel: true }.
• reply_payload_sending: reescribe objetos ReplyPayload normalizados (incluidos presentation, delivery, referencias de medios y texto) o devuelve { cancel: true }.
• message_sent: observa el éxito o fallo final.

• message_sending con cancel: true es terminal.
• message_sending con cancel: false se trata como sin decisión.
• El content reescrito continúa hacia hooks de menor prioridad salvo que un hook posterior cancele la entrega.
• reply_payload_sending se ejecuta después de la normalización de la carga útil y antes de la entrega del canal, incluidas las respuestas enrutadas de vuelta al canal de origen. Los manejadores se ejecutan secuencialmente y cada manejador ve la carga útil más reciente producida por manejadores de mayor prioridad.
• Las cargas útiles de reply_payload_sending no exponen marcadores de confianza del runtime como trustedLocalMedia; los plugins pueden editar la forma de la carga útil, pero no pueden conceder confianza a medios locales.
• message_sending puede devolver cancelReason y metadata acotados con una cancelación. Las nuevas API de ciclo de vida de mensajes exponen esto como un resultado de entrega suprimido con motivo cancelled_by_message_sending_hook; la entrega directa heredada sigue devolviendo una matriz de resultados vacía por compatibilidad.
• message_sent es solo de observación. Los fallos de manejadores se registran y no cambian el resultado de entrega.

​

Hooks de instalación

​

Ciclo de vida del Gateway

​

Próximas obsolescencias

• Sobres de canal en texto plano en manejadores inbound_claim y message_received. Lee BodyForAgent y los bloques estructurados de contexto de usuario en lugar de analizar texto de sobre plano. Consulta Sobres de canal en texto plano → BodyForAgent.
• before_agent_start permanece por compatibilidad. Los nuevos plugins deberían usar before_model_resolve y before_prompt_build en lugar de la fase combinada.
• subagent_spawning permanece por compatibilidad con plugins antiguos, pero los nuevos plugins no deberían devolver enrutamiento de hilos desde él. Core prepara vinculaciones de subagentes thread: true mediante adaptadores de vinculación de sesión de canal antes de que se dispare subagent_spawned.
• deactivate permanece como alias de compatibilidad de limpieza obsoleto hasta después del 2026-08-16. Los nuevos plugins deberían usar gateway_stop.
• onResolution en before_tool_call ahora usa la unión tipada PluginApprovalResolution (allow-once / allow-always / deny / timeout / cancelled) en lugar de un string de forma libre.
• api.registerSessionExtension / api.enqueueNextTurnInjection permanecen como alias de compatibilidad de nivel superior. Los nuevos plugins deberían usar api.session.state.registerSessionExtension(...) y api.session.workflow.enqueueNextTurnInjection(...).

​

Relacionado

• Migración del Plugin SDK - obsolescencias activas y cronograma de eliminación
• Crear plugins
• Descripción general del Plugin SDK
• Puntos de entrada de plugins
• Hooks internos
• Detalles internos de la arquitectura de plugins