हुक्स

Hooks छोटी स्क्रिप्ट होती हैं जो एजेंट इवेंट सक्रिय होने पर Gateway के भीतर चलती हैं: /new, /reset, /stop जैसे कमांड, सत्र Compaction, Gateway जीवनचक्र और संदेश प्रवाह। इन्हें डायरेक्टरी से खोजा जाता है और openclaw hooks से प्रबंधित किया जाता है। Gateway आंतरिक Hooks को तभी लोड करता है जब आप Hooks सक्षम करते हैं या कम-से-कम एक Hook प्रविष्टि, Hook पैक, लेगेसी हैंडलर या अतिरिक्त Hook डायरेक्टरी कॉन्फ़िगर करते हैं।

OpenClaw में दो प्रकार के Hooks होते हैं:

• आंतरिक Hooks (यह पृष्ठ): एजेंट इवेंट सक्रिय होने पर Gateway के भीतर चलते हैं।
• Webhooks: बाहरी HTTP एंडपॉइंट, जो अन्य सिस्टम को OpenClaw में कार्य ट्रिगर करने देते हैं। Webhooks देखें।

Hooks को Plugin के भीतर भी बंडल किया जा सकता है। openclaw hooks list स्वतंत्र Hooks और Plugin द्वारा प्रबंधित Hooks (जो plugin:<id> के रूप में दिखते हैं), दोनों दिखाता है।

सही सतह चुनें

OpenClaw में कई एक्सटेंशन सतहें हैं जो समान दिखती हैं, लेकिन अलग-अलग समस्याएँ हल करती हैं:

जब आप ऐसा ऑटोमेशन चाहते हैं जो किसी छोटे इंस्टॉल किए गए एकीकरण की तरह व्यवहार करे, तो आंतरिक Hooks का उपयोग करें। जब आपको रनटाइम जीवनचक्र नियंत्रण चाहिए, तो टाइप किए गए Plugin Hooks का उपयोग करें।

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

# उपलब्ध Hooks की सूची दिखाएँopenclaw hooks list # Hook सक्षम करेंopenclaw hooks enable session-memory # Hook की स्थिति जाँचेंopenclaw hooks check # विस्तृत जानकारी प्राप्त करेंopenclaw hooks info session-memory

इवेंट प्रकार

Hooks इस तालिका की किसी विशिष्ट कुंजी या केवल किसी फ़ैमिली नाम (command, session, agent, gateway, message) की सदस्यता लेते हैं, ताकि उस फ़ैमिली की प्रत्येक कार्रवाई प्राप्त कर सकें। OpenClaw कोर इसके अतिरिक्त कुछ भी उत्सर्जित नहीं करता, इसलिए कोई अन्य नाम लगभग हमेशा ऐसी टाइपिंग त्रुटि होता है जो Hook को बिना सूचना के निष्क्रिय छोड़ देता है (केवल कस्टम इवेंट उत्सर्जित करने वाला Plugin उसे सक्रिय कर सकता है)। Hook लोडर ऐसे नामों के लिए चेतावनी लॉग करता है (उदाहरण के लिए command:nwe), और openclaw hooks info <name> उन्हें चिह्नित करता है, इसलिए ऐसे Hook का निदान किया जा सकता है जो कभी नहीं चलता।

Hooks लिखना

Hook संरचना

प्रत्येक Hook ऐसी डायरेक्टरी है जिसमें दो फ़ाइलें होती हैं:

my-hook/├── HOOK.md          # मेटाडेटा + दस्तावेज़└── handler.ts       # हैंडलर कार्यान्वयन

हैंडलर फ़ाइल handler.ts, handler.js, index.ts या index.js हो सकती है।

HOOK.md प्रारूप

---name: my-hookdescription: "यह Hook क्या करता है, इसका संक्षिप्त विवरण"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # मेरा Hook विस्तृत दस्तावेज़ यहाँ दिए जाते हैं।

मेटाडेटा फ़ील्ड (metadata.openclaw):

हैंडलर कार्यान्वयन

