الخطافات

Hooks هي نصوص برمجية صغيرة تعمل داخل Gateway عند إطلاق أحداث الوكيل: أوامر مثل /new و/reset و/stop، وCompaction الجلسة، ودورة حياة Gateway، وتدفق الرسائل. تُكتشف من الأدلة وتُدار باستخدام openclaw hooks. لا يحمّل Gateway Hooks الداخلية إلا بعد تمكين Hooks أو تهيئة إدخال Hook واحد على الأقل، أو حزمة Hooks، أو معالج قديم، أو دليل Hooks إضافي.

يوجد نوعان من Hooks في OpenClaw:

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

يمكن أيضًا تضمين Hooks داخل Plugins. يعرض openclaw hooks list كلًا من Hooks المستقلة وتلك المُدارة بواسطة Plugins (وتظهر بصيغة plugin:<id>).

اختيار السطح المناسب

لدى OpenClaw عدة أسطح توسعة تبدو متشابهة، لكنها تحل مشكلات مختلفة:

استخدم Hooks الداخلية عندما تريد أتمتة تتصرف مثل تكامل صغير مثبّت. واستخدم Hooks المكتوبة بأنواع في Plugin عندما تحتاج إلى التحكم في دورة حياة وقت التشغيل.

البدء السريع

# سرد Hooks المتاحةopenclaw hooks list # تمكين Hookopenclaw hooks enable session-memory # التحقق من حالة Hookopenclaw hooks check # الحصول على معلومات مفصلةopenclaw hooks info session-memory

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

تشترك Hooks في مفتاح محدد من هذا الجدول، أو في اسم فئة مجرد (command أو session أو agent أو gateway أو message) لتلقي كل إجراء ضمن تلك الفئة. لا يطلق نواة OpenClaw أي شيء آخر، ولذلك يكون أي اسم آخر في الغالب خطأً مطبعيًا يترك Hook معطلة بصمت (ولا يمكن إطلاقه إلا بواسطة Plugin يطلق حدثًا مخصصًا). يسجل محمّل Hooks تحذيرًا لمثل هذه الأسماء (مثل command:nwe)، ويشير إليها openclaw hooks info <name>، ولذلك يمكن تشخيص Hook التي لا تعمل مطلقًا.

كتابة Hooks

بنية Hook

كل Hook عبارة عن دليل يحتوي على ملفين:

my-hook/├── HOOK.md          # البيانات الوصفية + التوثيق└── handler.ts       # تنفيذ المعالج

يمكن أن يكون ملف المعالج handler.ts أو handler.js أو index.ts أو index.js.

تنسيق HOOK.md

---name: my-hookdescription: "وصف موجز لما تفعله Hook هذه"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # Hook الخاصة بي يوضع التوثيق المفصل هنا.

حقول البيانات الوصفية (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 a reply on replyable surfaces  event.messages.push("Hook executed!");}; export default handler;

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

لا تُسلَّم السلاسل النصية المدفوعة إلى event.messages مرة أخرى إلى الدردشة إلا مع command:new وcommand:reset (وتُوجَّه كرد إلى المحادثة الأصلية) ومع session:compact:before وsession:compact:after (وتُرسل كإشعارات بحالة Compaction). تتجاهل جميع الأحداث الأخرى الرسائل المدفوعة، بما فيها command:stop وmessage:* وagent:bootstrap وsession:patch وgateway:*.

أبرز عناصر سياق الأحداث

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

أحداث الأوامر (command:stop): context.sessionEntry وcontext.sessionId وcontext.commandSource وcontext.senderId.

أحداث الرسائل (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، بالإضافة إلى context.error عند فشل الإرسال.

أحداث الرسائل (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 التي تحتاج إلى فحص إجابة نهائية طبيعية ومطالبة الوكيل بتمرير إضافي أن تستخدم Hook المكتوبة بأنواع before_agent_finalize بدلًا من ذلك. راجع Hooks الخاصة بـ Plugin.

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

استخدم gateway:pre-restart لإشعارات إعادة التشغيل القصيرة بينما لا تزال القنوات متاحة:

  const execFileAsync = promisify(execFile); export default async function handler(event) {  if (event.type !== "gateway" || event.action !== "pre-restart") {    return;  }   const restartInSeconds = Math.ceil(event.context.restartExpectedMs / 1000);  await execFileAsync("openclaw", [    "system",    "event",    "--mode",    "now",    "--text",    `Gateway restarting in ~${restartInSeconds}s (${event.context.reason}). Checkpoint now.`,  ]);}

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

اكتشاف Hooks

تُكتشف Hooks من أربعة مصادر:

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

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

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

حزم Hooks

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

openclaw plugins install <path-or-spec>

مواصفات Npm مخصصة للسجل فقط (اسم الحزمة + إصدار دقيق اختياري أو وسم توزيع). تُرفض مواصفات Git/URL/الملفات ونطاقات semver. الأمران الأقدم openclaw hooks install وopenclaw hooks update اسمان مستعاران مهملان للأمرين openclaw plugins install وopenclaw plugins update.

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

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

openclaw hooks enable <hook-name>

تفاصيل session-memory

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

إعداد bootstrap-extra-files

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

تُقبل patterns وfiles كاسمين مستعارين لـpaths. تُحل المسارات نسبةً إلى مساحة العمل ويجب أن تبقى داخلها. لا تُحمّل إلا أسماء ملفات التمهيد الأساسية المعروفة (AGENTS.md، وSOUL.md، وTOOLS.md، وIDENTITY.md، وUSER.md، وHEARTBEAT.md، وBOOTSTRAP.md، وMEMORY.md).

تفاصيل command-logger

يسجّل كل أمر يبدأ بشرطة مائلة كسطر JSON (الطابع الزمني، والإجراء، ومفتاح الجلسة، ومعرّف المرسل، والمصدر) في ~/.openclaw/logs/commands.log.

تفاصيل compaction-notifier

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

تفاصيل boot-md

يشغّل BOOT.md عند بدء Gateway لكل نطاق وكيل مضبوط، إذا كان الملف موجودًا في مساحة العمل المحلولة لذلك الوكيل.

خطافات Plugin

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

تختلف الخطافات الداخلية التي تديرها برامج Plugin: فهي تشارك في نظام أحداث الأوامر/دورة الحياة العام في هذه الصفحة، وتظهر في openclaw hooks list بصيغة plugin:<id>. استخدمها للآثار الجانبية والتوافق مع حزم الخطافات، وليس للبرمجيات الوسيطة المرتبة أو بوابات السياسات.

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

الإعداد

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

تستوفي قيم البيئة الخاصة بكل خطاف عمليات التحقق من أهلية requires.env للخطاف (إلى جانب بيئة العملية)، ويمكن للمعالجات قراءتها من إدخال إعداد الخطاف الخاص بها:

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

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

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

مرجع CLI

# سرد جميع الخطافات (أضف --eligible أو --verbose أو --json)openclaw hooks list # عرض معلومات مفصلة عن خطافopenclaw hooks info <hook-name> # عرض ملخص الأهليةopenclaw hooks check # تمكين/تعطيلopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

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

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

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

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

# التحقق من بنية الدليلls -la ~/.openclaw/hooks/my-hook/# ينبغي أن يعرض: HOOK.md, handler.ts # سرد جميع الخطافات المكتشفةopenclaw hooks list

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

openclaw hooks info my-hook

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

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

1. تحقق من تمكين الخطاف: openclaw hooks list
2. أعد تشغيل عملية Gateway حتى يُعاد تحميل الخطافات.
3. تحقق من سجلات Gateway: openclaw logs --follow | grep -i hook

ذو صلة

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