---
read_when:
    - در حال ساخت یک Plugin هستید که به before_tool_call، before_agent_reply، هوک‌های پیام، یا هوک‌های چرخه حیات نیاز دارد
    - باید فراخوانی‌های ابزار از سوی یک Plugin را مسدود یا بازنویسی کنید، یا برایشان تأیید الزامی کنید
    - شما در حال تصمیم‌گیری بین هوک‌های داخلی و هوک‌های Plugin هستید
summary: 'هوک‌های Plugin: رویدادهای چرخه عمر عامل، ابزار، پیام، نشست و Gateway را رهگیری کنید'
title: هوک‌های Plugin
x-i18n:
    generated_at: "2026-05-11T20:40:01Z"
    model: gpt-5.5
    provider: openai
    source_hash: b363b8ed7452f0d8bdb267d3eaa38f579d6d7cfb7ace2085ac35baf9b253b575
    source_path: plugins/hooks.md
    workflow: 16
---

قلاب‌های Plugin نقاط توسعهٔ درون‌فرایندی برای Pluginهای OpenClaw هستند. از آن‌ها
زمانی استفاده کنید که یک Plugin باید اجراهای عامل، فراخوانی‌های ابزار، جریان پیام،
چرخهٔ عمر نشست، مسیریابی زیردستیار، نصب‌ها، یا راه‌اندازی Gateway را بررسی یا تغییر دهد.

به‌جای آن، وقتی یک اسکریپت کوچک `HOOK.md` نصب‌شده توسط اپراتور برای رویدادهای فرمان و Gateway مانند
`/new`، `/reset`، `/stop`، `agent:bootstrap`، یا `gateway:startup` می‌خواهید، از [قلاب‌های داخلی](/fa/automation/hooks) استفاده کنید.

## شروع سریع

قلاب‌های تایپ‌شدهٔ Plugin را با `api.on(...)` از نقطهٔ ورود Plugin خود ثبت کنید:

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