const handler = async (event) => {  if (event.type !== "command" || event.action !== "new") {    return;  }   console.log(`[my-hook] नया कमांड ट्रिगर हुआ`);  // आपका लॉजिक यहाँ   // वैकल्पिक रूप से उत्तर देने योग्य सतहों पर उत्तर भेजें  event.messages.push("Hook निष्पादित हुआ!");}; export default handler;

प्रत्येक इवेंट में ये शामिल होते हैं: type, action, sessionKey, timestamp, messages और context (इवेंट-विशिष्ट डेटा)। एजेंट और टूल Hooks के लिए टाइप किए गए Plugin Hook संदर्भों में trace भी शामिल हो सकता है, जो केवल-पठन योग्य W3C-संगत डायग्नोस्टिक ट्रेस संदर्भ है और जिसे Plugin OTEL सहसंबंध के लिए संरचित लॉग में भेज सकते हैं।

event.messages में पुश की गई स्ट्रिंग केवल command:new और command:reset के लिए चैट में वापस भेजी जाती हैं (मूल वार्तालाप के उत्तर के रूप में रूट की जाती हैं) और session:compact:before / session:compact:after के लिए (Compaction स्थिति सूचनाओं के रूप में भेजी जाती हैं)। अन्य सभी इवेंट, जिनमें command:stop, message:*, agent:bootstrap, session:patch और gateway:* शामिल हैं, पुश किए गए संदेशों को अनदेखा करते हैं।

इवेंट संदर्भ की मुख्य बातें

कमांड इवेंट (command:new, command:reset): context.sessionEntry, context.previousSessionEntry, context.commandSource, context.senderId, context.workspaceDir, context.cfg।

कमांड इवेंट (command:stop): context.sessionEntry, context.sessionId, context.commandSource, context.senderId।

संदेश इवेंट (message:received): context.from, context.content, context.channelId, context.media (क्रमबद्ध चरणबद्ध अटैचमेंट तथ्य), जब रिमोट मीडिया अभी स्थानीय रूप से चरणबद्ध नहीं हुआ हो तब context.originalMedia के साथ context.mediaStagingPending, और context.metadata (प्रदाता-विशिष्ट डेटा, जिसमें senderId, senderName, guildId शामिल हैं)। कमांड-जैसे संदेशों के लिए context.content गैर-रिक्त कमांड बॉडी को प्राथमिकता देता है, फिर मूल इनबाउंड बॉडी और सामान्य बॉडी का उपयोग करता है; इसमें केवल एजेंट के लिए उपलब्ध संवर्धन, जैसे थ्रेड इतिहास या लिंक सारांश, शामिल नहीं होते। metadata के भीतर लेगेसी मीडिया उपनाम अप्रचलित हैं।

संदेश इवेंट (message:sent): context.to, context.content, context.success, context.channelId, और प्रेषण विफल होने पर context.error।

संदेश इवेंट (message:transcribed): context.transcript, context.from, context.channelId और context.media। context.mediaPath और context.mediaType पहले तथ्य के अप्रचलित उपनाम बने हुए हैं।

संदेश इवेंट (message:preprocessed): context.bodyForAgent (अंतिम संवर्धित बॉडी), context.from, context.channelId।

बूटस्ट्रैप इवेंट (agent:bootstrap): context.bootstrapFiles (परिवर्तनीय सरणी), context.agentId।

सत्र पैच इवेंट (session:patch): context.sessionEntry, context.patch (केवल बदले गए फ़ील्ड), context.cfg। केवल विशेषाधिकार प्राप्त क्लाइंट पैच इवेंट ट्रिगर कर सकते हैं; संदर्भ एक क्लोन है, इसलिए हैंडलर लाइव सत्र प्रविष्टि को बदल नहीं सकते।

Compaction इवेंट: session:compact:before में messageCount, tokenCount शामिल हैं। session:compact:after में compactedCount, summaryLength, tokensBefore, tokensAfter जोड़े जाते हैं।

command:stop उपयोगकर्ता द्वारा /stop जारी किए जाने का अवलोकन करता है; यह रद्दीकरण/कमांड जीवनचक्र है, एजेंट-अंतिमीकरण गेट नहीं। जिन Plugin को किसी स्वाभाविक अंतिम उत्तर का निरीक्षण करके एजेंट से एक और चरण माँगना हो, उन्हें इसके बजाय टाइप किए गए Plugin Hook before_agent_finalize का उपयोग करना चाहिए। Plugin Hooks देखें।

Gateway जीवनचक्र इवेंट: gateway:shutdown में reason और restartExpectedMs शामिल होते हैं और यह Gateway शटडाउन शुरू होने पर सक्रिय होता है। gateway:pre-restart में वही संदर्भ होता है, लेकिन यह केवल तभी सक्रिय होता है जब शटडाउन किसी अपेक्षित पुनरारंभ का भाग हो और एक सीमित restartExpectedMs मान दिया गया हो। शटडाउन के दौरान, प्रत्येक जीवनचक्र Hook प्रतीक्षा सर्वोत्तम-प्रयास और सीमित होती है, ताकि हैंडलर के अटकने पर भी शटडाउन जारी रहे। डिफ़ॉल्ट प्रतीक्षा बजट gateway:shutdown के लिए 5 सेकंड और gateway:pre-restart के लिए 10 सेकंड है।

चैनल उपलब्ध रहते समय छोटे पुनरारंभ नोटिस के लिए gateway:pre-restart का उपयोग करें:

  const execFileAsync = promisify(execFile); export default async function handler(event) {  if (event.type !== "gateway" || event.action !== "pre-restart") {    return;  }   const restartInSeconds = Math.ceil(event.context.restartExpectedMs / 1000);  await execFileAsync("openclaw", [    "system",    "event",    "--mode",    "now",    "--text",    `Gateway लगभग ${restartInSeconds} सेकंड में पुनरारंभ हो रहा है (${event.context.reason})। अभी चेकपॉइंट बनाएँ।`,  ]);}

gateway:shutdown (या gateway:pre-restart) इवेंट और शेष शटडाउन क्रम के बीच, Gateway हर उस सत्र के लिए एक टाइप किया हुआ session_end Plugin Hook भी सक्रिय करता है जो प्रक्रिया रुकने के समय अभी भी सक्रिय था। सामान्य SIGTERM/SIGINT रोक के लिए इवेंट का reason, shutdown होता है और जब बंद करना किसी अपेक्षित पुनरारंभ के भाग के रूप में निर्धारित किया गया हो तब restart होता है। यह निकासी सीमित होती है, ताकि धीमा session_end हैंडलर प्रक्रिया को समाप्त होने से न रोक सके, और दोबारा सक्रिय होने से बचाने के लिए उन सत्रों को छोड़ दिया जाता है जिन्हें replace / reset / delete / compaction के माध्यम से पहले ही अंतिम रूप दिया जा चुका है।

Hook खोज

Hooks चार स्रोतों से खोजे जाते हैं:

1. बंडल किए गए हुक: OpenClaw के साथ भेजे जाते हैं
2. Plugin हुक: इंस्टॉल किए गए plugins में बंडल किए जाते हैं; समान नाम वाले बंडल किए गए हुक को ओवरराइड कर सकते हैं
3. प्रबंधित हुक: ~/.openclaw/hooks/ (उपयोगकर्ता द्वारा इंस्टॉल किए गए, कार्यस्थानों में साझा); बंडल किए गए और Plugin हुक को ओवरराइड कर सकते हैं। hooks.internal.load.extraDirs से अतिरिक्त डायरेक्टरियों की भी यही प्राथमिकता है।
4. कार्यस्थान हुक: <workspace>/hooks/ (प्रति-एजेंट, स्पष्ट रूप से सक्षम किए जाने तक डिफ़ॉल्ट रूप से अक्षम)

कार्यस्थान हुक नए हुक नाम जोड़ सकते हैं, लेकिन समान नाम वाले बंडल किए गए, प्रबंधित या Plugin द्वारा प्रदान किए गए हुक को ओवरराइड नहीं कर सकते।

आंतरिक हुक कॉन्फ़िगर होने तक Gateway स्टार्टअप पर आंतरिक हुक खोज को छोड़ देता है। बंडल किए गए या प्रबंधित हुक को openclaw hooks enable <name> से सक्षम करें, हुक पैक इंस्टॉल करें या ऑप्ट इन करने के लिए hooks.internal.enabled=true सेट करें। जब आप किसी नामित हुक को सक्षम करते हैं, तो Gateway केवल उसी हुक का हैंडलर लोड करता है; hooks.internal.enabled=true, अतिरिक्त हुक डायरेक्टरियाँ और लीगेसी हैंडलर व्यापक खोज के लिए ऑप्ट इन करते हैं।

हुक पैक

हुक पैक ऐसे npm पैकेज हैं जो package.json में openclaw.hooks के माध्यम से हुक एक्सपोर्ट करते हैं। इससे इंस्टॉल करें:

openclaw plugins install <path-or-spec>

Npm स्पेक केवल रजिस्ट्री के लिए हैं (पैकेज नाम + वैकल्पिक सटीक वर्ज़न या dist-tag)। Git/URL/फ़ाइल स्पेक और semver रेंज अस्वीकार कर दी जाती हैं। पुराने openclaw hooks install और openclaw hooks update कमांड, openclaw plugins install / openclaw plugins update के अप्रचलित उपनाम हैं।

बंडल किए गए हुक

कोई भी बंडल किया गया हुक सक्षम करें:

openclaw hooks enable <hook-name>

session-memory का विवरण

अंतिम उपयोगकर्ता/सहायक संदेशों को निकालता है (डिफ़ॉल्ट 15, hooks.internal.entries.session-memory.messages से कॉन्फ़िगर करने योग्य) और होस्ट की स्थानीय तारीख का उपयोग करके उन्हें <workspace>/memory/YYYY-MM-DD-HHMM.md में सहेजता है। मेमोरी कैप्चर पृष्ठभूमि में चलता है, इसलिए ट्रांसक्रिप्ट पढ़ने या वैकल्पिक स्लग जनरेशन के कारण /new और /reset अभिस्वीकृतियों में देरी नहीं होती। वर्णनात्मक फ़ाइलनाम स्लग जनरेट करने के लिए hooks.internal.entries.session-memory.llmSlug: true सेट करें और वैकल्पिक रूप से hooks.internal.entries.session-memory.model को किसी कॉन्फ़िगर किए गए उपनाम जैसे sonnet, एजेंट के डिफ़ॉल्ट प्रदाता पर किसी मूल मॉडल ID या किसी provider/model संदर्भ पर सेट करें। model छोड़े जाने पर स्लग जनरेशन एजेंट के डिफ़ॉल्ट मॉडल का उपयोग करता है और अनुपलब्ध होने पर टाइमस्टैम्प स्लग का उपयोग करता है। workspace.dir का कॉन्फ़िगर होना आवश्यक है।

bootstrap-extra-files कॉन्फ़िगरेशन

{  "hooks": {    "internal": {      "entries": {        "bootstrap-extra-files": {          "enabled": true,          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]        }      }    }  }}

