Building plugins

Plugin अनुमति अनुरोध

Plugin अनुमति अनुरोध Plugin कोड को किसी टूल कॉल या Plugin-स्वामित्व वाले ऑपरेशन को तब तक रोकने देते हैं, जब तक उपयोगकर्ता उसे स्वीकृत या अस्वीकृत नहीं कर देता। वे Gateway plugin.approval.* प्रवाह और उन्हीं स्वीकृति UI सतहों का उपयोग करते हैं जो चैट स्वीकृति बटन और /approve कमांड संभालती हैं।

Plugin/ऐप अनुमतियों के लिए Plugin अनुमति अनुरोधों का उपयोग करें। वे होस्ट exec स्वीकृतियों, वैकल्पिक टूल अनुमति-सूचियों या Codex की मूल अनुमति समीक्षा को प्रतिस्थापित नहीं करते।

सही गेट चुनें

अपनी आवश्यक निर्णय-बिंदु से मेल खाने वाला गेट चुनें:

गेट	इसका उपयोग कब करें	यह क्या नियंत्रित करता है
वैकल्पिक टूल	उपयोगकर्ता के ऑप्ट इन करने तक कोई टूल मॉडल को दिखाई नहीं देना चाहिए।	`tools.allow` के माध्यम से टूल का प्रदर्शन।
Plugin अनुमति अनुरोध	किसी Plugin हुक या Plugin-स्वामित्व वाले ऑपरेशन को कोई कार्रवाई चलने से पहले पूछना आवश्यक हो।	`plugin.approval.*` के माध्यम से रनटाइम स्वीकृति।
Exec स्वीकृतियाँ	किसी होस्ट कमांड या शेल-जैसे टूल को ऑपरेटर की स्वीकृति आवश्यक हो।	होस्ट exec नीति और स्थायी exec अनुमति-सूचियाँ।
Codex मूल अनुमति अनुरोध	Codex मूल शेल, फ़ाइल, MCP या ऐप-सर्वर कार्रवाइयों से पहले पूछता है।	Codex ऐप-सर्वर या मूल हुक स्वीकृति प्रबंधन, जिसे प्रॉम्प्ट का स्वामी OpenClaw होने पर Plugin स्वीकृतियों के माध्यम से रूट किया जाता है।
MCP स्वीकृति अनुरोध	कोई Codex MCP सर्वर किसी टूल कॉल के लिए स्वीकृति का अनुरोध करता है।	OpenClaw Plugin स्वीकृतियों के माध्यम से ब्रिज किए गए MCP स्वीकृति उत्तर।

वैकल्पिक टूल खोज-समय का गेट हैं। Plugin अनुमति अनुरोध प्रति-कॉल गेट हैं। जब किसी संवेदनशील टूल को मॉडल के सामने दिखाई देने से पहले स्पष्ट ऑप्ट-इन और कार्रवाई चलने से पहले स्वीकृति की आवश्यकता हो, तब दोनों का उपयोग करें।

टूल कॉल से पहले स्वीकृति का अनुरोध करें

अधिकांश Plugin-निर्मित प्रॉम्प्ट किसी before_tool_call हुक में शुरू होने चाहिए। यह हुक मॉडल द्वारा टूल चुने जाने के बाद और OpenClaw द्वारा उसे निष्पादित करने से पहले चलता है:

typescript

 export default definePluginEntry({  id: "deploy-policy",  name: "Deploy Policy",  register(api) {    api.on("before_tool_call", async (event) => {      if (event.toolName !== "deploy_service") {        return;      }       const environment =        typeof event.params.environment === "string" ? event.params.environment : "unknown";       return {        requireApproval: {          title: "Deploy service",          description: `Deploy service to ${environment}.`,          severity: environment === "production" ? "critical" : "warning",          allowedDecisions:            environment === "production"              ? ["allow-once", "deny"]              : ["allow-once", "allow-always", "deny"],          timeoutMs: 120_000,          onResolution(decision) {            console.log(`deploy approval resolved: ${decision}`);          },        },      };    });  },});

