​

حلقة الوكيل (OpenClaw)

حلقة الوكيل هي التشغيل «الحقيقي» الكامل للوكيل: الاستقبال → تجميع السياق → استدلال النموذج → تنفيذ الأدوات → بثّ الردود → الاستمرارية. وهي المسار المرجعي الذي يحوّل الرسالة إلى أفعال وردّ نهائي، مع الحفاظ على اتساق حالة الجلسة. في OpenClaw، تكون الحلقة تشغيلًا واحدًا متسلسلًا لكل جلسة، وتُصدر أحداث دورة الحياة وأحداث البث بينما يفكّر النموذج، ويستدعي الأدوات، ويبثّ المخرجات. يشرح هذا المستند كيف تُوصَل هذه الحلقة الأصيلة من البداية إلى النهاية.

​

نقاط الدخول

• Gateway RPC: ‏agent و agent.wait.
• CLI: الأمر agent.

​

كيف تعمل (على مستوى عالٍ)

1. يقوم ‏agent‏ RPC بالتحقق من المعلمات، وحلّ الجلسة (sessionKey/sessionId)، وتخزين بيانات الجلسة الوصفية، ويُعيد ‏{ runId, acceptedAt }‏ فورًا.
2. يقوم ‏agentCommand‏ بتشغيل الوكيل:
   • حلّ النموذج وإعدادات التفكير/الإسهاب الافتراضية
   • تحميل لقطة Skills
   • استدعاء ‏runEmbeddedPiAgent‏ (بيئة تشغيل pi-agent-core)
   • إصدار نهاية/خطأ دورة الحياة إذا لم تُصدر الحلقة المضمّنة واحدًا
3. يقوم ‏runEmbeddedPiAgent‏ بما يلي:
   • تسلسل التشغيلات عبر طوابير لكل جلسة + طابور عام
   • حلّ النموذج + ملف التفويض وبناء جلسة pi
   • الاشتراك في أحداث pi وبثّ فروق المساعد/الأداة
   • فرض مهلة -> عمليات الإجهاض إذا تم تجاوزها
   • إرجاع الحمولات + بيانات الاستخدام الوصفية
4. يقوم ‏subscribeEmbeddedPiSession‏ بربط أحداث pi-agent-core بتدفق ‏agent‏ في OpenClaw:
   • أحداث الأدوات ⇒ ‏stream: "tool"
   • فروق المساعد ⇒ ‏stream: "assistant"
   • أحداث دورة الحياة ⇒ ‏stream: "lifecycle"‏ (‏phase: "start" | "end" | "error"‏)
5. يستخدم ‏agent.wait‏ ‏waitForAgentJob‏:
   • ينتظر نهاية/خطأ دورة الحياة لـ ‏runId
   • يُعيد ‏{ status: ok|error|timeout, startedAt, endedAt, error? }

​

الاصطفاف + التزامن

• يتم تسلسل التشغيلات لكل مفتاح جلسة (مسار الجلسة) وبشكل اختياري عبر مسار عام.
• يمنع ذلك سباقات الأدوات/الجلسات ويحافظ على اتساق سجل الجلسة.
• يمكن لقنوات المراسلة اختيار أوضاع الاصطفاف (collect/steer/followup) التي تُغذّي نظام المسارات هذا. انظر Command Queue.

​

إعداد الجلسة + مساحة العمل

• يتم حلّ مساحة العمل وإنشاؤها؛ وقد تعيد التشغيلات المُقيَّدة بـ sandbox التوجيه إلى جذر مساحة عمل sandbox.
• يتم تحميل Skills (أو إعادة استخدامها من لقطة) وحقنها في البيئة والمطالبة.
• يتم حلّ ملفات التمهيد/السياق وحقنها في تقرير مطالبة النظام.
• يتم الحصول على قفل كتابة للجلسة؛ ويُفتح ‏SessionManager‏ ويُحضَّر قبل البث.

​

تجميع المطالبة + مطالبة النظام

• تُبنى مطالبة النظام من مطالبة OpenClaw الأساسية، ومطالبة Skills، وسياق التمهيد، والتجاوزات الخاصة بكل تشغيل.
• تُفرَض حدود خاصة بالنموذج واحتياطي الرموز للضغط.
• راجع System prompt لمعرفة ما يراه النموذج.

​

نقاط الربط (حيث يمكنك الاعتراض)

يمتلك OpenClaw نظامي ربط:

• الربط الداخلي (ربط Gateway): سكربتات مدفوعة بالأحداث للأوامر وأحداث دورة الحياة.
• ربط الإضافات: نقاط توسيع داخل دورة حياة الوكيل/الأداة وخط أنابيب Gateway.

​

الربط الداخلي (ربط Gateway)

