الخطافات

Hooks هي سكربتات صغيرة تعمل عند حدوث شيء داخل Gateway. يمكن اكتشافها من الأدلة وفحصها باستخدام openclaw hooks. لا يحمّل Gateway الخطافات الداخلية إلا بعد تمكين الخطافات أو تكوين إدخال خطاف واحد على الأقل، أو حزمة خطافات، أو معالج قديم، أو دليل خطافات إضافي.

يوجد نوعان من الخطافات في OpenClaw:

• الخطافات الداخلية (هذه الصفحة): تعمل داخل Gateway عند إطلاق أحداث الوكيل، مثل /new أو /reset أو /stop أو أحداث دورة الحياة.
• Webhooks: نقاط نهاية HTTP خارجية تتيح للأنظمة الأخرى تشغيل العمل في OpenClaw. راجع Webhooks.

يمكن أيضًا تضمين الخطافات داخل plugins. يعرض openclaw hooks list كلًا من الخطافات المستقلة والخطافات التي تديرها plugins.

البدء السريع

# List available hooksopenclaw hooks list # Enable a hookopenclaw hooks enable session-memory # Check hook statusopenclaw hooks check # Get detailed informationopenclaw hooks info session-memory

أنواع الأحداث

كتابة الخطافات

بنية الخطاف

كل خطاف هو دليل يحتوي على ملفين:

my-hook/├── HOOK.md          # Metadata + documentation└── handler.ts       # Handler implementation

تنسيق HOOK.md

---name: my-hookdescription: "Short description of what this hook does"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # My Hook Detailed documentation goes here.

حقول البيانات الوصفية (metadata.openclaw):

تنفيذ المعالج