कार्रवाई को स्वीकृत करने वाले व्यक्ति के लिए प्रॉम्प्ट टेक्स्ट लिखें:

title को संक्षिप्त और कार्रवाई-केंद्रित रखें; Gateway इसे 80 वर्णों तक सीमित करता है।
description को विशिष्ट और सीमित रखें; Gateway इसे 512 वर्णों तक सीमित करता है।
कार्रवाई, लक्ष्य और जोखिम शामिल करें। ऐसे सीक्रेट, टोकन या निजी पेलोड शामिल न करें जो चैट स्वीकृति सतहों पर दिखाई नहीं देने चाहिए।
severity छोड़े जाने पर डिफ़ॉल्ट रूप से "warning" होता है। "critical" का उपयोग केवल उन कार्रवाइयों के लिए करें जिनमें गलत निर्णय से उत्पादन को क्षति या डेटा की हानि हो सकती है।
allowedDecisions छोड़े जाने पर डिफ़ॉल्ट रूप से ["allow-once", "allow-always", "deny"] होता है। जब उस कार्रवाई के लिए स्थायी भरोसा असुरक्षित हो, तब ["allow-once", "deny"] पास करें।
timeoutMs डिफ़ॉल्ट रूप से 120000 (2 मिनट) होता है और अनुरोधित मान की परवाह किए बिना अधिकतम 600000 (10 मिनट) तक सीमित रहता है।

निर्णय व्यवहार

OpenClaw एक plugin: ID के साथ लंबित स्वीकृति बनाता है, उसे उपलब्ध स्वीकृति सतहों तक पहुँचाता है और निर्णय की प्रतीक्षा करता है।

निर्णय	परिणाम
`allow-once`	वर्तमान कॉल जारी रहता है।
`allow-always`	वर्तमान कॉल जारी रहता है और निर्णय Plugin को भेज दिया जाता है।
`deny`	कॉल को अस्वीकृत टूल परिणाम के साथ अवरुद्ध कर दिया जाता है।
समय-समाप्ति	कॉल अवरुद्ध कर दिया जाता है।
रद्दीकरण	रन निरस्त होने पर कॉल अवरुद्ध कर दिया जाता है।
कोई स्वीकृति रूट नहीं	कॉल अवरुद्ध कर दिया जाता है क्योंकि कोई कनेक्टेड स्वीकृति सतह इसे हल नहीं कर सकती।

केवल अनुरोध द्वारा अनुमत सटीक allow-once और allow-always निर्णय ही निष्पादन की अनुमति देते हैं। अज्ञात, विकृत, बेमेल, अनुपस्थित और समय-समाप्त निर्णय सुरक्षित रूप से विफल होते हैं। पुराना timeoutBehavior फ़ील्ड Plugin संगतता के लिए स्वीकार किया जाता है, लेकिन वह अप्रचलित है और अनदेखा किया जाता है; उसे नए हुक में सेट न करें।

allow-always केवल तभी स्थायी होता है जब अनुरोध करने वाला Plugin या रनटाइम उस स्थायित्व को लागू करता है। सामान्य before_tool_call.requireApproval हुक के लिए, OpenClaw allow-once और allow-always को वर्तमान कॉल के स्वीकृति निर्णयों के रूप में मानता है और हल किया गया मान onResolution को भेजता है। यदि आपका Plugin allow-always प्रदान करता है, तो ठीक-ठीक दस्तावेज़ित और लागू करें कि वह भविष्य की किन कॉलों पर भरोसा करता है।

यदि हुक params भी लौटाता है, तो OpenClaw उन पैरामीटर परिवर्तनों को केवल स्वीकृति सफल होने के बाद लागू करता है। उच्च-प्राथमिकता वाले हुक द्वारा स्वीकृति का अनुरोध किए जाने के बाद भी निम्न-प्राथमिकता वाला हुक अवरुद्ध कर सकता है।

allowedDecisions उपयोगकर्ता को दिखाए जाने वाले बटन और कमांड सीमित करता है। Gateway ऐसे किसी भी निर्णय को हल करने के प्रयास को अस्वीकार करता है जिसे अनुरोध ने प्रस्तुत नहीं किया था।