export default definePluginEntry({
  id: "tool-preflight",
  name: "Tool Preflight",
  register(api) {
    api.on(
      "before_tool_call",
      async (event) => {
        if (event.toolName !== "web_search") {
          return;
        }

        return {
          requireApproval: {
            title: "Run web search",
            description: `Allow search query: ${String(event.params.query ?? "")}`,
            severity: "info",
            timeoutMs: 60_000,
            timeoutBehavior: "deny",
          },
        };
      },
      { priority: 50 },
    );
  },
});
```

مدیریت‌کننده‌های قلاب به‌ترتیب نزولی `priority` به‌صورت ترتیبی اجرا می‌شوند. قلاب‌های با اولویت یکسان
ترتیب ثبت را حفظ می‌کنند.

`api.on(name, handler, opts?)` می‌پذیرد:

- `priority` - ترتیب مدیریت‌کننده‌ها (عدد بالاتر زودتر اجرا می‌شود).
- `timeoutMs` - بودجهٔ اختیاری برای هر قلاب. وقتی تنظیم شود، اجراکنندهٔ قلاب پس از سپری شدن بودجه، آن
  مدیریت‌کننده را لغو می‌کند و به مورد بعدی ادامه می‌دهد، به‌جای اینکه راه‌اندازی یا بازیابی کند اجازه داده شود
  مهلت مدل پیکربندی‌شدهٔ فراخواننده را مصرف کند. برای استفاده از مهلت پیش‌فرض مشاهده/تصمیم که اجراکنندهٔ
  قلاب به‌صورت عمومی اعمال می‌کند، آن را حذف کنید.

اپراتورها همچنین می‌توانند بدون وصله‌کردن کد Plugin، بودجه‌های قلاب را تنظیم کنند:

```json
{
  "plugins": {
    "entries": {
      "my-plugin": {
        "hooks": {
          "timeoutMs": 30000,
          "timeouts": {
            "before_prompt_build": 90000,
            "agent_end": 60000
          }
        }
      }
    }
  }
}
```

`hooks.timeouts.<hookName>` مقدار `hooks.timeoutMs` را بازنویسی می‌کند، و آن نیز مقدار نوشته‌شده توسط Plugin در
`api.on(..., { timeoutMs })` را بازنویسی می‌کند. هر مقدار پیکربندی‌شده باید یک عدد صحیح مثبت و حداکثر
600000 میلی‌ثانیه باشد. برای قلاب‌های کند شناخته‌شده، بازنویسی‌های جداگانه برای هر قلاب را ترجیح دهید تا یک
Plugin در همه‌جا بودجهٔ طولانی‌تری نگیرد.

هر قلاب `event.context.pluginConfig` را دریافت می‌کند؛ یعنی پیکربندی حل‌شده برای Pluginی که آن مدیریت‌کننده را ثبت کرده است.
از آن برای تصمیم‌های قلابی استفاده کنید که به گزینه‌های فعلی Plugin نیاز دارند؛ OpenClaw آن را برای هر مدیریت‌کننده تزریق می‌کند
بدون اینکه شیء رویداد مشترکی را که Pluginهای دیگر می‌بینند تغییر دهد.

## فهرست قلاب‌ها

قلاب‌ها بر اساس سطحی که گسترش می‌دهند گروه‌بندی شده‌اند. نام‌های **پررنگ** نتیجهٔ تصمیم را می‌پذیرند
(مسدودسازی، لغو، بازنویسی، یا درخواست تأیید)؛ همهٔ موارد دیگر فقط برای مشاهده هستند.

**نوبت عامل**

- `before_model_resolve` - بازنویسی ارائه‌دهنده یا مدل پیش از بارگذاری پیام‌های نشست
- `agent_turn_prepare` - مصرف تزریق‌های نوبت Plugin در صف و افزودن زمینهٔ همان نوبت پیش از قلاب‌های پرامپت
- `before_prompt_build` - افزودن زمینهٔ پویا یا متن پرامپت سیستمی پیش از فراخوانی مدل
- `before_agent_start` - فاز ترکیبی فقط برای سازگاری؛ دو قلاب بالا را ترجیح دهید
- **`before_agent_run`** - بررسی پرامپت نهایی و پیام‌های نشست پیش از ارسال به مدل و در صورت نیاز مسدودسازی اجرا
- **`before_agent_reply`** - قطع کوتاه نوبت مدل با پاسخ مصنوعی یا سکوت
- **`before_agent_finalize`** - بررسی پاسخ نهایی طبیعی و درخواست یک گذر دیگر از مدل
- `agent_end` - مشاهدهٔ پیام‌های نهایی، وضعیت موفقیت، و مدت اجرای نوبت
- `heartbeat_prompt_contribution` - افزودن زمینهٔ ویژهٔ Heartbeat برای پایشگر پس‌زمینه و Pluginهای چرخهٔ عمر

**مشاهدهٔ گفتگو**

- `model_call_started` / `model_call_ended` - مشاهدهٔ فرادادهٔ پاک‌سازی‌شدهٔ فراخوانی ارائه‌دهنده/مدل، زمان‌بندی، نتیجه، و هش‌های محدود شناسهٔ درخواست بدون محتوای پرامپت یا پاسخ
- `llm_input` - مشاهدهٔ ورودی ارائه‌دهنده (پرامپت سیستمی، پرامپت، تاریخچه)
- `llm_output` - مشاهدهٔ خروجی ارائه‌دهنده

**ابزارها**

- **`before_tool_call`** - بازنویسی پارامترهای ابزار، مسدودسازی اجرا، یا درخواست تأیید
- `after_tool_call` - مشاهدهٔ نتایج ابزار، خطاها، و مدت‌زمان
- **`tool_result_persist`** - بازنویسی پیام دستیار تولیدشده از نتیجهٔ ابزار
- **`before_message_write`** - بررسی یا مسدودسازی نوشتن پیام در حال انجام (نادر)

**پیام‌ها و تحویل**

- **`inbound_claim`** - ادعای یک پیام ورودی پیش از مسیریابی عامل (پاسخ‌های مصنوعی)
- `message_received` - مشاهدهٔ محتوای ورودی، فرستنده، رشته، و فراداده
- **`message_sending`** - بازنویسی محتوای خروجی یا لغو تحویل
- `message_sent` - مشاهدهٔ موفقیت یا شکست تحویل خروجی
- **`before_dispatch`** - بررسی یا بازنویسی یک ارسال خروجی پیش از واگذاری به کانال
- **`reply_dispatch`** - مشارکت در خط لولهٔ نهایی ارسال پاسخ

**نشست‌ها و Compaction**

- `session_start` / `session_end` - پیگیری مرزهای چرخهٔ عمر نشست. مقدار `reason` رویداد یکی از `new`، `reset`، `idle`، `daily`، `compaction`، `deleted`، `shutdown`، `restart`، یا `unknown` است. مقدارهای `shutdown` و `restart` از نهایی‌ساز خاموشی gateway زمانی اجرا می‌شوند که فرایند در حالی متوقف یا راه‌اندازی مجدد می‌شود که نشست‌ها هنوز فعال‌اند؛ بنابراین Pluginهای پایین‌دستی (مانند حافظه یا ذخیره‌سازهای رونوشت) می‌توانند ردیف‌های شبحی را که در غیر این صورت پس از راه‌اندازی مجدد در وضعیت باز باقی می‌مانند نهایی کنند. نهایی‌ساز محدود است تا یک Plugin کند نتواند SIGTERM/SIGINT را مسدود کند.
- `before_compaction` / `after_compaction` - مشاهده یا حاشیه‌نویسی چرخه‌های Compaction
- `before_reset` - مشاهدهٔ رویدادهای بازنشانی نشست (`/reset`، بازنشانی‌های برنامه‌نویسی‌شده)

**زیردستیارها**

- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` - هماهنگی مسیریابی زیردستیار و تحویل تکمیل

