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 स्वीकृति समर्थन को सत्यापित करें।