• ‏agent:bootstrap‏: يعمل أثناء بناء ملفات التمهيد قبل تثبيت مطالبة النظام. استخدمه لإضافة/إزالة ملفات سياق التمهيد.
• ربط الأوامر: ‏/new‏، ‏/reset‏، ‏/stop‏، وأحداث أوامر أخرى (انظر مستند Hooks).

انظر Hooks للإعداد والأمثلة.

​

ربط الإضافات (دورة حياة الوكيل + Gateway)

تعمل هذه داخل حلقة الوكيل أو خط أنابيب Gateway:

• ‏before_agent_start‏: حقن السياق أو تجاوز مطالبة النظام قبل بدء التشغيل.
• ‏agent_end‏: فحص قائمة الرسائل النهائية وبيانات التشغيل الوصفية بعد الاكتمال.
• ‏before_compaction‏ / ‏after_compaction‏: مراقبة أو وسم دورات الضغط.
• ‏before_tool_call‏ / ‏after_tool_call‏: اعتراض معلمات/نتائج الأدوات.
• ‏tool_result_persist‏: تحويل نتائج الأدوات بشكل متزامن قبل كتابتها في نص الجلسة.
• ‏message_received‏ / ‏message_sending‏ / ‏message_sent‏: ربط الرسائل الواردة + الصادرة.
• ‏session_start‏ / ‏session_end‏: حدود دورة حياة الجلسة.
• ‏gateway_start‏ / ‏gateway_stop‏: أحداث دورة حياة Gateway.

انظر Plugins لواجهة برمجة الربط وتفاصيل التسجيل.

​

البثّ + الردود الجزئية

• تُبثّ فروق المساعد من pi-agent-core وتُصدَر كأحداث ‏assistant‏.
• يمكن لبثّ الكتل إصدار ردود جزئية إما على ‏text_end‏ أو ‏message_end‏.
• يمكن إصدار بثّ الاستدلال كتدفق منفصل أو كاستجابات كتل.
• راجع Streaming لسلوك التقسيم وردود الكتل.

​

تنفيذ الأدوات + أدوات المراسلة

• تُصدَر أحداث بدء/تحديث/نهاية الأداة على تدفق ‏tool‏.
• تُنقّى نتائج الأدوات من حيث الحجم وحمولات الصور قبل التسجيل/الإصدار.
• يتم تتبّع إرسال أدوات المراسلة لقمع تأكيدات المساعد المكررة.

​

تشكيل الرد + القمع

• تُركَّب الحمولات النهائية من:
  • نص المساعد (واختياريًا الاستدلال)
  • ملخصات الأدوات المضمّنة (عند الإسهاب + السماح)
  • نص خطأ المساعد عند حدوث خطأ في النموذج
• يُعامَل ‏NO_REPLY‏ كرمز صامت ويُرشَّح من الحمولات الصادرة.
• تُزال التكرارات الخاصة بأدوات المراسلة من قائمة الحمولات النهائية.
• إذا لم تبقَ حمولات قابلة للعرض وحدث خطأ أداة، يُصدَر رد احتياطي لخطأ الأداة (إلا إذا كانت أداة مراسلة قد أرسلت بالفعل ردًا مرئيًا للمستخدم).

​

تأكيد + إعادة المحاولات

• يُصدِر الضغط التلقائي أحداث تدفق ‏compaction‏ ويمكن أن يطلق إعادة محاولة.
• عند إعادة المحاولة، تُعاد تهيئة المخازن داخل الذاكرة وملخصات الأدوات لتجنب الإخراج المكرر.
• راجع Compaction لخط أنابيب الضغط.

​

تدفقات الأحداث (حاليًا)

• ‏lifecycle‏: يُصدَر بواسطة ‏subscribeEmbeddedPiSession‏ (وكاحتياط بواسطة ‏agentCommand‏)
• ‏assistant‏: فروق مُبثّة من pi-agent-core
• ‏tool‏: أحداث أدوات مُبثّة من pi-agent-core

​

التعامل مع قناة الدردشة

• تُخزَّن فروق المساعد مؤقتًا في رسائل دردشة ‏delta‏.
• تُصدَر رسالة دردشة ‏final‏ عند نهاية/خطأ دورة الحياة.

​

المهل الزمنية

• الافتراضي لـ ‏agent.wait‏: 30 ثانية (الانتظار فقط). تتجاوزها معلمة ‏timeoutMs‏.
• زمن تشغيل الوكيل: الافتراضي لـ ‏agents.defaults.timeoutSeconds‏ هو 600 ثانية؛ ويُفرَض في مؤقّت الإجهاض ‏runEmbeddedPiAgent‏.

​

أين يمكن أن تنتهي الأمور مبكرًا

• مهلة الوكيل (إجهاض)
• AbortSignal (إلغاء)
• انقطاع Gateway أو مهلة RPC
• مهلة ‏agent.wait‏ (انتظار فقط، لا يوقف الوكيل)