**چرخهٔ عمر**

- `gateway_start` / `gateway_stop` - شروع یا توقف سرویس‌های متعلق به Plugin همراه با Gateway
- `cron_changed` - مشاهدهٔ تغییرات چرخهٔ عمر cron متعلق به gateway (افزوده‌شده، به‌روزرسانی‌شده، حذف‌شده، شروع‌شده، تمام‌شده، زمان‌بندی‌شده)
- **`before_install`** - بررسی اسکن‌های نصب Skill یا Plugin و در صورت نیاز مسدودسازی

## سیاست فراخوانی ابزار

`before_tool_call` دریافت می‌کند:

- `event.toolName`
- `event.params`
- `event.derivedPaths` اختیاری، شامل راهنمایی‌های بهترین‌تلاش مسیر هدف مشتق‌شده از میزبان
  برای پوشش‌های ابزار شناخته‌شده مانند `apply_patch`؛ وقتی حاضر باشد،
  این مسیرها ممکن است ناقص باشند یا ممکن است بیش از حد برآورد کنند که ابزار واقعاً
  چه چیزی را لمس خواهد کرد (برای مثال، با ورودی‌های بدشکل یا جزئی)
- `event.runId` اختیاری
- `event.toolCallId` اختیاری
- فیلدهای زمینه مانند `ctx.agentId`، `ctx.sessionKey`، `ctx.sessionId`،
  `ctx.runId`، `ctx.jobId` (در اجراهای مبتنی بر cron تنظیم می‌شود)، و `ctx.trace` تشخیصی

می‌تواند برگرداند:

```typescript
type BeforeToolCallResult = {
  params?: Record<string, unknown>;
  block?: boolean;
  blockReason?: string;
  requireApproval?: {
    title: string;
    description: string;
    severity?: "info" | "warning" | "critical";
    timeoutMs?: number;
    timeoutBehavior?: "allow" | "deny";
    pluginId?: string;
    onResolution?: (
      decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled",
    ) => Promise<void> | void;
  };
};
```

قواعد:

- `block: true` نهایی است و مدیریت‌کننده‌های با اولویت پایین‌تر را رد می‌کند.
- `block: false` به‌عنوان بدون تصمیم در نظر گرفته می‌شود.
- `params` پارامترهای ابزار را برای اجرا بازنویسی می‌کند.
- `requireApproval` اجرای عامل را متوقف می‌کند و از کاربر از طریق تأییدهای Plugin درخواست می‌پرسد. فرمان `/approve` می‌تواند هم تأییدهای exec و هم تأییدهای Plugin را تأیید کند.
- یک `block: true` با اولویت پایین‌تر همچنان می‌تواند پس از اینکه قلابی با اولویت بالاتر درخواست تأیید کرده است، مسدود کند.
- `onResolution` تصمیم تأیید حل‌شده را دریافت می‌کند - `allow-once`،
  `allow-always`، `deny`، `timeout`، یا `cancelled`.

Pluginهای همراه که به سیاست سطح میزبان نیاز دارند می‌توانند سیاست‌های ابزار مورداعتماد را با
`api.registerTrustedToolPolicy(...)` ثبت کنند. این‌ها پیش از قلاب‌های معمولی
`before_tool_call` و پیش از تصمیم‌های Plugin خارجی اجرا می‌شوند. آن‌ها را فقط
برای دروازه‌های مورداعتماد میزبان مانند سیاست فضای کاری، اعمال بودجه، یا ایمنی گردش‌کار رزروشده استفاده کنید.
Pluginهای خارجی باید از قلاب‌های عادی `before_tool_call` استفاده کنند.

### ماندگاری نتیجهٔ ابزار

نتایج ابزار می‌توانند شامل `details` ساختاریافته برای رندر UI، عیب‌یابی،
مسیریابی رسانه، یا فرادادهٔ متعلق به Plugin باشند. `details` را فرادادهٔ زمان اجرا در نظر بگیرید،
نه محتوای پرامپت:

- OpenClaw پیش از بازپخش ارائه‌دهنده و ورودی Compaction،
  `toolResult.details` را حذف می‌کند تا فراداده به زمینهٔ مدل تبدیل نشود.
- ورودی‌های نشست ذخیره‌شده فقط `details` محدود را نگه می‌دارند. details بیش از حد بزرگ
  با یک خلاصهٔ فشرده و `persistedDetailsTruncated: true` جایگزین می‌شوند.
- `tool_result_persist` و `before_message_write` پیش از سقف نهایی
  ماندگاری اجرا می‌شوند. قلاب‌ها همچنان باید `details` برگشتی را کوچک نگه دارند و از
  قرار دادن متن مرتبط با پرامپت فقط در `details` خودداری کنند؛ خروجی ابزار قابل‌مشاهده برای مدل را
  در `content` قرار دهید.

## قلاب‌های پرامپت و مدل

برای Pluginهای جدید از قلاب‌های ویژهٔ فاز استفاده کنید:

- `before_model_resolve`: فقط پرامپت فعلی و فرادادهٔ پیوست را دریافت می‌کند.
  `providerOverride` یا `modelOverride` را برگردانید.
- `agent_turn_prepare`: پرامپت فعلی، پیام‌های نشست آماده‌شده،
  و هر تزریق صف‌شدهٔ دقیقاً-یک‌بار که برای این نشست تخلیه شده است را دریافت می‌کند. `prependContext` یا `appendContext` را برگردانید.
- `before_prompt_build`: پرامپت فعلی و پیام‌های نشست را دریافت می‌کند.
  `prependContext`، `appendContext`، `systemPrompt`،
  `prependSystemContext`، یا `appendSystemContext` را برگردانید.