const handler = async (event) => {  if (event.type !== "command" || event.action !== "new") {    return;  }   console.log(`[my-hook] New command triggered`);  // Your logic here   // Optionally send message to user  event.messages.push("Hook executed!");}; export default handler;

يتضمن كل حدث: type وaction وsessionKey وtimestamp وmessages (أضف إليها للإرسال إلى المستخدم) وcontext (بيانات خاصة بالحدث). يمكن أن تتضمن سياقات خطافات Plugins الخاصة بالوكلاء والأدوات أيضًا trace، وهو سياق تتبع تشخيصي متوافق مع W3C للقراءة فقط يمكن لـ plugins تمريره إلى السجلات المنظمة لربط OTEL.

أبرز سياقات الأحداث

أحداث الأوامر (command:new، command:reset): context.sessionEntry وcontext.previousSessionEntry وcontext.commandSource وcontext.workspaceDir وcontext.cfg.

أحداث الرسائل (message:received): context.from وcontext.content وcontext.channelId وcontext.metadata (بيانات خاصة بالمزود تتضمن senderId وsenderName وguildId). يفضل context.content نص أمر غير فارغ للرسائل الشبيهة بالأوامر، ثم يعود إلى النص الوارد الخام والنص العام؛ ولا يتضمن إثراءً مخصصًا للوكيل فقط مثل سجل سلسلة النقاش أو ملخصات الروابط.

أحداث الرسائل (message:sent): context.to وcontext.content وcontext.success وcontext.channelId.

أحداث الرسائل (message:transcribed): context.transcript وcontext.from وcontext.channelId وcontext.mediaPath.

أحداث الرسائل (message:preprocessed): context.bodyForAgent (النص النهائي المُثرى) وcontext.from وcontext.channelId.

أحداث التمهيد (agent:bootstrap): context.bootstrapFiles (مصفوفة قابلة للتعديل) وcontext.agentId.

أحداث تصحيح الجلسة (session:patch): context.sessionEntry وcontext.patch (الحقول المتغيرة فقط) وcontext.cfg. لا يمكن إلا للعملاء ذوي الامتياز تشغيل أحداث التصحيح.

أحداث Compaction: يتضمن session:compact:before كلًا من messageCount وtokenCount. يضيف session:compact:after كلًا من compactedCount وsummaryLength وtokensBefore وtokensAfter.

يراقب command:stop إصدار المستخدم للأمر /stop؛ فهو جزء من دورة حياة الإلغاء/الأمر، وليس بوابة لإنهاء الوكيل. يجب على Plugins التي تحتاج إلى فحص إجابة نهائية طبيعية وطلب مرور إضافي واحد من الوكيل استخدام خطاف Plugin المكتوب before_agent_finalize بدلًا من ذلك. راجع خطافات Plugin.

أحداث دورة حياة Gateway: يتضمن gateway:shutdown كلًا من reason وrestartExpectedMs ويُطلق عند بدء إيقاف Gateway. يتضمن gateway:pre-restart السياق نفسه، لكنه يُطلق فقط عندما يكون الإيقاف جزءًا من إعادة تشغيل متوقعة وتُقدَّم قيمة restartExpectedMs محدودة. أثناء الإيقاف، يكون انتظار كل خطاف دورة حياة بأفضل جهد ومحدودًا بحيث يستمر الإيقاف إذا توقف معالج عن الاستجابة.

بين حدث gateway:shutdown (أو gateway:pre-restart) وبقية تسلسل الإيقاف، يطلق Gateway أيضًا خطاف Plugin مكتوبًا باسم session_end لكل جلسة كانت لا تزال نشطة عند توقف العملية. تكون قيمة reason في الحدث هي shutdown عند إيقاف SIGTERM/SIGINT عادي، وrestart عندما يكون الإغلاق مجدولًا كجزء من إعادة تشغيل متوقعة. هذا التفريغ محدود بحيث لا يستطيع معالج session_end البطيء حظر خروج العملية، ويتم تخطي الجلسات التي أُنجز إنهاؤها مسبقًا عبر الاستبدال / إعادة الضبط / الحذف / Compaction لتجنب الإطلاق المزدوج.

اكتشاف الخطافات

تُكتشف الخطافات من هذه الأدلة، بترتيب أسبقية تجاوز متزايدة:

1. الخطافات المضمنة: تُشحن مع OpenClaw
2. خطافات Plugin: خطافات مضمنة داخل plugins المثبتة
3. الخطافات المُدارة: ~/.openclaw/hooks/ (مثبتة من المستخدم ومشتركة بين مساحات العمل). تشارك الأدلة الإضافية من hooks.internal.load.extraDirs هذه الأسبقية.
4. خطافات مساحة العمل: <workspace>/hooks/ (لكل وكيل، معطلة افتراضيًا حتى تُفعّل صراحة)

يمكن لخطافات مساحة العمل إضافة أسماء خطافات جديدة، لكنها لا تستطيع تجاوز الخطافات المضمنة أو المُدارة أو المقدمة من plugins التي تحمل الاسم نفسه.

يتخطى Gateway اكتشاف الخطافات الداخلية عند بدء التشغيل حتى تُكوَّن الخطافات الداخلية. فعّل خطافًا مضمنًا أو مُدارًا باستخدام openclaw hooks enable <name>، أو ثبّت حزمة خطافات، أو اضبط hooks.internal.enabled=true للاشتراك. عندما تفعّل خطافًا مسمى واحدًا، لا يحمّل Gateway إلا معالج ذلك الخطاف؛ أما hooks.internal.enabled=true وأدلة الخطافات الإضافية والمعالجات القديمة فتشترك في الاكتشاف الواسع.

حزم الخطافات

حزم الخطافات هي حزم npm تصدّر الخطافات عبر openclaw.hooks في package.json. ثبّتها باستخدام:

openclaw plugins install <path-or-spec>

مواصفات npm مقتصرة على السجل (اسم الحزمة + إصدار دقيق اختياري أو dist-tag). تُرفض مواصفات Git/URL/file ونطاقات semver.

الخطافات المضمنة

فعّل أي خطاف مضمن:

openclaw hooks enable <hook-name>

تفاصيل session-memory

يستخرج آخر 15 رسالة للمستخدم/المساعد ويحفظها في <workspace>/memory/YYYY-MM-DD-HHMM.md باستخدام التاريخ المحلي للمضيف. يعمل التقاط الذاكرة في الخلفية بحيث لا تتأخر إقرارات /new و/reset بسبب قراءات النص أو إنشاء slug اختياري. اضبط hooks.internal.entries.session-memory.llmSlug: true لإنشاء slug وصفي لاسم الملف باستخدام النموذج المكوّن. يتطلب تكوين workspace.dir.

إعداد bootstrap-extra-files

{  "hooks": {    "internal": {      "entries": {        "bootstrap-extra-files": {          "enabled": true,          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]        }      }    }  }}

