الخطافات

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

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

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

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

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

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

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

بدء سريع

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

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

كتابة Hooks

بنية Hook

كل Hook هو دليل يحتوي على ملفين:

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 a reply on replyable surfaces  event.messages.push("Hook executed!");}; export default handler;

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

يتم تسليم event.messages تلقائيًا فقط على الأسطح القابلة للرد مثل command:* وmessage:received. أحداث دورة الحياة فقط مثل agent:bootstrap أو session:* أو gateway:* أو message:sent لا تحتوي على قناة رد وتتجاهل الرسائل المدفوعة.

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

أحداث الأوامر (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 التي تحتاج إلى فحص إجابة نهائية طبيعية وطلب تمريرة إضافية من الوكيل استخدام Hook plugin النمطي 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 plugins: Hooks مضمّنة داخل plugins مثبتة
3. Hooks المُدارة: ~/.openclaw/hooks/ (مثبتة بواسطة المستخدم، مشتركة عبر مساحات العمل). تشترك الأدلة الإضافية من hooks.internal.load.extraDirs في هذه الأسبقية.
4. Hooks مساحة العمل: <workspace>/hooks/ (لكل وكيل، معطلة افتراضيًا حتى يتم تمكينها صراحة)

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

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

حزم Hook

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

openclaw plugins install <path-or-spec>

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

Hooks المضمّنة

فعّل أي خطاف مرفق:

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 لتوليد slugs وصفية لأسماء الملفات باستخدام النموذج المكوّن. يتطلب تهيئة 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

يسجل كل أمر شرطة مائلة في ~/.openclaw/logs/commands.log.

تفاصيل compaction-notifier

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

تفاصيل boot-md

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

خطافات Plugin

يمكن لـ Plugins تسجيل خطافات typed عبر Plugin SDK لتكامل أعمق: اعتراض استدعاءات الأدوات، وتعديل الموجهات، والتحكم في تدفق الرسائل، والمزيد. استخدم خطافات 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 }      }    }  }}

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

{  "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 داخل العملية
• التهيئة