- `heartbeat_prompt_contribution`: فقط برای نوبت‌های heartbeat اجرا می‌شود و
  `prependContext` یا `appendContext` را برمی‌گرداند. برای پایشگرهای پس‌زمینه‌ای در نظر گرفته شده است
  که باید وضعیت فعلی را بدون تغییر دادن نوبت‌های آغازشده توسط کاربر خلاصه کنند.

`before_agent_start` برای سازگاری باقی می‌ماند. قلاب‌های صریح بالا را ترجیح دهید
تا Plugin شما به یک فاز ترکیبی قدیمی وابسته نباشد.

`before_agent_run` پس از ساخت پرامپت و پیش از هر ورودی مدل اجرا می‌شود،
از جمله بارگذاری تصویر محلی به پرامپت و مشاهدهٔ `llm_input`. ورودی فعلی کاربر را به‌عنوان `prompt`،
همراه با تاریخچهٔ نشست بارگذاری‌شده در `messages` و پرامپت سیستمی فعال دریافت می‌کند.
برای توقف اجرا پیش از اینکه مدل بتواند پرامپت را بخواند، `{ outcome: "block", reason, message? }`
را برگردانید. `reason` داخلی است؛ `message` جایگزین قابل‌مشاهده برای کاربر است. تنها خروجی‌های پشتیبانی‌شده
`pass` و `block` هستند؛ شکل‌های تصمیم پشتیبانی‌نشده به‌صورت بسته شکست می‌خورند.

وقتی اجرایی مسدود می‌شود، OpenClaw فقط متن جایگزین را در
`message.content` به‌همراه فرادادهٔ غیرحساس مسدودسازی مانند شناسهٔ Plugin مسدودکننده
و مهر زمانی ذخیره می‌کند. متن اصلی کاربر در رونوشت یا زمینهٔ آینده نگهداری نمی‌شود.
دلایل داخلی مسدودسازی حساس تلقی می‌شوند و از رونوشت، تاریخچه، پخش، گزارش، و payloadهای عیب‌یابی حذف می‌شوند.
مشاهده‌پذیری باید از فیلدهای پاک‌سازی‌شده مانند شناسهٔ مسدودکننده، نتیجه، مهر زمانی، یا یک دستهٔ امن استفاده کند.

`before_agent_start` و `agent_end` زمانی `event.runId` را شامل می‌شوند که OpenClaw بتواند
اجرای فعال را شناسایی کند. همان مقدار روی `ctx.runId` نیز در دسترس است.
اجراهای مبتنی بر Cron همچنین `ctx.jobId` (شناسهٔ کار cron آغازکننده) را در معرض قرار می‌دهند تا
قلاب‌های Plugin بتوانند معیارها، اثرات جانبی، یا وضعیت را به یک کار زمان‌بندی‌شدهٔ مشخص محدود کنند.

برای اجراهای آغازشده از کانال، `ctx.messageProvider` سطح ارائه‌دهنده مانند
`discord` یا `telegram` است، در حالی که `ctx.channelId` شناسهٔ هدف گفتگو است
وقتی OpenClaw بتواند آن را از کلید نشست یا فرادادهٔ تحویل استخراج کند.

`agent_end` یک قلاب مشاهده است و پس از نوبت به‌صورت آتش‌و-فراموش اجرا می‌شود. اجراکنندهٔ
قلاب یک مهلت 30 ثانیه‌ای اعمال می‌کند تا یک Plugin گیرکرده یا endpoint جاسازی
نتواند promise قلاب را برای همیشه معلق نگه دارد. timeout ثبت می‌شود و
OpenClaw ادامه می‌دهد؛ کار شبکهٔ متعلق به Plugin را لغو نمی‌کند مگر اینکه
Plugin خودش نیز از سیگنال لغو استفاده کند.

