هوک‌های Plugin

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

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

شروع سریع

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

 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، بودجه‌های قلاب را تنظیم کنند:

{  "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 تشخیصی

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

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 را اضافه کنند تا گذر اضافی مدل کران‌دار و ایمن برای بازپخش باشد:

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) نیاز دارند باید تنظیم کنند:

{  "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 را ببینید.
• 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 → منسوخ‌سازی‌های فعال را ببینید.

مرتبط

• مهاجرت Plugin SDK - منسوخ‌سازی‌های فعال و زمان‌بندی حذف
• ساخت Pluginها
• نمای کلی Plugin SDK
• نقاط ورود Plugin
• هوک‌های داخلی
• جزئیات داخلی معماری Plugin