Plugin hooks

​

Быстрый старт

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 },
    );
  },
});

• priority — порядок обработчиков (большее значение выполняется раньше).
• timeoutMs — необязательный бюджет на хук. Когда он задан, раннер хуков прерывает этот обработчик после истечения бюджета и продолжает со следующим, вместо того чтобы позволять медленной настройке или извлечению из памяти расходовать настроенный вызывающей стороной тайм-аут модели. Не указывайте его, чтобы использовать стандартный тайм-аут наблюдения/решения, который раннер хуков применяет обобщенно.

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

​

Каталог хуков

• before_model_resolve — переопределить провайдера или модель до загрузки сообщений сессии
• agent_turn_prepare — обработать поставленные в очередь вставки хода Plugin и добавить контекст того же хода перед хуками промпта
• before_prompt_build — добавить динамический контекст или текст системного промпта перед вызовом модели
• before_agent_start — объединенная фаза только для совместимости; предпочитайте два хука выше
• before_agent_run — проверить финальный промпт и сообщения сессии перед отправкой в модель и при необходимости заблокировать запуск
• before_agent_reply — досрочно завершить ход модели синтетическим ответом или молчанием
• before_agent_finalize — проверить естественный финальный ответ и запросить еще один проход модели
• agent_end — наблюдать финальные сообщения, состояние успеха и длительность запуска
• heartbeat_prompt_contribution — добавить контекст только для Heartbeat для фонового монитора и Plugin’ов жизненного цикла

• model_call_started / model_call_ended — наблюдать очищенные метаданные вызова провайдера/модели, тайминг, результат и ограниченные хэши идентификатора запроса без содержимого промпта или ответа
• llm_input — наблюдать вход провайдера (системный промпт, промпт, историю)
• llm_output — наблюдать выход провайдера, использование и разрешенный contextTokenBudget, когда он доступен

• before_tool_call — переписать параметры инструмента, заблокировать выполнение или запросить подтверждение
• after_tool_call — наблюдать результаты инструмента, ошибки и длительность
• resolve_exec_env — добавить переменные окружения, принадлежащие Plugin, в exec
• tool_result_persist — переписать сообщение ассистента, созданное из результата инструмента
• before_message_write — проверить или заблокировать выполняющуюся запись сообщения (редко)

• inbound_claim — забрать входящее сообщение до маршрутизации агенту (синтетические ответы)
• message_received — наблюдать входящее содержимое, отправителя, поток и метаданные
• message_sending — переписать исходящее содержимое или отменить доставку
• reply_payload_sending — изменить или отменить нормализованную полезную нагрузку ответа перед доставкой
• message_sent — наблюдать успех или сбой исходящей доставки
• before_dispatch — проверить или переписать исходящую отправку перед передачей каналу
• reply_dispatch — участвовать в финальном конвейере отправки ответа

• session_start / session_end — отслеживать границы жизненного цикла сессии. reason события имеет одно из значений: new, reset, idle, daily, compaction, deleted, shutdown, restart или unknown. Значения shutdown и restart срабатывают из финализатора завершения Gateway, когда процесс остановлен или перезапущен, пока сессии еще активны, чтобы нижестоящие Plugin’ы (например, хранилища памяти или расшифровок) могли финализировать призрачные строки, которые иначе остались бы в открытом состоянии между перезапусками. Финализатор ограничен по времени, поэтому медленный Plugin не может заблокировать SIGTERM/SIGINT.
• before_compaction / after_compaction — наблюдать или аннотировать циклы Compaction
• before_reset — наблюдать события сброса сессии (/reset, программные сбросы)

