Hooks هي سكربتات صغيرة تعمل عند حدوث شيء داخل Gateway. يمكن اكتشافها من الأدلة وفحصها باستخدام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.
openclaw hooks. لا يحمّل Gateway الخطافات الداخلية إلا بعد تمكين الخطافات أو تكوين إدخال خطاف واحد على الأقل، أو حزمة خطافات، أو معالج قديم، أو دليل خطافات إضافي.
يوجد نوعان من الخطافات في OpenClaw:
- الخطافات الداخلية (هذه الصفحة): تعمل داخل Gateway عند إطلاق أحداث الوكيل، مثل
/newأو/resetأو/stopأو أحداث دورة الحياة. - Webhooks: نقاط نهاية HTTP خارجية تتيح للأنظمة الأخرى تشغيل العمل في OpenClaw. راجع Webhooks.
openclaw hooks list كلًا من الخطافات المستقلة والخطافات التي تديرها plugins.
البدء السريع
أنواع الأحداث
| الحدث | وقت إطلاقه |
|---|---|
command:new | عند إصدار الأمر /new |
command:reset | عند إصدار الأمر /reset |
command:stop | عند إصدار الأمر /stop |
command | أي حدث أمر (مستمع عام) |
session:compact:before | قبل أن تلخص Compaction السجل |
session:compact:after | بعد اكتمال Compaction |
session:patch | عند تعديل خصائص الجلسة |
agent:bootstrap | قبل حقن ملفات تمهيد مساحة العمل |
gateway:startup | بعد بدء القنوات وتحميل الخطافات |
gateway:shutdown | عند بدء إيقاف Gateway |
gateway:pre-restart | قبل إعادة تشغيل متوقعة لـ Gateway |
message:received | رسالة واردة من أي قناة |
message:transcribed | بعد اكتمال تفريغ الصوت |
message:preprocessed | بعد اكتمال المعالجة المسبقة للوسائط والروابط أو تخطيها |
message:sent | تسليم رسالة صادرة |
كتابة الخطافات
بنية الخطاف
كل خطاف هو دليل يحتوي على ملفين:تنسيق HOOK.md
metadata.openclaw):
| الحقل | الوصف |
|---|---|
emoji | رمز تعبيري للعرض في CLI |
events | مصفوفة من الأحداث التي يجب الاستماع إليها |
export | التصدير المسمى المراد استخدامه (الافتراضي هو "default") |
os | المنصات المطلوبة (مثل ["darwin", "linux"]) |
requires | مسارات bins أو anyBins أو env أو config المطلوبة |
always | تجاوز فحوصات الأهلية (قيمة منطقية) |
install | طرق التثبيت |
تنفيذ المعالج
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 لتجنب الإطلاق المزدوج.
اكتشاف الخطافات
تُكتشف الخطافات من هذه الأدلة، بترتيب أسبقية تجاوز متزايدة:- الخطافات المضمنة: تُشحن مع OpenClaw
- خطافات Plugin: خطافات مضمنة داخل plugins المثبتة
- الخطافات المُدارة:
~/.openclaw/hooks/(مثبتة من المستخدم ومشتركة بين مساحات العمل). تشارك الأدلة الإضافية منhooks.internal.load.extraDirsهذه الأسبقية. - خطافات مساحة العمل:
<workspace>/hooks/(لكل وكيل، معطلة افتراضيًا حتى تُفعّل صراحة)
openclaw hooks enable <name>، أو ثبّت حزمة خطافات، أو اضبط hooks.internal.enabled=true للاشتراك. عندما تفعّل خطافًا مسمى واحدًا، لا يحمّل Gateway إلا معالج ذلك الخطاف؛ أما hooks.internal.enabled=true وأدلة الخطافات الإضافية والمعالجات القديمة فتشترك في الاكتشاف الواسع.
حزم الخطافات
حزم الخطافات هي حزم npm تصدّر الخطافات عبرopenclaw.hooks في package.json. ثبّتها باستخدام:
الخطافات المضمنة
| الخطاف | الأحداث | ما يفعله |
|---|---|---|
| session-memory | command:new, command:reset | يحفظ سياق الجلسة في <workspace>/memory/ |
| bootstrap-extra-files | agent:bootstrap | يحقن ملفات تمهيد إضافية من أنماط glob |
| command-logger | command | يسجل جميع الأوامر في ~/.openclaw/logs/commands.log |
| compaction-notifier | session:compact:before, session:compact:after | يرسل إشعارات دردشة مرئية عند بدء/انتهاء Compaction للجلسة |
| boot-md | gateway:startup | يشغّل BOOT.md عند بدء Gateway |
تفاصيل 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
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.handlers القديم مدعومًا للتوافق مع الإصدارات السابقة، لكن ينبغي للخطافات الجديدة استخدام النظام القائم على الاكتشاف.مرجع CLI
أفضل الممارسات
- أبقِ المعالجات سريعة. تعمل الخطافات أثناء معالجة الأوامر. شغّل الأعمال الثقيلة بأسلوب التشغيل والإهمال باستخدام
void processInBackground(event). - تعامل مع الأخطاء بسلاسة. لفّ العمليات الخطرة في try/catch؛ لا ترمِ استثناءات حتى تتمكن المعالجات الأخرى من العمل.
- رشّح الأحداث مبكرًا. ارجع فورًا إذا لم يكن نوع الحدث/الإجراء ذا صلة.
- استخدم مفاتيح أحداث محددة. فضّل
"events": ["command:new"]على"events": ["command"]لتقليل الحمل الزائد.
استكشاف الأخطاء وإصلاحها
لم يتم اكتشاف الخطاف
الخطاف غير مؤهل
الخطاف لا يُنفّذ
- تحقق من تمكين الخطاف:
openclaw hooks list - أعد تشغيل عملية Gateway حتى تعيد الخطافات التحميل.
- تحقق من سجلات Gateway:
./scripts/clawlog.sh | grep hook
ذو صلة
- مرجع CLI: الخطافات
- Webhooks
- خطافات Plugin — خطافات دورة حياة Plugin داخل العملية
- الإعدادات