خطافات Plugin

​

البدء السريع

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 },
    );
  },
});

​

فهرس الخطافات

• before_model_resolve — تجاوز المزوّد أو النموذج قبل تحميل رسائل الجلسة
• before_prompt_build — إضافة سياق ديناميكي أو نص مطالبة نظام قبل استدعاء النموذج
• before_agent_start — مرحلة مدمجة للتوافق فقط؛ يُفضّل استخدام الخطافين أعلاه
• before_agent_reply — إنهاء دورة النموذج مبكرًا برد اصطناعي أو بصمت
• agent_end — مراقبة الرسائل النهائية، وحالة النجاح، ومدة التشغيل

• 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 — فحص عملية dispatch صادرة أو إعادة كتابتها قبل تسليم القناة
• reply_dispatch — المشاركة في مسار dispatch النهائي للرد

• session_start / session_end — تتبّع حدود دورة حياة الجلسة
• before_compaction / after_compaction — مراقبة دورات Compaction أو إضافة تعليقات توضيحية إليها
• before_reset — مراقبة أحداث إعادة ضبط الجلسة (/reset، وإعادات الضبط البرمجية)

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended — تنسيق توجيه الوكيل الفرعي وتسليم الإكمال

• gateway_start / gateway_stop — بدء الخدمات التي يملكها Plugin أو إيقافها مع Gateway
• before_install — فحص عمليات المسح الخاصة بتثبيت Skills أو Plugins وإمكانية حظرها

​

سياسة استدعاء الأدوات

• event.toolName
• event.params
• event.runId اختياري
• event.toolCallId اختياري
• حقول السياق مثل ctx.agentId وctx.sessionKey وctx.sessionId و حقل التشخيص 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.

​

خطافات المطالبة والنموذج

• before_model_resolve: يتلقى المطالبة الحالية وبيانات تعريف المرفقات فقط. أرجِع providerOverride أو modelOverride.
• before_prompt_build: يتلقى المطالبة الحالية ورسائل الجلسة. أرجِع prependContext أو systemPrompt أو prependSystemContext أو appendSystemContext.

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

​

خطافات الرسائل

• message_received: مراقبة المحتوى الوارد، والمرسل، وthreadId، وmessageId، وsenderId، وربط التشغيل/الجلسة الاختياري، وبيانات التعريف.
• message_sending: إعادة كتابة content أو إرجاع { cancel: true }.
• message_sent: مراقبة النجاح أو الفشل النهائي.

• message_sending مع cancel: true نهائي.
• يُعامَل message_sending مع cancel: false على أنه بلا قرار.
• يستمر content المعاد كتابته إلى الخطافات ذات الأولوية الأدنى ما لم يقم خطاف لاحق بإلغاء التسليم.

​

خطافات التثبيت

​

دورة حياة Gateway

​

الإهمالات القادمة

• أغلفة القنوات النصية الصريحة في معالِجات inbound_claim وmessage_received. اقرأ BodyForAgent وكتل سياق المستخدم المهيكلة بدلًا من تحليل نص الغلاف المسطح. راجع أغلفة القنوات النصية الصريحة → BodyForAgent.
• before_agent_start يبقى للتوافق. يجب أن تستخدم Plugins الجديدة before_model_resolve وbefore_prompt_build بدلًا من المرحلة المدمجة.
• onResolution في before_tool_call تستخدم الآن اتحاد PluginApprovalResolution typed ‏(allow-once / allow-always / deny / timeout / cancelled) بدلًا من string حر.

​

ذو صلة

• ترحيل Plugin SDK — الإهمالات النشطة والجدول الزمني للإزالة
• بناء Plugins
• نظرة عامة على Plugin SDK
• نقاط إدخال Plugin
• الخطافات الداخلية
• البنية الداخلية لـ Plugin