• subagent_spawned / subagent_ended — наблюдать запуск и завершение субагента.
• subagent_delivery_target — хук совместимости для доставки завершения, когда базовая привязка сессии ядра не может спроецировать маршрут.
• subagent_spawning — устаревший хук совместимости. Теперь ядро подготавливает привязки субагентов thread: true через адаптеры привязки сессий каналов до срабатывания subagent_spawned.
• subagent_spawned включает resolvedModel и resolvedProvider, когда OpenClaw разрешил нативную модель дочерней сессии перед запуском.
• subagent_ended несет targetSessionKey (идентичность — это соответствует subagent_spawned.childSessionKey), targetKind ("subagent" или "acp"), reason, необязательный outcome ("ok", "error", "timeout", "killed", "reset" или "deleted"), необязательные error, runId, endedAt, accountId и sendFarewell. Он не включает agentId или childSessionKey; используйте targetSessionKey, чтобы сопоставить его с соответствующим событием subagent_spawned.

• gateway_start / gateway_stop — запускать или останавливать сервисы, принадлежащие Plugin, вместе с Gateway
• deactivate — устаревший псевдоним совместимости для gateway_stop; используйте gateway_stop в новых Plugin’ах
• cron_changed — наблюдать изменения жизненного цикла Cron, принадлежащего Gateway (добавлен, обновлен, удален, запущен, завершен, запланирован)
• before_install — проверить подготовленные материалы установки Skills или Plugin из загруженного рантайма Plugin

​

Отладка хуков рантайма

​

Политика вызовов инструментов

• event.toolName
• event.params
• необязательные event.toolKind и event.toolInputKind — авторитетные со стороны хоста дискриминаторы для инструментов, которые намеренно имеют общие имена; например, внешние вызовы exec в режиме кода используют toolKind: "code_mode_exec" и включают toolInputKind: "javascript" | "typescript", когда язык входных данных известен
• необязательный event.derivedPaths, содержащий best-effort подсказки целевых путей, выведенные хостом, для известных оболочек инструментов, таких как apply_patch; при наличии эти пути могут быть неполными или могут завышать то, чего инструмент фактически коснется (например, при некорректных или частичных входных данных)
• необязательный event.runId
• необязательный event.toolCallId
• поля контекста, такие как ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (задается для запусков, управляемых Cron), ctx.toolKind, ctx.toolInputKind и диагностический ctx.trace

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 является терминальным и пропускает обработчики с более низким приоритетом.
• block: false трактуется как отсутствие решения.
• params переписывает параметры инструмента для выполнения.
• requireApproval приостанавливает запуск агента и запрашивает пользователя через подтверждения Plugin. Команда /approve может подтверждать как exec, так и подтверждения Plugin. В нативных ретрансляциях PreToolUse режима отчета app-server Codex это откладывается до соответствующего запроса подтверждения app-server; см. рантайм Codex harness.
• block: true с более низким приоритетом все еще может заблокировать после того, как хук с более высоким приоритетом запросил подтверждение.
• onResolution получает разрешенное решение подтверждения — allow-once, allow-always, deny, timeout или cancelled.

​

Хук окружения Exec

• event.sessionKey
• event.toolName, сейчас всегда "exec"
• event.host, одно из "gateway", "sandbox" или "node"
• поля контекста, такие как ctx.agentId, ctx.sessionKey, ctx.messageProvider и ctx.channelId

​

Сохранение результатов инструментов

• OpenClaw удаляет toolResult.details перед повторным воспроизведением у провайдера и входом Compaction, чтобы метаданные не стали контекстом модели.
• Сохраненные записи сессий хранят только ограниченные details. Слишком большие details заменяются компактной сводкой и persistedDetailsTruncated: true.
• tool_result_persist и before_message_write выполняются до финального ограничения сохранения. Hooks все равно должны держать возвращаемые details небольшими и не размещать текст, важный для промпта, только в details; видимый модели вывод инструмента помещайте в content.

​

Hooks промпта и модели

• before_model_resolve: получает только текущий промпт и метаданные вложений. Возвращайте providerOverride или modelOverride.
• agent_turn_prepare: получает текущий промпт, подготовленные сообщения сессии и все поставленные в очередь для этой сессии внедрения, которые должны быть обработаны ровно один раз и уже извлечены. Возвращайте prependContext или appendContext.
• before_prompt_build: получает текущий промпт и сообщения сессии. Возвращайте prependContext, appendContext, systemPrompt, prependSystemContext или appendSystemContext.
• heartbeat_prompt_contribution: выполняется только для ходов Heartbeat и возвращает prependContext или appendContext. Он предназначен для фоновых мониторов, которым нужно суммировать текущее состояние, не изменяя ходы, инициированные пользователем.

