Plugin हुक्स

​

त्वरित शुरुआत

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 - पृष्ठभूमि मॉनिटर और लाइफसाइकल Plugin के लिए केवल-Heartbeat संदर्भ जोड़ें

• model_call_started / model_call_ended - प्रॉम्प्ट या प्रतिक्रिया सामग्री के बिना स्वच्छ किए गए प्रदाता/मॉडल कॉल मेटाडेटा, टाइमिंग, परिणाम, और सीमित अनुरोध-id हैश का अवलोकन करें
• llm_input - प्रदाता इनपुट (सिस्टम प्रॉम्प्ट, प्रॉम्प्ट, इतिहास) का अवलोकन करें
• llm_output - उपलब्ध होने पर प्रदाता आउटपुट, उपयोग, और हल किए गए contextTokenBudget का अवलोकन करें

• before_tool_call - टूल पैरामीटर फिर से लिखें, निष्पादन ब्लॉक करें, या स्वीकृति आवश्यक करें
• after_tool_call - टूल परिणामों, त्रुटियों, और अवधि का अवलोकन करें
• resolve_exec_env - exec में Plugin-स्वामित्व वाले पर्यावरण वेरिएबल योगदान करें
• 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 - अप्रचलित संगतता हुक। कोर अब subagent_spawned फायर होने से पहले चैनल सेशन-बाइंडिंग अडैप्टर के माध्यम से thread: true सबएजेंट बाइंडिंग तैयार करता है।
• 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 शामिल नहीं हैं; संबंधित subagent_spawned इवेंट से संबद्ध करने के लिए targetSessionKey का उपयोग करें।

• gateway_start / gateway_stop - Gateway के साथ Plugin-स्वामित्व वाली सेवाएं शुरू या बंद करें
• deactivate - gateway_stop के लिए अप्रचलित संगतता उपनाम; नए Plugin में gateway_stop का उपयोग करें
• cron_changed - Gateway-स्वामित्व वाले Cron लाइफसाइकल बदलावों (जोड़ा गया, अपडेट किया गया, हटाया गया, शुरू हुआ, समाप्त हुआ, शेड्यूल किया गया) का अवलोकन करें
• before_install - लोड किए गए Plugin रनटाइम से स्टेज की गई skill या Plugin इंस्टॉल सामग्री की जांच करें

​

डीबग रनटाइम हुक

​

टूल कॉल नीति

• event.toolName
• event.params
• वैकल्पिक event.toolKind और event.toolInputKind, ऐसे टूल के लिए होस्ट-प्रामाणिक डिस्क्रिमिनेटर जो जानबूझकर नाम साझा करते हैं; उदाहरण के लिए, बाहरी कोड-मोड exec कॉल toolKind: "code_mode_exec" का उपयोग करते हैं और इनपुट भाषा ज्ञात होने पर toolInputKind: "javascript" | "typescript" शामिल करते हैं
• वैकल्पिक event.derivedPaths, जिसमें 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 स्वीकृतियों, दोनों को स्वीकृत कर सकता है। Codex ऐप-सर्वर रिपोर्ट-मोड नेटिव PreToolUse रिले में, इसे मेल खाते ऐप-सर्वर स्वीकृति अनुरोध तक स्थगित किया जाता है; Codex हार्नेस रनटाइम देखें।
• किसी उच्च-प्राथमिकता हुक द्वारा स्वीकृति मांगे जाने के बाद भी कम-प्राथमिकता वाला 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

​

टूल परिणाम persistence

• OpenClaw provider replay और compaction input से पहले toolResult.details हटा देता है ताकि मेटाडेटा model context न बन जाए।
• Persisted session entries केवल bounded details रखती हैं। बहुत बड़े details को compact summary और persistedDetailsTruncated: true से बदल दिया जाता है।
• tool_result_persist और before_message_write अंतिम persistence cap से पहले चलते हैं। Hooks को फिर भी लौटाए गए details छोटे रखने चाहिए और prompt-relevant text को केवल details में रखने से बचना चाहिए; model-visible tool output को content में रखें।

​

Prompt और model hooks

