طلبات أذونات Plugin

تتيح طلبات أذونات Plugin لشيفرة Plugin إيقاف استدعاء أداة أو عملية يملكها Plugin مؤقتًا حتى يوافق المستخدم عليها أو يرفضها. وهي تستخدم تدفق Gateway plugin.approval.* وأسطح واجهة الموافقة نفسها التي تتعامل مع أزرار الموافقة في المحادثة وأوامر /approve.

استخدم طلبات أذونات Plugin لأذونات Plugin/التطبيق. وهي لا تحل محل موافقات التنفيذ على المضيف، أو قوائم السماح الاختيارية للأدوات، أو مراجعة الأذونات الأصلية في Codex.

اختر البوابة المناسبة

اختر البوابة التي تطابق نقطة القرار المطلوبة:

الأدوات الاختيارية بوابة في وقت الاكتشاف. أما طلبات أذونات Plugin فهي بوابة لكل استدعاء. استخدم كليهما عندما يجب أن تتطلب أداة حساسة موافقة صريحة قبل أن يتمكن النموذج من رؤيتها، وموافقة قبل تنفيذ الإجراء.

اطلب الموافقة قبل استدعاء أداة

ينبغي أن تبدأ معظم المطالبات التي ينشئها Plugin في خطاف before_tool_call. يعمل الخطاف بعد أن يختار النموذج أداة وقبل أن ينفذها OpenClaw:

 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 (دقيقتان)، ويكون حدها الأقصى 600000 (10 دقائق) بصرف النظر عن القيمة المطلوبة.

سلوك القرار

ينشئ OpenClaw موافقة معلّقة بمعرّف plugin:، ويوصلها إلى أسطح الموافقة المتاحة، وينتظر قرارًا.

لا يسمح بالتنفيذ سوى قراري 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 محاولة البت بأي قرار لم يقدمه الطلب.

وجّه مطالبات الموافقة

يمكن البت في مطالبات الموافقة ضمن أسطح واجهة المستخدم المحلية أو في قنوات المحادثة التي تدعم معالجة الموافقات. لإعادة توجيه مطالبات موافقة Plugin إلى أهداف محادثة صريحة، اضبط approvals.plugin:

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

يعمل approvals.plugin بصورة مستقلة عن approvals.exec. لا يؤدي تمكين إعادة توجيه موافقات التنفيذ إلى توجيه مطالبات موافقة Plugin، كما لا يؤدي تمكين إعادة توجيه موافقات Plugin إلى تغيير سياسة التنفيذ على المضيف.

عندما تتضمن المطالبة نصًا للموافقة اليدوية، فابتّ فيها باستخدام أحد القرارات المعروضة:

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

راجع موافقات التنفيذ المتقدمة للاطلاع على نموذج إعادة التوجيه الكامل، وسلوك الموافقة في المحادثة نفسها، والتسليم الأصلي عبر القنوات، وقواعد الموافقين الخاصة بكل قناة.

أذونات Codex الأصلية

يمكن أيضًا أن تمر مطالبات أذونات Codex الأصلية عبر موافقات Plugin، لكن ملكيتها تختلف عن الخطافات التي ينشئها Plugin.

• تُوجَّه طلبات موافقة خادم تطبيقات Codex عبر OpenClaw بعد مراجعة Codex.
• يمكن لمرحل الخطاف الأصلي permission_request أن يطلب عبر plugin.approval.request عند تمكين ذلك المرحل.
• تُوجَّه طلبات استجلاء موافقة أدوات MCP عبر موافقات Plugin عندما يعيّن Codex _meta.codex_approval_kind إلى "mcp_tool_call".

راجع وقت تشغيل حاضنة Codex للاطلاع على السلوك الخاص بـ Codex وقواعد الرجوع الاحتياطي.

استكشاف الأخطاء وإصلاحها

تفيد الأداة بأن موافقات Plugin غير متاحة. لم تقبل أي واجهة مستخدم للموافقة أو مسار موافقة مضبوط الطلب. صِل عميلًا قادرًا على الموافقة، أو استخدم قناة تدعم /approve في المحادثة نفسها، أو اضبط approvals.plugin.

يظهر allow-always، لكن الاستدعاء التالي يطلب الموافقة مجددًا. لا يحفظ تدفق موافقة Plugin العام الثقة تلقائيًا للخطافات الاعتباطية. احفظ الثقة التي يملكها Plugin داخل Plugin بعد onResolution("allow-always")، أو اعرض فقط allow-once وdeny.

يرفض /approve القرار. قيّد الطلب allowedDecisions. استخدم أحد القرارات المطبوعة في المطالبة.

تُوجَّه مطالبة Discord أو Matrix أو Slack أو Telegram بصورة مختلفة عن موافقات التنفيذ. تستخدم موافقات Plugin وموافقات التنفيذ إعدادات منفصلة، وقد تستخدم عمليات تحقق مختلفة للتخويل. تحقّق من approvals.plugin ودعم القناة لموافقات Plugin بدلًا من التحقق من approvals.exec فقط.

ذو صلة

• خطافات Plugin
• إنشاء Plugins
• موافقات التنفيذ المتقدمة
• بروتوكول Gateway
• وقت تشغيل حاضنة Codex