Hooks de Plugin

​

Início 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,
          },
        };
      },
      { 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 - observam a inicialização e a conclusão de subagentes.
• subagent_delivery_target - hook de compatibilidade para entrega de conclusão quando nenhum vínculo de sessão do núcleo consegue projetar uma rota.
• subagent_spawning - hook de compatibilidade obsoleto. Agora, o núcleo prepara vínculos de subagentes com thread: true por meio de adaptadores de vínculo de sessão do canal antes que subagent_spawned seja disparado.
• subagent_spawned inclui resolvedModel e resolvedProvider quando o OpenClaw resolve o modelo nativo da sessão filha antes da inicialização.
• subagent_ended contém targetSessionKey (identidade — corresponde a subagent_spawned.childSessionKey), targetKind ("subagent" ou "acp"), reason, outcome opcional ("ok", "error", "timeout", "killed", "reset" ou "deleted"), error opcional, runId, endedAt, accountId e sendFarewell. Ele não inclui agentId nem childSessionKey; use targetSessionKey para correlacioná-lo com o evento subagent_spawned correspondente.

​

Solicitações de pareamento de canais

api.on("channel_pairing_requested", async (event) => {
  await notifyOperator({
    text: `Nova solicitação de pareamento de ${event.channel} de ${event.senderId}: ${event.code}`,
  });
});

​

Hooks de depuração do runtime

​

Política de chamadas de ferramentas

• event.toolName
• event.params
• event.toolKind e event.toolInputKind opcionais, discriminadores definidos de forma autoritativa pelo host para ferramentas que compartilham nomes intencionalmente; por exemplo, chamadas externas de exec no modo de código usam toolKind: "code_mode_exec" e incluem toolInputKind: "javascript" | "typescript" quando a linguagem da entrada é conhecida
• event.derivedPaths opcional, dicas de caminhos de destino derivadas pelo host em caráter de melhor esforço para envelopes de ferramentas conhecidos, como apply_patch; esses caminhos podem estar incompletos ou superestimar o que a ferramenta realmente modificará (por exemplo, com entradas malformadas ou parciais)
• event.runId opcional
• event.toolCallId opcional
• campos de contexto como ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.toolKind, ctx.toolInputKind e o diagnóstico ctx.trace

type BeforeToolCallResult = {
  params?: Record<string, unknown>;
  block?: boolean;
  blockReason?: string;
  requireApproval?: {
    title: string;
    description: string;
    severity?: "info" | "warning" | "critical";
    timeoutMs?: number;
    /** @deprecated Aprovações não resolvidas sempre negam. */
    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 é terminal e ignora manipuladores de prioridade inferior.
• block: false é tratado como ausência de decisão.
• params reescreve os parâmetros da ferramenta para execução.
• requireApproval pausa a execução do agente e solicita confirmação ao usuário por meio das aprovações do plugin. /approve pode aprovar tanto aprovações de exec quanto do plugin. Em retransmissões nativas de PreToolUse no modo de relatório do app-server do Codex, isso delega à solicitação de aprovação correspondente do app-server; consulte Runtime do harness do Codex.
• Um block: true de prioridade inferior ainda pode bloquear depois que um hook de prioridade superior solicitar aprovação.
• onResolution recebe a decisão resolvida: allow-once, allow-always, deny, timeout ou cancelled.

​

Hook do ambiente de exec

• event.sessionKey
• event.toolName, atualmente sempre "exec"
• event.host, um entre "gateway", "sandbox" ou "node"
• campos de contexto como ctx.agentId, ctx.sessionKey, ctx.messageProvider e ctx.channelId

​

Persistência dos resultados de ferramentas

• O OpenClaw remove toolResult.details antes da reprodução para o provedor e da entrada de Compaction, para que os metadados não se tornem contexto do modelo.
• Entradas persistidas da sessão mantêm somente details limitados. Detalhes grandes demais são substituídos por um resumo compacto e persistedDetailsTruncated: true.
• tool_result_persist e before_message_write são executados antes do limite final de persistência. Mantenha os details retornados pequenos e evite colocar texto relevante para o prompt somente em details; coloque a saída da ferramenta visível ao modelo em content.

​

Hooks de prompt e modelo

• before_model_resolve: recebe somente o prompt atual e os metadados dos anexos. Retorne providerOverride ou modelOverride.
• agent_turn_prepare: recebe o prompt atual, as mensagens preparadas da sessão e quaisquer injeções enfileiradas de execução única consumidas para esta sessão. Retorne prependContext ou appendContext.
• before_prompt_build: recebe o prompt atual e as mensagens da sessão. Retorne prependContext, appendContext, systemPrompt, prependSystemContext ou appendSystemContext.
• heartbeat_prompt_contribution: é executado somente em turnos de Heartbeat e retorna prependContext ou appendContext. Destina-se a monitores em segundo plano que precisam resumir o estado atual sem alterar turnos iniciados pelo usuário.

• ctx.senderId — ID do remetente no escopo do canal (por exemplo, open_id do Feishu, ID de usuário do Discord). Preenchido quando a execução se origina de uma mensagem de usuário com metadados conhecidos do remetente.
• ctx.chatId — identificador de conversa nativo do transporte (por exemplo, chat_id do Feishu, chat_id do Telegram). Preenchido quando o canal de origem fornece um ID de conversa nativo.
• ctx.channelContext.sender.id — o mesmo ID do remetente que ctx.senderId, dentro de um objeto pertencente ao canal que os plugins podem estender com campos específicos do canal.
• ctx.channelContext.chat.id — o mesmo ID de conversa que ctx.chatId, dentro de um objeto pertencente ao canal que os plugins podem estender com campos específicos do 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
        }
      }
    }
  }
}