patterns और files को paths के उपनाम के रूप में स्वीकार किया जाता है। पथ कार्यस्थान के सापेक्ष हल किए जाते हैं और उन्हें उसके भीतर ही रहना चाहिए। केवल मान्य बूटस्ट्रैप बेसनाम लोड किए जाते हैं (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md)।

command-logger का विवरण

प्रत्येक स्लैश कमांड को JSON पंक्ति (टाइमस्टैम्प, कार्रवाई, सत्र कुंजी, प्रेषक ID, स्रोत) के रूप में ~/.openclaw/logs/commands.log में लॉग करता है।

compaction-notifier का विवरण

जब OpenClaw सत्र ट्रांसक्रिप्ट का Compaction शुरू और पूरा करता है, तब वर्तमान वार्तालाप में संक्षिप्त स्थिति संदेश भेजता है। इससे चैट सतहों पर लंबे टर्न कम भ्रमित करने वाले होते हैं, क्योंकि उपयोगकर्ता देख सकता है कि सहायक संदर्भ का सारांश बना रहा है और Compaction के बाद जारी रखेगा।

boot-md का विवरण

यदि फ़ाइल उस एजेंट के निर्धारित कार्यस्थान में मौजूद है, तो प्रत्येक कॉन्फ़िगर किए गए एजेंट स्कोप के लिए Gateway स्टार्टअप पर BOOT.md चलाता है।