• before_model_resolve: केवल वर्तमान prompt और attachment मेटाडेटा प्राप्त करता है। providerOverride या modelOverride लौटाएं।
• agent_turn_prepare: वर्तमान prompt, prepared session messages, और इस session के लिए drained की गई any exactly-once queued injections प्राप्त करता है। prependContext या appendContext लौटाएं।
• before_prompt_build: वर्तमान prompt और session messages प्राप्त करता है। prependContext, appendContext, systemPrompt, prependSystemContext, या appendSystemContext लौटाएं।
• heartbeat_prompt_contribution: केवल heartbeat turns के लिए चलता है और prependContext या appendContext लौटाता है। यह उन background monitors के लिए है जिन्हें user-initiated turns बदले बिना current state summarize करनी होती है।

• ctx.senderId — channel-scoped sender ID (जैसे Feishu open_id, Discord user ID)। तब populated होता है जब run known sender metadata वाले user message से originate होता है।
• ctx.chatId — transport-native conversation identifier (जैसे Feishu chat_id, Telegram chat_id)। तब populated होता है जब originating channel native conversation ID प्रदान करता है।
• ctx.channelContext.sender.id — ctx.senderId जैसा ही sender ID, ऐसे channel-owned object के अंतर्गत जिसे plugins channel-specific fields से extend कर सकते हैं।
• ctx.channelContext.chat.id — ctx.chatId जैसा ही conversation ID, ऐसे channel-owned object के अंतर्गत जिसे plugins channel-specific fields से extend कर सकते हैं।

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

​

Session extensions और next-turn injections

​

Message hooks

• message_received: inbound content, sender, threadId, messageId, senderId, optional run/session correlation, और metadata observe करें।
• message_sending: content rewrite करें या { cancel: true } लौटाएं।
• reply_payload_sending: normalized ReplyPayload objects (जिसमें presentation, delivery, media refs, और text शामिल हैं) rewrite करें या { cancel: true } लौटाएं।
• message_sent: final success या failure observe करें।

• cancel: true के साथ message_sending अंतिम है.
• cancel: false के साथ message_sending को कोई निर्णय नहीं माना जाता.
• फिर से लिखा गया content कम-प्राथमिकता वाले hooks तक जारी रहता है जब तक कोई बाद का hook वितरण रद्द नहीं कर देता.
• reply_payload_sending payload normalization के बाद और channel delivery से पहले चलता है, जिसमें originating channel पर वापस route किए गए replies भी शामिल हैं. Handlers क्रम से चलते हैं और प्रत्येक handler उच्च-प्राथमिकता वाले handlers द्वारा बनाए गए नवीनतम payload को देखता है.
• reply_payload_sending payloads runtime trust markers जैसे trustedLocalMedia को expose नहीं करते; plugins payload shape edit कर सकते हैं लेकिन local media trust grant नहीं कर सकते.
• message_sending cancellation के साथ cancelReason और सीमित metadata लौटा सकता है. नए message lifecycle APIs इसे reason cancelled_by_message_sending_hook के साथ suppressed delivery outcome के रूप में expose करते हैं; legacy direct delivery compatibility के लिए empty result array लौटाता रहता है.
• message_sent केवल observation के लिए है. Handler failures log किए जाते हैं और delivery result नहीं बदलते.

​

Install hooks

​

Gateway lifecycle

​

आगामी deprecations

• Plaintext channel envelopes inbound_claim और message_received handlers में. flat envelope text parse करने के बजाय BodyForAgent और structured user-context blocks पढ़ें. देखें Plaintext channel envelopes → BodyForAgent.
• before_agent_start compatibility के लिए रहता है. नए plugins को combined phase के बजाय before_model_resolve और before_prompt_build का उपयोग करना चाहिए.
• subagent_spawning पुराने plugins के साथ compatibility के लिए रहता है, लेकिन नए plugins को इससे thread routing return नहीं करनी चाहिए. Core subagent_spawned fire होने से पहले channel session-binding adapters के माध्यम से thread: true subagent bindings prepare करता है.
• deactivate 2026-08-16 के बाद तक deprecated cleanup compatibility alias के रूप में रहता है. नए plugins को gateway_stop का उपयोग करना चाहिए.
• onResolution in before_tool_call अब free-form string के बजाय typed PluginApprovalResolution union (allow-once / allow-always / deny / timeout / cancelled) का उपयोग करता है.

​

संबंधित

• Plugin SDK migration - active deprecations और removal timeline
• Building plugins
• Plugin SDK overview
• Plugin entry points
• Internal hooks
• Plugin architecture internals