​

Extensões de sessão e injeções no próximo turno

​

Hooks de mensagem

• message_received: observa o conteúdo recebido, o remetente, threadId, messageId, senderId, a correlação opcional de execução/sessão e os metadados.
• message_sending: reescreve content ou retorna { cancel: true }.
• reply_payload_sending: reescreve objetos ReplyPayload normalizados (incluindo presentation, delivery, referências de mídia e texto) ou retorna { cancel: true }.
• message_sent: observa o sucesso ou a falha final.

• message_sending com cancel: true é terminal.
• message_sending com cancel: false é tratado como ausência de decisão.
• O content reescrito continua para hooks de prioridade inferior, a menos que um hook posterior cancele a entrega.
• reply_payload_sending é executado após a normalização do payload e antes da entrega pelo canal, incluindo respostas roteadas de volta ao canal de origem. Os manipuladores são executados sequencialmente, e cada manipulador vê o payload mais recente produzido pelos manipuladores de prioridade superior.
• Os payloads de reply_payload_sending não expõem marcadores de confiança do runtime, como trustedLocalMedia; os plugins podem editar a estrutura do payload, mas não podem conceder confiança à mídia local.
• message_sending pode retornar cancelReason e metadata limitados com um cancelamento. Novas APIs do ciclo de vida de mensagens expõem isso como um resultado de entrega suprimida com o motivo cancelled_by_message_sending_hook; a entrega direta legada continua retornando uma matriz de resultados vazia por compatibilidade.
• message_sent serve apenas para observação. Falhas dos manipuladores são registradas e não alteram o resultado da entrega.

​

Hooks de instalação

​

Ciclo de vida do Gateway

​

Projeção Cron externa segura

import { setTimeout as sleep } from "node:timers/promises";
import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";

type ExternalWake = { jobId: string; runAtMs: number };

type ExternalWakeHost = {
  replaceAll(wakes: readonly ExternalWake[], options: { signal: AbortSignal }): Promise<void>;
  close(): Promise<void>;
};

type CronReader = {
  list(options: { includeDisabled: true }): Promise<
    Array<{
      id: string;
      enabled?: boolean;
      state?: { nextRunAtMs?: number };
    }>
  >;
};

