hooks

إدارة خطافات الأحداث (hooks): الاستماع للأحداث وتنفيذ إجراءات تلقائية.

ما هي الخطافات (Hooks)؟

الخطافات هي نصوص أو أوامر تُنفذ تلقائيًا عند حدوث أحداث معينة في OpenClaw. مثل: رسالة واردة، جلسة جديدة، تحديث النظام، إلخ.

الأوامر

عرض الخطافات

openclaw hooks list
openclaw hooks show

إضافة خطاف

openclaw hooks add message.received --script ./notify.sh
openclaw hooks add session.start --command "echo 'New session started'"
openclaw hooks add agent.error --message "Admin: Error occurred" --to admin

حذف خطاف

openclaw hooks delete <hook-id>
openclaw hooks delete --event message.received --all

الأحداث المتاحة

  • message.received - رسالة واردة
  • message.sent - رسالة صادرة
  • session.start - جلسة جديدة
  • session.end - نهاية جلسة
  • agent.start - بدء وكيل
  • agent.stop - إيقاف وكيل
  • agent.error - خطأ في الوكيل
  • gateway.start - بدء Gateway
  • gateway.stop - إيقاف Gateway
  • channel.connected - اتصال قناة
  • channel.disconnected - انقطاع قناة
  • system.update - تحديث النظام

أنواع الإجراءات

1. تشغيل نص برمجي (Script)

openclaw hooks add message.received --script ./on-message.sh

# مثال على on-message.sh:
#!/bin/bash
echo "Received: $HOOK_MESSAGE_TEXT"
echo "From: $HOOK_MESSAGE_FROM"
# ... إجراءات مخصصة

2. تنفيذ أمر

openclaw hooks add gateway.start --command "systemctl start nginx"

3. إرسال رسالة

openclaw hooks add agent.error --message "Error: {{error}}" --to admin

4. استدعاء webhook

openclaw hooks add message.received --webhook https://example.com/webhook

المتغيرات البيئية

عند تنفيذ خطاف، تُمرر معلومات الحدث عبر متغيرات بيئية:

HOOK_EVENT=message.received
HOOK_TIMESTAMP=2026-02-07T00:00:00Z
HOOK_MESSAGE_TEXT="Hello"
HOOK_MESSAGE_FROM="+33612345678"
HOOK_MESSAGE_CHANNEL=telegram
HOOK_SESSION_ID=abc123
# ... والمزيد حسب نوع الحدث

الفلاتر

يمكنك تصفية الأحداث حسب معايير محددة:

# فقط رسائل من قناة معينة
openclaw hooks add message.received --filter channel=telegram --script ./notify.sh

# فقط أخطاء من وكيل معين
openclaw hooks add agent.error --filter agent=main --message "Main agent error" --to admin

# رسائل تحتوي على كلمة مفتاحية
openclaw hooks add message.received --filter text~=urgent --webhook https://alerts.example.com

الخيارات

  • --script - مسار نص برمجي للتنفيذ
  • --command - أمر shell للتنفيذ
  • --message - رسالة للإرسال
  • --to - المستلم (لإرسال الرسائل)
  • --webhook - URL webhook للاستدعاء
  • --filter - معايير الفلترة
  • --async - تنفيذ غير متزامن (لا ينتظر الانتهاء)
  • --timeout - مهلة التنفيذ (بالثواني)

أمان:

الخطافات تُنفذ بأذونات OpenClaw. تأكد من أن النصوص البرمجية آمنة وموثوقة. تجنب تنفيذ أوامر من مدخلات مستخدم غير موثوق.

أمثلة الاستخدام

إشعار عند رسالة جديدة

openclaw hooks add message.received --script ./notify.sh

نسخ احتياطي عند بدء Gateway

openclaw hooks add gateway.start --command "tar -czf ~/backup/openclaw-$(date +%Y%m%d).tar.gz ~/.openclaw"

تنبيه عند خطأ

openclaw hooks add agent.error --message "⚠️ Agent error: {{error}}" --to admin --channel telegram

التخزين

الخطافات تُخزن في ~/.openclaw/hooks.json. يمكنك تحرير هذا الملف مباشرة أو استخدام الأوامر.

انظر أيضًا