تُحل المسارات نسبةً إلى مساحة العمل. لا تُحمّل إلا أسماء ملفات التمهيد الأساسية المعروفة (AGENTS.md وSOUL.md وTOOLS.md وIDENTITY.md وUSER.md وHEARTBEAT.md وBOOTSTRAP.md وMEMORY.md).

تفاصيل command-logger

يسجل كل أمر slash في ~/.openclaw/logs/commands.log.

تفاصيل compaction-notifier

يرسل رسائل حالة قصيرة إلى المحادثة الحالية عندما يبدأ OpenClaw وينتهي من ضغط نص الجلسة. يجعل هذا المنعطفات الطويلة أقل إرباكًا على واجهات الدردشة لأن المستخدم يستطيع رؤية أن المساعد يلخص السياق وسيواصل بعد Compaction.

تفاصيل boot-md

يشغّل BOOT.md من مساحة العمل النشطة عند بدء Gateway.

خطافات Plugin

يمكن لـ Plugins تسجيل خطافات مكتوبة عبر Plugin SDK لتكامل أعمق: اعتراض استدعاءات الأدوات، وتعديل المطالبات، والتحكم في تدفق الرسائل، وغير ذلك. استخدم خطافات Plugin عندما تحتاج إلى before_tool_call أو before_agent_reply أو before_install أو خطافات دورة حياة أخرى داخل العملية.

للاطلاع على مرجع خطافات Plugin الكامل، راجع خطافات Plugin.

التكوين

{  "hooks": {    "internal": {      "enabled": true,      "entries": {        "session-memory": { "enabled": true },        "command-logger": { "enabled": false }      }    }  }}

متغيرات البيئة لكل خطاف:

{  "hooks": {    "internal": {      "entries": {        "my-hook": {          "enabled": true,          "env": { "MY_CUSTOM_VAR": "value" }        }      }    }  }}

أدلة الخطافات الإضافية:

{  "hooks": {    "internal": {      "load": {        "extraDirs": ["/path/to/more/hooks"]      }    }  }}

مرجع CLI

# List all hooks (add --eligible, --verbose, or --json)openclaw hooks list # Show detailed info about a hookopenclaw hooks info <hook-name> # Show eligibility summaryopenclaw hooks check # Enable/disableopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

أفضل الممارسات

• أبقِ المعالجات سريعة. تعمل الخطافات أثناء معالجة الأوامر. شغّل الأعمال الثقيلة بأسلوب التشغيل والإهمال باستخدام void processInBackground(event).
• تعامل مع الأخطاء بسلاسة. لفّ العمليات الخطرة في try/catch؛ لا ترمِ استثناءات حتى تتمكن المعالجات الأخرى من العمل.
• رشّح الأحداث مبكرًا. ارجع فورًا إذا لم يكن نوع الحدث/الإجراء ذا صلة.
• استخدم مفاتيح أحداث محددة. فضّل "events": ["command:new"] على "events": ["command"] لتقليل الحمل الزائد.

استكشاف الأخطاء وإصلاحها

لم يتم اكتشاف الخطاف

# Verify directory structurels -la ~/.openclaw/hooks/my-hook/# Should show: HOOK.md, handler.ts # List all discovered hooksopenclaw hooks list

الخطاف غير مؤهل

openclaw hooks info my-hook

تحقق من الملفات التنفيذية المفقودة (PATH)، أو متغيرات البيئة، أو قيم الإعدادات، أو توافق نظام التشغيل.

الخطاف لا يُنفّذ

1. تحقق من تمكين الخطاف: openclaw hooks list
2. أعد تشغيل عملية Gateway حتى تعيد الخطافات التحميل.
3. تحقق من سجلات Gateway: ./scripts/clawlog.sh | grep hook

ذو صلة

• مرجع CLI: الخطافات
• Webhooks
• خطافات Plugin — خطافات دورة حياة Plugin داخل العملية
• الإعدادات