از `model_call_started` و `model_call_ended` برای تله‌متری فراخوانی ارائه‌دهنده استفاده کنید که نباید پرامپت‌های خام، تاریخچه، پاسخ‌ها، سرآیندها، بدنه‌های درخواست یا شناسه‌های درخواست ارائه‌دهنده را دریافت کند. این هوک‌ها شامل فراداده پایدار مانند `runId`، `callId`، `provider`، `model`، `api`/`transport` اختیاری، `durationMs`/`outcome` پایانی، و `upstreamRequestIdHash` هستند، وقتی OpenClaw بتواند یک هش کران‌دار از شناسه درخواست ارائه‌دهنده استخراج کند.

`before_agent_finalize` فقط زمانی اجرا می‌شود که یک harness در آستانه پذیرش یک پاسخ نهایی طبیعی از دستیار باشد. این مسیر لغو `/stop` نیست و وقتی کاربر یک نوبت را لغو کند اجرا نمی‌شود. برای درخواست یک گذر مدل دیگر از harness پیش از نهایی‌سازی، `{ action: "revise", reason }` را برگردانید؛ برای اجبار نهایی‌سازی، `{ action:
"finalize", reason? }` را برگردانید؛ یا برای ادامه، نتیجه‌ای برنگردانید. هوک‌های بومی `Stop` در Codex به‌عنوان تصمیم‌های `before_agent_finalize` در OpenClaw به این هوک منتقل می‌شوند.

هنگام برگرداندن `action: "revise"`، Pluginها می‌توانند فراداده `retry` را اضافه کنند تا گذر اضافی مدل کران‌دار و ایمن برای بازپخش باشد:

```typescript
type BeforeAgentFinalizeRetry = {
  instruction: string;
  idempotencyKey?: string;
  maxAttempts?: number;
};
```

`instruction` به دلیل بازبینی ارسال‌شده به harness افزوده می‌شود. `idempotencyKey` به میزبان امکان می‌دهد تلاش‌های مجدد را برای همان درخواست Plugin در میان تصمیم‌های نهایی‌سازی معادل بشمارد، و `maxAttempts` سقف تعداد گذرهای اضافی را که میزبان پیش از ادامه با پاسخ نهایی طبیعی مجاز می‌داند تعیین می‌کند.

Pluginهای غیرباندل‌شده‌ای که به هوک‌های مکالمه خام (`before_model_resolve`، `before_agent_reply`، `llm_input`، `llm_output`، `before_agent_finalize`، `agent_end`، یا `before_agent_run`) نیاز دارند باید تنظیم کنند:

```json
{
  "plugins": {
    "entries": {
      "my-plugin": {
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  }
}
```

هوک‌های تغییردهنده پرامپت و تزریق‌های پایدار نوبت بعدی را می‌توان برای هر Plugin با `plugins.entries.<id>.hooks.allowPromptInjection=false` غیرفعال کرد.

### افزونه‌های نشست و تزریق‌های نوبت بعدی

Pluginهای گردش‌کار می‌توانند وضعیت نشست کوچک و سازگار با JSON را با `api.registerSessionExtension(...)` پایدار کنند و آن را از طریق متد `sessions.pluginPatch` در Gateway به‌روزرسانی کنند. ردیف‌های نشست، وضعیت افزونه ثبت‌شده را از طریق `pluginExtensions` بازتاب می‌دهند تا Control UI و کلاینت‌های دیگر بتوانند وضعیت تحت مالکیت Plugin را بدون دانستن جزئیات داخلی Plugin نمایش دهند.

وقتی یک Plugin نیاز دارد زمینه پایدار دقیقاً یک بار به نوبت بعدی مدل برسد، از `api.enqueueNextTurnInjection(...)` استفاده کنید. OpenClaw تزریق‌های صف‌شده را پیش از هوک‌های پرامپت تخلیه می‌کند، تزریق‌های منقضی‌شده را حذف می‌کند، و بر پایه `idempotencyKey` برای هر Plugin رفع تکرار انجام می‌دهد. این درز مناسب برای ازسرگیری‌های تأیید، خلاصه‌های سیاست، دلتاهای پایش پس‌زمینه، و ادامه‌های فرمان است که باید در نوبت بعدی برای مدل قابل مشاهده باشند اما نباید به متن دائمی پرامپت سیستم تبدیل شوند.