Plugin हुक

Plugins अधिक गहन एकीकरण के लिए Plugin SDK के माध्यम से टाइप किए गए हुक पंजीकृत कर सकते हैं: टूल कॉल को इंटरसेप्ट करना, प्रॉम्प्ट संशोधित करना, संदेश प्रवाह नियंत्रित करना और बहुत कुछ। जब आपको before_tool_call, before_agent_reply, before_install या अन्य इन-प्रोसेस लाइफ़साइकल हुक की आवश्यकता हो, तब Plugin हुक का उपयोग करें।

Plugin द्वारा प्रबंधित आंतरिक हुक अलग होते हैं: वे इस पृष्ठ की स्थूल कमांड/लाइफ़साइकल इवेंट प्रणाली में भाग लेते हैं और openclaw hooks list में plugin:<id> के रूप में दिखाई देते हैं। उनका उपयोग साइड इफ़ेक्ट और हुक पैक के साथ संगतता के लिए करें, क्रमबद्ध मिडलवेयर या नीति गेट के लिए नहीं।

संपूर्ण Plugin हुक संदर्भ के लिए, Plugin हुक देखें।

कॉन्फ़िगरेशन

{  "hooks": {    "internal": {      "enabled": true,      "entries": {        "session-memory": { "enabled": true },        "command-logger": { "enabled": false }      }    }  }}