• ctx.senderId — ограниченный каналом ID отправителя (например, Feishu open_id, ID пользователя Discord). Заполняется, когда запуск исходит из пользовательского сообщения с известными метаданными отправителя.
• ctx.chatId — транспортно-нативный идентификатор беседы (например, Feishu chat_id, Telegram chat_id). Заполняется, когда исходный канал предоставляет нативный ID беседы.
• ctx.channelContext.sender.id — тот же ID отправителя, что и ctx.senderId, под объектом, принадлежащим каналу, который plugins могут расширять специфичными для канала полями.
• ctx.channelContext.chat.id — тот же ID беседы, что и ctx.chatId, под объектом, принадлежащим каналу, который plugins могут расширять специфичными для канала полями.

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
        }
      }
    }
  }
}

​

Расширения сессии и внедрения следующего хода

​

Hooks сообщений

• message_received: наблюдает входящий контент, отправителя, threadId, messageId, senderId, необязательную корреляцию run/session и метаданные.
• message_sending: переписывает content или возвращает { cancel: true }.
• reply_payload_sending: переписывает нормализованные объекты ReplyPayload (включая presentation, delivery, media refs и text) или возвращает { cancel: true }.
• message_sent: наблюдает финальный успех или сбой.

• message_sending с cancel: true является терминальным.
• message_sending с cancel: false трактуется как отсутствие решения.
• Переписанное content продолжает передаваться хукам с более низким приоритетом, если последующий хук не отменит доставку.
• reply_payload_sending выполняется после нормализации полезной нагрузки и перед доставкой в канал, включая ответы, направляемые обратно в исходный канал. Обработчики выполняются последовательно, и каждый обработчик видит последнюю полезную нагрузку, созданную обработчиками с более высоким приоритетом.
• Полезные нагрузки reply_payload_sending не раскрывают маркеры доверия времени выполнения, такие как trustedLocalMedia; плагины могут изменять форму полезной нагрузки, но не могут предоставлять доверие к локальным медиа.
• message_sending может возвращать cancelReason и ограниченные metadata вместе с отменой. Новые API жизненного цикла сообщений раскрывают это как результат подавленной доставки с причиной cancelled_by_message_sending_hook; устаревшая прямая доставка для совместимости продолжает возвращать пустой массив результатов.
• message_sent предназначен только для наблюдения. Сбои обработчиков логируются и не изменяют результат доставки.

​

Хуки установки

​

Жизненный цикл Gateway

​

Предстоящие устаревания

• Текстовые конверты каналов в обработчиках inbound_claim и message_received. Читайте BodyForAgent и структурированные блоки пользовательского контекста вместо разбора плоского текста конверта. См. Текстовые конверты каналов → BodyForAgent.
• before_agent_start остается для совместимости. Новым плагинам следует использовать before_model_resolve и before_prompt_build вместо объединенной фазы.
• subagent_spawning остается для совместимости со старыми плагинами, но новым плагинам не следует возвращать из него маршрутизацию потоков. Ядро подготавливает привязки подагентов thread: true через адаптеры привязки сессий каналов до срабатывания subagent_spawned.
• deactivate остается устаревшим совместимым псевдонимом очистки до после 2026-08-16. Новым плагинам следует использовать gateway_stop.
• onResolution в before_tool_call теперь использует типизированное объединение PluginApprovalResolution (allow-once / allow-always / deny / timeout / cancelled) вместо свободного string.

​

Связанные материалы

• Миграция Plugin SDK - активные устаревания и график удаления
• Создание плагинов
• Обзор Plugin SDK
• Точки входа Plugin
• Внутренние хуки
• Внутренняя архитектура Plugin