معناشناسی پاک‌سازی بخشی از قرارداد است. پاک‌سازی افزونه نشست و callbackهای پاک‌سازی چرخه عمر زمان اجرا، `reset`، `delete`، `disable` یا `restart` را دریافت می‌کنند. میزبان وضعیت افزونه نشست پایدار Plugin مالک و تزریق‌های نوبت بعدی در انتظار را برای reset/delete/disable حذف می‌کند؛ restart وضعیت نشست پایدار را نگه می‌دارد، در حالی که callbackهای پاک‌سازی به Pluginها امکان می‌دهند jobهای زمان‌بند، زمینه اجرا، و منابع خارج از باند دیگر را برای نسل زمان اجرای قدیمی آزاد کنند.

## هوک‌های پیام

از هوک‌های پیام برای مسیریابی و سیاست تحویل در سطح کانال استفاده کنید:

- `message_received`: محتوای ورودی، فرستنده، `threadId`، `messageId`، `senderId`، همبستگی اختیاری run/session، و فراداده را مشاهده می‌کند.
- `message_sending`: `content` را بازنویسی می‌کند یا `{ cancel: true }` را برمی‌گرداند.
- `message_sent`: موفقیت یا شکست نهایی را مشاهده می‌کند.

برای پاسخ‌های TTS فقط-صوتی، `content` ممکن است شامل رونویسی گفتاری پنهان باشد حتی وقتی payload کانال متن/کپشن قابل مشاهده‌ای ندارد. بازنویسی آن `content` فقط رونویسی قابل مشاهده برای هوک را به‌روزرسانی می‌کند؛ به‌عنوان کپشن رسانه نمایش داده نمی‌شود.

زمینه‌های هوک پیام، وقتی در دسترس باشند، فیلدهای همبستگی پایدار را در معرض می‌گذارند: `ctx.sessionKey`، `ctx.runId`، `ctx.messageId`، `ctx.senderId`، `ctx.trace`، `ctx.traceId`، `ctx.spanId`، `ctx.parentSpanId`، و `ctx.callDepth`. پیش از خواندن فراداده قدیمی، این فیلدهای درجه‌یک را ترجیح دهید.

پیش از استفاده از فراداده مخصوص کانال، فیلدهای تایپ‌شده `threadId` و `replyToId` را ترجیح دهید.

قواعد تصمیم‌گیری:

- `message_sending` با `cancel: true` پایانی است.
- `message_sending` با `cancel: false` به‌عنوان نبود تصمیم در نظر گرفته می‌شود.
- `content` بازنویسی‌شده به هوک‌های با اولویت پایین‌تر ادامه می‌دهد مگر اینکه هوک بعدی تحویل را لغو کند.
- `message_sending` می‌تواند همراه با لغو، `cancelReason` و `metadata` کران‌دار را برگرداند. APIهای جدید چرخه عمر پیام این را به‌عنوان نتیجه تحویل سرکوب‌شده با دلیل `cancelled_by_message_sending_hook` در معرض می‌گذارند؛ تحویل مستقیم قدیمی برای سازگاری همچنان یک آرایه نتیجه خالی برمی‌گرداند.
- `message_sent` فقط برای مشاهده است. شکست‌های handler ثبت می‌شوند و نتیجه تحویل را تغییر نمی‌دهند.

## هوک‌های نصب

`before_install` پس از اسکن داخلی برای نصب‌های Skills و Plugin اجرا می‌شود. یافته‌های اضافی یا `{ block: true, blockReason }` را برای توقف نصب برگردانید.

