---
read_when:
    - برای پرسیدن پیش از اجرای یک اثر جانبی، به یک hook یا ابزار Plugin نیاز دارید
    - باید پیکربندی کنید درخواست‌های تأیید Plugin کجا تحویل داده شوند
    - شما در حال تصمیم‌گیری بین ابزارهای اختیاری، تأییدهای اجرا و تأییدهای Plugin هستید
sidebarTitle: Permission requests
summary: از کاربران بخواهید فراخوانی‌های ابزار Plugin و درخواست‌های مجوز متعلق به Plugin را تأیید کنند
title: درخواست‌های مجوز Plugin
x-i18n:
    generated_at: "2026-06-27T18:21:42Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 72b860e9f8ddef80c70e943ec05353cbc0a917577382289649432a58c3ce6bd0
    source_path: plugins/plugin-permission-requests.md
    workflow: 16
---

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

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

## گیت درست را انتخاب کنید

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

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

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

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

بیشتر پرامپت‌های نوشته‌شده توسط Plugin باید در یک هوک `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,
          timeoutBehavior: "deny",
          onResolution(decision) {
            console.log(`deploy approval resolved: ${decision}`);
          },
        },
      };
    });
  },
});
```

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

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

## رفتار تصمیم

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

| تصمیم            | نتیجه                                                                    |
| ---------------- | ------------------------------------------------------------------------- |
| `allow-once`     | فراخوانی فعلی ادامه پیدا می‌کند.                                          |
| `allow-always`   | فراخوانی فعلی ادامه پیدا می‌کند و تصمیم به Plugin ارسال می‌شود.           |
| `deny`           | فراخوانی با نتیجه ابزارِ ردشده مسدود می‌شود.                              |
| پایان مهلت       | فراخوانی مسدود می‌شود مگر آن‌که `timeoutBehavior` برابر با `"allow"` باشد. |
| لغو              | وقتی اجرا متوقف می‌شود، فراخوانی مسدود می‌شود.                            |
| نبود مسیر تأیید  | فراخوانی مسدود می‌شود چون هیچ سطح تأیید متصلی نمی‌تواند آن را حل کند.     |

`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](/fa/tools/exec-approvals-advanced#plugin-approval-forwarding)
را ببینید.

## مجوزهای بومی 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](/fa/plugins/codex-harness-runtime#native-permissions-and-mcp-elicitations)
را ببینید.

## عیب‌یابی

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