export function registerCronProjection(api: OpenClawPluginApi, host: ExternalWakeHost) {
  const lifecycle = new AbortController();
  let cron: CronReader | undefined;
  let enabled = false;
  let hasBaseline = false;
  let reconciliationSignal: AbortSignal | undefined;
  let requestedRevision = 0;
  let appliedRevision = 0;
  let worker = Promise.resolve();
  let activeAttempt: AbortController | undefined;

  const projectLatest = async () => {
    let retryMs = 1_000;

    while (!lifecycle.signal.aborted && appliedRevision < requestedRevision) {
      const ownerSignal = reconciliationSignal;
      if (!ownerSignal || ownerSignal.aborted) {
        return;
      }
      const targetRevision = requestedRevision;
      const attempt = new AbortController();
      const signal = AbortSignal.any([lifecycle.signal, ownerSignal, attempt.signal]);
      activeAttempt = attempt;

      try {
        const jobs = enabled && cron ? await cron.list({ includeDisabled: true }) : [];
        if (signal.aborted || targetRevision !== requestedRevision) {
          continue;
        }
        const wakes = jobs
          .flatMap((job): ExternalWake[] => {
            const runAtMs = job.enabled === false ? undefined : job.state?.nextRunAtMs;
            return runAtMs === undefined ? [] : [{ jobId: job.id, runAtMs }];
          })
          .sort((a, b) => a.runAtMs - b.runAtMs || a.jobId.localeCompare(b.jobId));

        await host.replaceAll(wakes, { signal });
        if (signal.aborted || targetRevision !== requestedRevision) {
          continue;
        }
        appliedRevision = targetRevision;
        retryMs = 1_000;
      } catch {
        if (lifecycle.signal.aborted || ownerSignal.aborted) {
          return;
        }
        if (attempt.signal.aborted) {
          continue;
        }
        api.logger.warn(`external cron projection failed; retrying in ${retryMs}ms`);
        try {
          await sleep(retryMs, undefined, { signal });
        } catch {
          if (lifecycle.signal.aborted) {
            return;
          }
          if (attempt.signal.aborted) {
            continue;
          }
        }
        retryMs = Math.min(retryMs * 2, 30_000);
      } finally {
        if (activeAttempt === attempt) {
          activeAttempt = undefined;
        }
      }
    }
  };

  const requestProjection = () => {
    const targetRevision = ++requestedRevision;
    activeAttempt?.abort();
    worker = worker.then(async () => {
      if (!lifecycle.signal.aborted && appliedRevision < targetRevision) {
        await projectLatest();
      }
    });
    return worker;
  };

  api.on("cron_reconciled", (event, ctx) => {
    const reconciledCron = ctx.getCron?.();
    if (event.enabled && !reconciledCron) {
      api.logger.warn("cron reconciliation did not expose a scheduler");
      return;
    }
    cron = reconciledCron;
    enabled = event.enabled;
    hasBaseline = true;
    reconciliationSignal = ctx.abortSignal;
    return requestProjection();
  });

  api.on("cron_changed", () => {
    if (hasBaseline) {
      return requestProjection();
    }
  });

  api.on("gateway_stop", async () => {
    lifecycle.abort();
    await worker;
    await host.close();
  });
}

​

Próximas descontinuações

• Envelopes de canal em texto simples nos manipuladores inbound_claim e message_received. Leia BodyForAgent e os blocos estruturados de contexto do usuário em vez de analisar o texto simples do envelope. Consulte Envelopes de canal em texto simples → BodyForAgent.
• before_agent_start permanece por compatibilidade. Novos plugins devem usar before_model_resolve e before_prompt_build em vez da fase combinada.
• subagent_spawning permanece por compatibilidade com plugins mais antigos, mas novos plugins não devem retornar o roteamento de threads por meio dele. O núcleo prepara as associações de subagentes com thread: true por meio dos adaptadores de associação de sessão do canal antes que subagent_spawned seja disparado.
• deactivate permanece como um alias de compatibilidade obsoleto para limpeza até depois de 2026-08-16. Novos plugins devem usar gateway_stop.
• onResolution em before_tool_call agora usa a união tipada PluginApprovalResolution (allow-once / allow-always / deny / timeout / cancelled) em vez de uma string de formato livre.
• api.registerSessionExtension / api.enqueueNextTurnInjection permanecem como aliases de compatibilidade de nível superior. Novos plugins devem usar api.session.state.registerSessionExtension(...) e api.session.workflow.enqueueNextTurnInjection(...).

​

Relacionados

• Migração do SDK de Plugin - descontinuações ativas e cronograma de remoção
• Criação de plugins
• Visão geral do SDK de Plugin
• Pontos de entrada de plugins
• Hooks internos
• Detalhes internos da arquitetura de plugins