الانتقال إلى المحتوى الرئيسي

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.

Hooks هي سكربتات صغيرة تعمل عند حدوث شيء داخل Gateway. يمكن اكتشافها من الأدلة وفحصها باستخدام openclaw hooks. لا يحمّل Gateway الخطافات الداخلية إلا بعد تمكين الخطافات أو تكوين إدخال خطاف واحد على الأقل، أو حزمة خطافات، أو معالج قديم، أو دليل خطافات إضافي. يوجد نوعان من الخطافات في OpenClaw:
  • الخطافات الداخلية (هذه الصفحة): تعمل داخل Gateway عند إطلاق أحداث الوكيل، مثل /new أو /reset أو /stop أو أحداث دورة الحياة.
  • Webhooks: نقاط نهاية HTTP خارجية تتيح للأنظمة الأخرى تشغيل العمل في OpenClaw. راجع Webhooks.
يمكن أيضًا تضمين الخطافات داخل plugins. يعرض openclaw hooks list كلًا من الخطافات المستقلة والخطافات التي تديرها plugins.

البدء السريع

# List available hooks
openclaw hooks list

# Enable a hook
openclaw hooks enable session-memory

# Check hook status
openclaw hooks check

# Get detailed information
openclaw hooks info session-memory

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

الحدثوقت إطلاقه
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تسليم رسالة صادرة

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

بنية الخطاف

كل خطاف هو دليل يحتوي على ملفين:
my-hook/
├── HOOK.md          # Metadata + documentation
└── handler.ts       # Handler implementation

تنسيق HOOK.md

---
name: my-hook
description: "Short description of what this hook does"
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

Detailed documentation goes here.
حقول البيانات الوصفية (metadata.openclaw):
الحقلالوصف
emojiرمز تعبيري للعرض في CLI
eventsمصفوفة من الأحداث التي يجب الاستماع إليها
exportالتصدير المسمى المراد استخدامه (الافتراضي هو "default")
osالمنصات المطلوبة (مثل ["darwin", "linux"])
requiresمسارات bins أو anyBins أو env أو config المطلوبة
alwaysتجاوز فحوصات الأهلية (قيمة منطقية)
installطرق التثبيت

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

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.

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

الخطافالأحداثما يفعله
session-memorycommand:new, command:resetيحفظ سياق الجلسة في <workspace>/memory/
bootstrap-extra-filesagent:bootstrapيحقن ملفات تمهيد إضافية من أنماط glob
command-loggercommandيسجل جميع الأوامر في ~/.openclaw/logs/commands.log
compaction-notifiersession:compact:before, session:compact:afterيرسل إشعارات دردشة مرئية عند بدء/انتهاء Compaction للجلسة
boot-mdgateway:startupيشغّل BOOT.md عند بدء Gateway
فعّل أي خطاف مضمن:
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"]
      }
    }
  }
}
ما يزال تنسيق إعدادات مصفوفة hooks.internal.handlers القديم مدعومًا للتوافق مع الإصدارات السابقة، لكن ينبغي للخطافات الجديدة استخدام النظام القائم على الاكتشاف.

مرجع CLI

# List all hooks (add --eligible, --verbose, or --json)
openclaw hooks list

# Show detailed info about a hook
openclaw hooks info <hook-name>

# Show eligibility summary
openclaw hooks check

# Enable/disable
openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>

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

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

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

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

# Verify directory structure
ls -la ~/.openclaw/hooks/my-hook/
# Should show: HOOK.md, handler.ts

# List all discovered hooks
openclaw hooks list

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

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

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

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

ذو صلة