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

​
الخطافات

الخطافات هي نصوص برمجية صغيرة تعمل عندما يحدث شيء ما داخل Gateway. يتم اكتشافها تلقائيًا من الأدلة ويمكن فحصها باستخدام openclaw hooks. هناك نوعان من الخطافات في 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قبل أن يلخص الضغط السجل
session:compact:afterبعد اكتمال الضغط
session:patchعند تعديل خصائص الجلسة
agent:bootstrapقبل إدخال ملفات التمهيد الخاصة بمساحة العمل
gateway:startupبعد بدء القنوات وتحميل الخطافات
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 (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 (استخدم push لإرسالها إلى المستخدم) وcontext (بيانات خاصة بالحدث).

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

أحداث الأوامر (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). أحداث الرسائل (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. يمكن فقط للعملاء ذوي الامتيازات تشغيل أحداث التصحيح. أحداث الضغط: يتضمن session:compact:before القيمتين messageCount وtokenCount. ويضيف session:compact:after القيم compactedCount وsummaryLength وtokensBefore وtokensAfter.

​
اكتشاف الخطافات

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

​
حزم الخطافات

حزم الخطافات هي حزم 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
boot-mdgateway:startupيشغّل BOOT.md عند بدء gateway
لتفعيل أي خطاف مضمّن: 
openclaw hooks enable <hook-name>

​
تفاصيل session-memory

يستخرج آخر 15 رسالة مستخدم/مساعد، وينشئ slug وصفيًا لاسم الملف عبر LLM، ويحفظه في <workspace>/memory/YYYY-MM-DD-slug.md. يتطلب تكوين 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).

​
خطافات plugins

يمكن لـ plugins تسجيل خطافات من خلال Plugin SDK من أجل تكامل أعمق: اعتراض استدعاءات الأدوات، وتعديل المطالبات، والتحكم في تدفق الرسائل، وغير ذلك. يوفّر Plugin SDK عدد 28 خطافًا تغطي تحليل النموذج، ودورة حياة الوكيل، وتدفق الرسائل، وتنفيذ الأدوات، وتنسيق الوكلاء الفرعيين، ودورة حياة gateway. للاطلاع على المرجع الكامل لخطافات plugin بما في ذلك before_tool_call وbefore_agent_reply وbefore_install وجميع خطافات plugin الأخرى، راجع Plugin Architecture.

​
التكوين

{
  "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>

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

  • أبقِ المعالجات سريعة. تعمل الخطافات أثناء معالجة الأوامر. نفّذ الأعمال الثقيلة بشكل fire-and-forget باستخدام 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

​
ذو صلة