خطافات Plugin

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

البدء السريع

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 - ترتيب المعالجات (الأعلى يعمل أولا).
• timeoutMs - ميزانية اختيارية لكل خطاف. عند ضبطها، يوقف مشغل الخطافات ذلك المعالج بعد انقضاء الميزانية ويتابع إلى التالي، بدلا من السماح لإعداد بطيء أو عمل استدعاء بأن يستهلك مهلة النموذج المكونة لدى المستدعي. احذفها لاستخدام مهلة الملاحظة/القرار الافتراضية التي يطبقها مشغل الخطافات بشكل عام.

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

​

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

• 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 فقط لـ plugins مراقبة الخلفية ودورة الحياة

• 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 - المشاركة في خط أنابيب إرسال الرد النهائي

• session_start / session_end - تتبع حدود دورة حياة الجلسة. تكون قيمة reason في الحدث واحدة من new أو reset أو idle أو daily أو compaction أو deleted أو shutdown أو restart أو unknown. تنطلق قيمتا shutdown وrestart من منهي إيقاف Gateway عندما تتوقف العملية أو يعاد تشغيلها بينما لا تزال الجلسات نشطة، حتى تتمكن plugins اللاحقة (مثل مخازن الذاكرة أو النصوص) من إنهاء الصفوف الشبحية التي كانت ستترك في حالة مفتوحة عبر عمليات إعادة التشغيل. المنهي محدود زمنيا حتى لا يستطيع 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 - فحص عمليات مسح تثبيت Skills أو Plugin وحظرها اختياريا

​

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

• 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.

​

استمرار نتيجة الأداة

• يزيل OpenClaw toolResult.details قبل إعادة تشغيل المزود ودخل Compaction حتى لا تصبح البيانات الوصفية سياقا للنموذج.
• تحتفظ إدخالات الجلسة المستمرة فقط بـ details محدودة. تستبدل التفاصيل الكبيرة بملخص مضغوط وpersistedDetailsTruncated: true.
• يعمل tool_result_persist وbefore_message_write قبل حد الاستمرار النهائي. يجب أن تبقي الخطافات مع ذلك details المعادة صغيرة وتتجنب وضع نص ذي صلة بالمطالبة في details فقط؛ ضع خرج الأداة المرئي للنموذج في content.

​

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

• before_model_resolve: يتلقى فقط المطالبة الحالية والبيانات الوصفية للمرفقات. أرجع providerOverride أو modelOverride.
• agent_turn_prepare: يتلقى المطالبة الحالية ورسائل الجلسة المحضرة وأي حقنات مصفوفة مرة واحدة بالضبط تم تفريغها لهذه الجلسة. أرجع prependContext أو appendContext.
• before_prompt_build: يتلقى المطالبة الحالية ورسائل الجلسة. أرجع prependContext أو appendContext أو systemPrompt أو prependSystemContext أو appendSystemContext.
• heartbeat_prompt_contribution: يعمل فقط لدورات Heartbeat ويرجع prependContext أو appendContext. وهو مخصص لمراقبي الخلفية الذين يحتاجون إلى تلخيص الحالة الحالية دون تغيير الدورات التي بدأها المستخدم.

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

{
  "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 المعاد كتابته إلى الخطافات ذات الأولوية الأدنى ما لم يلغِ خطاف لاحق التسليم.
• يمكن لـ message_sending إرجاع cancelReason وmetadata محدودة مع الإلغاء. تعرض واجهات API الجديدة لدورة حياة الرسائل ذلك كنتيجة تسليم مكبوتة بالسبب cancelled_by_message_sending_hook؛ بينما يستمر التسليم المباشر القديم في إرجاع مصفوفة نتائج فارغة للتوافق.
• message_sent للملاحظة فقط. تُسجَّل إخفاقات المعالج ولا تغيّر نتيجة التسليم.

​

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

​

دورة حياة Gateway

​

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

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

​

ذات صلة

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