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

درخواست‌های مجوز Plugin به کد Plugin اجازه می‌دهند یک فراخوانی ابزار یا عملیاتِ متعلق به Plugin را تا زمانی که کاربر آن را تأیید یا رد کند متوقف کند. آن‌ها از جریان plugin.approval.* در Gateway و همان سطوح UI تأیید استفاده می‌کنند که دکمه‌های تأیید چت و دستورهای /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,          timeoutBehavior: "deny",          onResolution(decision) {            console.log(`deploy approval resolved: ${decision}`);          },        },      };    });  },});

متن پرامپت را برای فردی بنویسید که قرار است اقدام را تأیید کند:

• title را کوتاه و متمرکز بر اقدام نگه دارید. Gateway تا ۸۰ نویسه را می‌پذیرد.
• description را مشخص و محدود نگه دارید. Gateway تا ۲۵۶ نویسه را می‌پذیرد.
• اقدام، هدف، و ریسک را وارد کنید. رازها، توکن‌ها، یا بارهای خصوصی‌ای را که نباید در سطوح تأیید چت ظاهر شوند وارد نکنید.
• فقط برای اقدام‌هایی از severity: "critical" استفاده کنید که تصمیم نادرست درباره آن‌ها می‌تواند باعث آسیب به محیط تولید یا از دست رفتن داده شود.
• وقتی اعتماد پایدار برای آن اقدام ناامن است، از allowedDecisions: ["allow-once", "deny"] استفاده کنید.

رفتار تصمیم

OpenClaw یک تأیید در انتظار با شناسه 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 را پیکربندی کنید:

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

approvals.plugin مستقل از approvals.exec است. فعال کردن ارسال تأییدهای exec اعلان‌های تأیید Plugin را مسیریابی نمی‌کند، و فعال کردن ارسال تأییدهای Plugin سیاست exec میزبان را تغییر نمی‌دهد.

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

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

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

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

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

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

برای رفتار مخصوص Codex و قواعد fallback، زمان اجرای harness در Codex را ببینید.

عیب‌یابی

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

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

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

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

مرتبط

• hookهای Plugin
• ساخت Pluginها
• تأییدهای پیشرفته exec
• پروتکل Gateway
• زمان اجرای harness در Codex