Хуки Plugin

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Швидкий старт

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 - спожити поставлені в чергу ін’єкції ходу плагіна й додати контекст того самого ходу перед хуками запиту
• before_prompt_build - додати динамічний контекст або текст системного запиту перед викликом моделі
• before_agent_start - комбінована фаза лише для сумісності; надавайте перевагу двом хукам вище
• before_agent_run - перевірити фінальний запит і повідомлення сесії перед надсиланням моделі та за потреби заблокувати запуск
• before_agent_reply - перервати хід моделі синтетичною відповіддю або тишею
• before_agent_finalize - перевірити природну фінальну відповідь і запросити ще один прохід моделі
• agent_end - спостерігати фінальні повідомлення, стан успіху та тривалість запуску
• heartbeat_prompt_contribution - додати контекст лише для Heartbeat для фонових моніторів і плагінів життєвого циклу

• model_call_started / model_call_ended - спостерігати санітизовані метадані виклику провайдера/моделі, час, результат і обмежені хеші ідентифікаторів запитів без вмісту запиту чи відповіді
• llm_input - спостерігати вхідні дані провайдера (системний запит, запит, історія)
• llm_output - спостерігати вихідні дані провайдера

• before_tool_call - переписати параметри інструмента, заблокувати виконання або вимагати схвалення
• after_tool_call - спостерігати результати інструмента, помилки й тривалість
• tool_result_persist - переписати повідомлення асистента, створене з результату інструмента
• before_message_write - перевірити або заблокувати запис повідомлення, що виконується (рідко)

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

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

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended - координувати маршрутизацію субагентів і доставлення завершення

• gateway_start / gateway_stop - запускати або зупиняти сервіси, що належать плагіну, разом із Gateway
• cron_changed - спостерігати зміни життєвого циклу Cron, що належать Gateway (додано, оновлено, видалено, запущено, завершено, заплановано)
• before_install - перевірити сканування встановлення навички або плагіна та за потреби заблокувати

​

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

• event.toolName
• event.params
• необов’язкове event.derivedPaths, що містить найкращі можливі підказки цільових шляхів, отримані від хоста, для добре відомих оболонок інструментів, як-от apply_patch; коли вони присутні, ці шляхи можуть бути неповними або можуть надмірно приблизно описувати те, чого інструмент фактично торкнеться (наприклад, із некоректними або частковими вхідними даними)
• необов’язкове event.runId
• необов’язкове event.toolCallId
• поля контексту, як-от ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (задається для запусків, керованих Cron), і діагностичне 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";
    pluginId?: string;
    onResolution?: (
      decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled",
    ) => Promise<void> | void;
  };
};

• block: true є термінальним і пропускає обробники з нижчим пріоритетом.
• block: false трактується як відсутність рішення.
• params переписує параметри інструмента для виконання.
• requireApproval призупиняє запуск агента й запитує користувача через схвалення плагінів. Команда /approve може схвалювати як exec, так і схвалення плагінів.
• block: true з нижчим пріоритетом усе ще може заблокувати після того, як хук із вищим пріоритетом запросив схвалення.
• onResolution отримує розв’язане рішення схвалення - allow-once, allow-always, deny, timeout або cancelled.

​

Збереження результатів інструментів

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

​

Хуки запитів і моделі

• before_model_resolve: отримує лише поточний запит і метадані вкладень. Повертає providerOverride або modelOverride.
• agent_turn_prepare: отримує поточний запит, підготовлені повідомлення сесії та будь-які одноразові поставлені в чергу ін’єкції, вилучені для цієї сесії. Повертає prependContext або appendContext.
• before_prompt_build: отримує поточний запит і повідомлення сесії. Повертає prependContext, appendContext, systemPrompt, prependSystemContext або appendSystemContext.
• heartbeat_prompt_contribution: виконується лише для ходів Heartbeat і повертає prependContext або appendContext. Він призначений для фонових моніторів, яким потрібно підсумовувати поточний стан, не змінюючи ходи, ініційовані користувачем.

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

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

​

Розширення сесії та ін’єкції наступного turn

​

Хуки повідомлень

• message_received: спостерігає вхідний вміст, відправника, threadId, messageId, senderId, необов’язкову кореляцію run/session і метадані.
• message_sending: переписує content або повертає { cancel: true }.
• message_sent: спостерігає фінальний успіх або помилку.

• message_sending з cancel: true є terminal.
• message_sending з cancel: false вважається відсутністю рішення.
• Переписаний content продовжує передаватися хукам нижчого пріоритету, якщо пізніший хук не скасує доставлення.
• message_sending може повернути cancelReason і обмежені metadata разом зі скасуванням. Нові API життєвого циклу повідомлень показують це як suppressed результат доставлення з причиною cancelled_by_message_sending_hook; legacy direct delivery і надалі повертає порожній масив результатів для сумісності.
• message_sent призначений лише для спостереження. Помилки handler логуються й не змінюють результат доставлення.

​

Хуки встановлення

​

Життєвий цикл Gateway

​

Майбутні припинення підтримки

• Plaintext channel envelopes у handler inbound_claim і message_received. Читайте BodyForAgent і структуровані блоки user-context замість parsing flat envelope text. Див. Plaintext channel envelopes → BodyForAgent.
• before_agent_start зберігається для сумісності. Нові plugins мають використовувати before_model_resolve і before_prompt_build замість combined phase.
• onResolution у before_tool_call тепер використовує typed union PluginApprovalResolution (allow-once / allow-always / deny / timeout / cancelled) замість free-form string.

​

Пов’язане

• Міграція Plugin SDK - активні припинення підтримки та графік видалення
• Створення plugins
• Огляд Plugin SDK
• Точки входу Plugin
• Внутрішні хуки
• Внутрішня архітектура Plugin