`block: true` پایانی است. `block: false` به‌عنوان نبود تصمیم در نظر گرفته می‌شود.

## چرخه عمر Gateway

از `gateway_start` برای سرویس‌های Plugin که به وضعیت تحت مالکیت Gateway نیاز دارند استفاده کنید. زمینه، `ctx.config`، `ctx.workspaceDir`، و `ctx.getCron?.()` را برای بررسی و به‌روزرسانی cron در معرض می‌گذارد. برای پاک‌سازی منابع بلندمدت از `gateway_stop` استفاده کنید.

برای سرویس‌های زمان اجرای تحت مالکیت Plugin به هوک داخلی `gateway:startup` تکیه نکنید.

`cron_changed` برای رویدادهای چرخه عمر cron تحت مالکیت gateway با payload رویداد تایپ‌شده اجرا می‌شود که دلیل‌های `added`، `updated`، `removed`، `started`، `finished`، و `scheduled` را پوشش می‌دهد. رویداد یک snapshot از `PluginHookGatewayCronJob` (شامل `state.nextRunAtMs`، `state.lastRunStatus`، و در صورت وجود `state.lastError`) به‌همراه یک `PluginHookGatewayCronDeliveryStatus` از `not-requested` | `delivered` | `not-delivered` | `unknown` حمل می‌کند. رویدادهای حذف‌شده همچنان snapshot job حذف‌شده را حمل می‌کنند تا زمان‌بندهای خارجی بتوانند وضعیت را تطبیق دهند. هنگام همگام‌سازی زمان‌بندهای بیدارباش خارجی، از `ctx.getCron?.()` و `ctx.config` در زمینه زمان اجرا استفاده کنید، و OpenClaw را به‌عنوان منبع حقیقت برای بررسی‌های موعد و اجرا نگه دارید.

## منسوخ‌سازی‌های پیش‌رو

چند سطح نزدیک به هوک منسوخ شده‌اند اما همچنان پشتیبانی می‌شوند. پیش از انتشار major بعدی مهاجرت کنید:

- **پاکت‌های متنی ساده کانال** در handlerهای `inbound_claim` و `message_received`. به‌جای parse کردن متن پاکت تخت، `BodyForAgent` و بلوک‌های ساخت‌یافته زمینه کاربر را بخوانید. [پاکت‌های متنی ساده کانال → BodyForAgent](/fa/plugins/sdk-migration#active-deprecations) را ببینید.
- **`before_agent_start`** برای سازگاری باقی می‌ماند. Pluginهای جدید باید به‌جای فاز ترکیبی، از `before_model_resolve` و `before_prompt_build` استفاده کنند.
- **`onResolution` در `before_tool_call`** اکنون به‌جای `string` آزاد، از union تایپ‌شده `PluginApprovalResolution` (`allow-once` / `allow-always` / `deny` / `timeout` / `cancelled`) استفاده می‌کند.

برای فهرست کامل، یعنی ثبت قابلیت حافظه، پروفایل تفکر ارائه‌دهنده، ارائه‌دهندگان احراز هویت خارجی، انواع کشف ارائه‌دهنده، accessorهای زمان اجرای task، و تغییر نام `command-auth` → `command-status`، [مهاجرت Plugin SDK → منسوخ‌سازی‌های فعال](/fa/plugins/sdk-migration#active-deprecations) را ببینید.

## مرتبط

- [مهاجرت Plugin SDK](/fa/plugins/sdk-migration) - منسوخ‌سازی‌های فعال و زمان‌بندی حذف
- [ساخت Pluginها](/fa/plugins/building-plugins)
- [نمای کلی Plugin SDK](/fa/plugins/sdk-overview)
- [نقاط ورود Plugin](/fa/plugins/sdk-entrypoints)
- [هوک‌های داخلی](/fa/automation/hooks)
- [جزئیات داخلی معماری Plugin](/fa/plugins/architecture-internals)