---
read_when:
    - برای درخواست تأیید پیش از اجرای یک اثر جانبی، به یک هوک یا ابزار Plugin نیاز دارید
    - باید محل ارسال درخواست‌های تأیید Plugin را پیکربندی کنید
    - شما در حال تصمیم‌گیری میان ابزارهای اختیاری، تأیید اجرای دستورها و تأیید Pluginها هستید
sidebarTitle: Permission requests
summary: از کاربران بخواهید فراخوانی ابزارهای Plugin و درخواست‌های مجوز متعلق به Plugin را تأیید کنند
title: درخواست‌های مجوز Plugin
x-i18n:
    generated_at: "2026-07-27T14:25:38Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 675534212e70cc7b2e7bdc801955929c6a8156b08d620483edf0133afc3bfdaa
    source_path: plugins/plugin-permission-requests.md
    workflow: 16
---

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

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

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

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

| دروازه                             | چه زمانی از آن استفاده شود                                                              | چه چیزی را کنترل می‌کند                                                                                                  |
| -------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| ابزارهای اختیاری                   | تا زمانی که کاربر صریحاً آن را فعال نکرده است، ابزار نباید برای مدل قابل‌مشاهده باشد.        | نمایش ابزار از طریق `tools.allow`.                                                                              |
| درخواست‌های مجوز پلاگین       | یک هوک پلاگین یا عملیات تحت مالکیت پلاگین باید پیش از اجرای یک اقدام اجازه بگیرد. | تأیید زمان اجرا از طریق `plugin.approval.*`.                                                                     |
| تأییدهای اجرا                   | یک فرمان میزبان یا ابزار شبیه پوسته به تأیید اپراتور نیاز دارد.               | خط‌مشی اجرای میزبان و فهرست‌های مجاز پایدار اجرا.                                                                     |
| درخواست‌های بومی مجوز Codex | Codex پیش از اقدامات بومی پوسته، فایل، MCP یا app-server اجازه می‌گیرد.        | مدیریت تأیید app-server یا هوک بومی Codex که وقتی OpenClaw مالک درخواست است، از طریق تأییدهای پلاگین مسیریابی می‌شود. |
| درخواست‌های تأیید MCP        | یک سرور MCP در Codex برای فراخوانی ابزار درخواست تأیید می‌کند.                    | پاسخ‌های تأیید MCP که از طریق تأییدهای پلاگین OpenClaw منتقل می‌شوند.                                                 |

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

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

بیشتر درخواست‌هایی که پلاگین ایجاد می‌کند باید در یک هوک `before_tool_call` آغاز شوند. این هوک پس از انتخاب ابزار توسط مدل و پیش از اجرای آن به‌وسیله OpenClaw اجرا می‌شود:

```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

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`    | فراخوانی فعلی ادامه می‌یابد و تصمیم به پلاگین ارسال می‌شود.      |
| `deny`            | فراخوانی با نتیجه ردشده ابزار مسدود می‌شود.                            |
| پایان مهلت           | فراخوانی مسدود می‌شود.                                                      |
| لغو      | هنگام متوقف‌شدن اجرا، فراخوانی مسدود می‌شود.                              |
| نبود مسیر تأیید | فراخوانی مسدود می‌شود، زیرا هیچ سطح تأیید متصلی نمی‌تواند آن را حل‌وفصل کند. |

فقط تصمیم‌های دقیق `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` را پیکربندی کنید:

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

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

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

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

برای مدل کامل ارسال، رفتار تأیید در همان گفت‌وگو، تحویل بومی کانال و قواعد تأییدکنندگان مختص هر کانال، به [تأییدهای پیشرفته اجرا](/fa/tools/exec-approvals-advanced#plugin-approval-forwarding) مراجعه کنید.

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

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

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

برای رفتار مختص Codex و قواعد بازگشت، به [زمان اجرای مهار Codex](/fa/plugins/codex-harness-runtime#native-permissions-and-mcp-elicitations) مراجعه کنید.

## عیب‌یابی

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

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

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

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

## مطالب مرتبط

- [هوک‌های پلاگین](/fa/plugins/hooks#tool-call-policy)
- [ساخت پلاگین‌ها](/fa/plugins/building-plugins#registering-tools)
- [تأییدهای پیشرفته اجرا](/fa/tools/exec-approvals-advanced#plugin-approval-forwarding)
- [پروتکل Gateway](/fa/gateway/protocol)
- [زمان اجرای مهار Codex](/fa/plugins/codex-harness-runtime#native-permissions-and-mcp-elicitations)