स्वीकृति प्रॉम्प्ट रूट करें

स्वीकृति प्रॉम्प्ट स्थानीय UI सतहों या स्वीकृति प्रबंधन का समर्थन करने वाले चैट चैनलों में हल हो सकते हैं। Plugin स्वीकृति प्रॉम्प्ट को स्पष्ट चैट लक्ष्यों पर अग्रेषित करने के लिए approvals.plugin कॉन्फ़िगर करें:

json5

{  approvals: {    plugin: {      enabled: true,      mode: "targets",      agentFilter: ["main"],      targets: [{ channel: "slack", to: "U12345678" }],    },  },}

approvals.plugin, approvals.exec से स्वतंत्र है। Exec स्वीकृति अग्रेषण सक्षम करने से Plugin स्वीकृति प्रॉम्प्ट रूट नहीं होते, और Plugin स्वीकृति अग्रेषण सक्षम करने से होस्ट exec नीति नहीं बदलती।

जब किसी प्रॉम्प्ट में मैन्युअल स्वीकृति टेक्स्ट शामिल हो, तो प्रस्तुत निर्णयों में से किसी एक से उसे हल करें:

text

/approve <id> allow-once/approve <id> allow-always/approve <id> deny

संपूर्ण अग्रेषण मॉडल, समान-चैट स्वीकृति व्यवहार, मूल चैनल डिलीवरी और चैनल-विशिष्ट स्वीकर्ता नियमों के लिए उन्नत exec स्वीकृतियाँ देखें।

Codex मूल अनुमतियाँ

Codex के मूल अनुमति प्रॉम्प्ट भी Plugin स्वीकृतियों के माध्यम से जा सकते हैं, लेकिन उनका स्वामित्व Plugin-निर्मित हुक से अलग होता है।

Codex ऐप-सर्वर स्वीकृति अनुरोध Codex समीक्षा के बाद OpenClaw के माध्यम से रूट होते हैं।
मूल हुक permission_request रिले सक्षम होने पर plugin.approval.request के माध्यम से पूछ सकता है।
जब Codex _meta.codex_approval_kind को "mcp_tool_call" के रूप में चिह्नित करता है, तब MCP टूल स्वीकृति अनुरोध Plugin स्वीकृतियों के माध्यम से रूट होते हैं।

Codex-विशिष्ट व्यवहार और फ़ॉलबैक नियमों के लिए Codex हार्नेस रनटाइम देखें।

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

टूल कहता है कि Plugin स्वीकृतियाँ अनुपलब्ध हैं। किसी स्वीकृति UI या कॉन्फ़िगर किए गए स्वीकृति रूट ने अनुरोध स्वीकार नहीं किया। किसी स्वीकृति-सक्षम क्लाइंट को कनेक्ट करें, समान-चैट /approve का समर्थन करने वाला चैनल उपयोग करें, या approvals.plugin कॉन्फ़िगर करें।

allow-always दिखाई देता है, लेकिन अगली कॉल फिर से पूछती है। सामान्य Plugin स्वीकृति प्रवाह मनमाने हुक के लिए भरोसे को स्वचालित रूप से स्थायी नहीं करता। onResolution("allow-always") के बाद अपने Plugin में Plugin-स्वामित्व वाला भरोसा स्थायी करें, या केवल allow-once और deny प्रस्तुत करें।

/approve निर्णय को अस्वीकार करता है। अनुरोध ने allowedDecisions को सीमित किया था। प्रॉम्प्ट में मुद्रित निर्णयों में से किसी एक का उपयोग करें।

Discord, Matrix, Slack या Telegram का प्रॉम्प्ट exec स्वीकृतियों से अलग तरीके से रूट होता है। Plugin स्वीकृतियाँ और exec स्वीकृतियाँ अलग कॉन्फ़िगरेशन का उपयोग करती हैं और अलग-अलग प्राधिकरण जाँचों का उपयोग कर सकती हैं। केवल approvals.exec की जाँच करने के बजाय approvals.plugin और चैनल के Plugin स्वीकृति समर्थन को सत्यापित करें।