درخواست‌های مجوز Plugin

درخواست‌های مجوز پلاگین به کد پلاگین اجازه می‌دهند فراخوانی یک ابزار یا عملیات تحت مالکیت پلاگین را تا زمانی که کاربر آن را تأیید یا رد کند، متوقف کند. آن‌ها از جریان Gateway plugin.approval.* و همان سطوح رابط کاربری تأیید استفاده می‌کنند که دکمه‌های تأیید در گفت‌وگو و فرمان‌های /approve را مدیریت می‌کنند.

از درخواست‌های مجوز پلاگین برای مجوزهای پلاگین/برنامه استفاده کنید. این درخواست‌ها جایگزین تأییدهای اجرای میزبان، فهرست‌های مجاز اختیاری ابزارها یا بازبینی بومی مجوزهای Codex نمی‌شوند.

انتخاب دروازه مناسب

دروازه‌ای را انتخاب کنید که با نقطه تصمیم‌گیری موردنیازتان مطابقت دارد:

ابزارهای اختیاری دروازه‌ای در زمان کشف هستند. درخواست‌های مجوز پلاگین دروازه‌ای برای هر فراخوانی هستند. وقتی یک ابزار حساس باید پیش از قابل‌مشاهده‌شدن برای مدل به انتخاب صریح کاربر نیاز داشته باشد و پیش از اجرای اقدام نیز تأیید شود، از هر دو استفاده کنید.

درخواست تأیید پیش از فراخوانی ابزار

بیشتر درخواست‌هایی که پلاگین ایجاد می‌کند باید در یک هوک 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 (2 دقیقه) است و صرف‌نظر از مقدار درخواستی، به 600000 (10 دقیقه) محدود می‌شود.

رفتار تصمیم‌گیری

OpenClaw یک تأیید در انتظار با شناسه plugin: ایجاد می‌کند، آن را به سطوح تأیید موجود تحویل می‌دهد و منتظر تصمیم می‌ماند.

فقط تصمیم‌های دقیق allow-once و allow-always که درخواست اجازه داده است، اجرای عملیات را ممکن می‌کنند. تصمیم‌های ناشناخته، بدشکل، نامنطبق، مفقود و منقضی‌شده به‌صورت بسته و ایمن شکست می‌خورند. فیلد قدیمی timeoutBehavior برای سازگاری پلاگین همچنان پذیرفته می‌شود، اما منسوخ شده و نادیده گرفته می‌شود؛ آن را در هوک‌های جدید تنظیم نکنید.

allow-always فقط زمانی پایدار است که پلاگین یا زمان اجرای درخواست‌کننده، ماندگاری آن را پیاده‌سازی کند. برای هوک‌های عادی before_tool_call.requireApproval، OpenClaw مقادیر allow-once و allow-always را به‌عنوان تصمیم‌های تأیید فراخوانی فعلی در نظر می‌گیرد و مقدار نهایی را به onResolution ارسال می‌کند. اگر پلاگین شما allow-always را ارائه می‌دهد، دقیقاً مستند و پیاده‌سازی کنید که به کدام فراخوانی‌های آینده اعتماد می‌کند.

اگر هوک همچنین params را برگرداند، OpenClaw آن تغییرات پارامتر را فقط پس از موفقیت تأیید اعمال می‌کند. یک هوک با اولویت پایین‌تر همچنان می‌تواند پس از درخواست تأیید توسط هوکی با اولویت بالاتر، عملیات را مسدود کند.

allowedDecisions دکمه‌ها و فرمان‌های نمایش‌داده‌شده به کاربر را محدود می‌کند. Gateway هر تلاش برای حل‌وفصل با تصمیمی را که درخواست ارائه نکرده است، رد می‌کند.

مسیریابی درخواست‌های تأیید

درخواست‌های تأیید می‌توانند در سطوح رابط کاربری محلی یا کانال‌های گفت‌وگویی که از مدیریت تأیید پشتیبانی می‌کنند، حل‌وفصل شوند. برای ارسال درخواست‌های تأیید پلاگین به هدف‌های صریح گفت‌وگو، approvals.plugin را پیکربندی کنید:

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

approvals.plugin مستقل از approvals.exec است. فعال‌کردن ارسال تأیید اجرا، درخواست‌های تأیید پلاگین را مسیریابی نمی‌کند و فعال‌کردن ارسال تأیید پلاگین نیز خط‌مشی اجرای میزبان را تغییر نمی‌دهد.

وقتی یک درخواست شامل متن تأیید دستی است، آن را با یکی از تصمیم‌های ارائه‌شده حل‌وفصل کنید:

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

برای مدل کامل ارسال، رفتار تأیید در همان گفت‌وگو، تحویل بومی کانال و قواعد تأییدکنندگان مختص هر کانال، به تأییدهای پیشرفته اجرا مراجعه کنید.

مجوزهای بومی Codex

درخواست‌های بومی مجوز Codex نیز می‌توانند از طریق تأییدهای پلاگین منتقل شوند، اما مالکیت آن‌ها با هوک‌های ایجادشده توسط پلاگین متفاوت است.

• درخواست‌های تأیید app-server در Codex پس از بازبینی Codex از طریق OpenClaw مسیریابی می‌شوند.
• رله هوک بومی permission_request در صورت فعال‌بودن می‌تواند از طریق plugin.approval.request درخواست کند.
• وقتی Codex مقدار _meta.codex_approval_kind را "mcp_tool_call" علامت‌گذاری کند، درخواست‌های تأیید ابزار MCP از طریق تأییدهای پلاگین مسیریابی می‌شوند.

برای رفتار مختص Codex و قواعد بازگشت، به زمان اجرای مهار Codex مراجعه کنید.

عیب‌یابی

ابزار اعلام می‌کند تأییدهای پلاگین در دسترس نیستند. هیچ رابط کاربری تأیید یا مسیر تأیید پیکربندی‌شده‌ای درخواست را نپذیرفت. یک کلاینت دارای قابلیت تأیید را متصل کنید، از کانالی استفاده کنید که از /approve در همان گفت‌وگو پشتیبانی می‌کند، یا approvals.plugin را پیکربندی کنید.

allow-always ظاهر می‌شود، اما فراخوانی بعدی دوباره درخواست تأیید می‌کند. جریان عمومی تأیید پلاگین، اعتماد را برای هوک‌های دلخواه به‌طور خودکار پایدار نمی‌کند. پس از onResolution("allow-always")، اعتماد تحت مالکیت پلاگین را در پلاگین خود پایدار کنید، یا فقط allow-once و deny را ارائه دهید.

/approve تصمیم را رد می‌کند. درخواست، allowedDecisions را محدود کرده است. از یکی از تصمیم‌های چاپ‌شده در درخواست استفاده کنید.

یک درخواست Discord، Matrix، Slack یا Telegram متفاوت از تأییدهای اجرا مسیریابی می‌شود. تأییدهای پلاگین و تأییدهای اجرا از پیکربندی‌های جداگانه استفاده می‌کنند و ممکن است بررسی‌های مجوزدهی متفاوتی داشته باشند. به‌جای بررسی صرف approvals.exec، مقدار approvals.plugin و پشتیبانی کانال از تأیید پلاگین را بررسی کنید.

مطالب مرتبط

• هوک‌های پلاگین
• ساخت پلاگین‌ها
• تأییدهای پیشرفته اجرا
• پروتکل Gateway
• زمان اجرای مهار Codex