प्रति-हुक एनवायरनमेंट मान किसी हुक की requires.env पात्रता जाँच (प्रोसेस एनवायरनमेंट के साथ) को पूरा करते हैं, और हैंडलर उन्हें अपनी हुक कॉन्फ़िगरेशन प्रविष्टि से पढ़ सकते हैं:

{  "hooks": {    "internal": {      "entries": {        "my-hook": {          "enabled": true,          "env": { "MY_CUSTOM_VAR": "value" }        }      }    }  }}

अतिरिक्त हुक डायरेक्टरियाँ:

{  "hooks": {    "internal": {      "load": {        "extraDirs": ["/path/to/more/hooks"]      }    }  }}

CLI संदर्भ

# सभी हुक सूचीबद्ध करें (--eligible, --verbose या --json जोड़ें)openclaw hooks list # किसी हुक की विस्तृत जानकारी दिखाएँopenclaw hooks info <hook-name> # पात्रता सारांश दिखाएँopenclaw hooks check # सक्षम/अक्षम करेंopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

सर्वोत्तम अभ्यास

• हैंडलर तेज़ रखें। हुक कमांड प्रोसेसिंग के दौरान चलते हैं। void processInBackground(event) के साथ भारी कार्य को फ़ायर-एंड-फ़ॉरगेट करें।
• त्रुटियाँ सुचारु रूप से संभालें। जोखिमपूर्ण कार्रवाइयों को try/catch में रैप करें; त्रुटि थ्रो न करें, ताकि अन्य हैंडलर चल सकें।
• इवेंट को जल्दी फ़िल्टर करें। यदि इवेंट प्रकार/कार्रवाई प्रासंगिक नहीं है, तो तुरंत वापस लौटें।
• विशिष्ट इवेंट कुंजियों का उपयोग करें। ओवरहेड कम करने के लिए "events": ["command"] के बजाय "events": ["command:new"] को प्राथमिकता दें।

समस्या निवारण

हुक नहीं मिला

# डायरेक्टरी संरचना सत्यापित करेंls -la ~/.openclaw/hooks/my-hook/# यह दिखना चाहिए: HOOK.md, handler.ts # खोजे गए सभी हुक सूचीबद्ध करेंopenclaw hooks list

हुक पात्र नहीं है

openclaw hooks info my-hook

अनुपलब्ध बाइनरी (PATH), एनवायरनमेंट वेरिएबल, कॉन्फ़िगरेशन मान या OS संगतता की जाँच करें।

हुक निष्पादित नहीं हो रहा

1. सत्यापित करें कि हुक सक्षम है: openclaw hooks list
2. हुक फिर से लोड करने के लिए अपनी Gateway प्रोसेस पुनः आरंभ करें।
3. Gateway लॉग जाँचें: openclaw logs --follow | grep -i hook

संबंधित

• CLI संदर्भ: हुक
• Webhooks
• Plugin हुक — इन-प्रोसेस Plugin लाइफ़साइकल हुक
• कॉन्फ़िगरेशन