​

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

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

​

نقاط الدخول

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

​

كيف يعمل (نظرة عالية المستوى)

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

​

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

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

​

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

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

​

تجميع الموجه + موجه النظام

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

​

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

يحتوي OpenClaw على نظامي خطافات:

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

​

الخطافات الداخلية (خطافات Gateway)

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

راجع الخطافات للإعداد والأمثلة.

​

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

تعمل هذه داخل حلقة الوكيل أو مسار Gateway:

• before_model_resolve: يعمل قبل الجلسة (من دون messages) لتجاوز المزوّد/النموذج بشكل حتمي قبل حل النموذج.
• before_prompt_build: يعمل بعد تحميل الجلسة (مع messages) لحقن prependContext أو systemPrompt أو prependSystemContext أو appendSystemContext قبل إرسال الموجه. استخدم prependContext للنص الديناميكي لكل دور، واستخدم حقول سياق النظام للإرشادات الثابتة التي ينبغي أن تبقى ضمن مساحة موجه النظام.
• before_agent_start: خطاف توافق قديم قد يعمل في أي من المرحلتين؛ يُفضّل استخدام الخطافات الصريحة أعلاه.
• before_agent_reply: يعمل بعد الإجراءات المضمنة وقبل استدعاء LLM، مما يتيح لإضافة أن تستحوذ على الدور وتعيد ردًا اصطناعيًا أو تكتم الدور بالكامل.
• agent_end: يفحص قائمة الرسائل النهائية وبيانات التشغيل الوصفية بعد الاكتمال.
• before_compaction / after_compaction: يراقب أو يعلّق على دورات الضغط.
• before_tool_call / after_tool_call: يعترض معلمات/نتائج الأداة.
• before_install: يفحص نتائج المسح المضمّنة ويمكنه اختياريًا حظر تثبيت Skill أو إضافة.
• tool_result_persist: يغيّر نتائج الأدوات بشكل متزامن قبل كتابتها في سجل الجلسة.
• message_received / message_sending / message_sent: خطافات الرسائل الواردة + الصادرة.
• session_start / session_end: حدود دورة حياة الجلسة.
• gateway_start / gateway_stop: أحداث دورة حياة Gateway.

قواعد قرار الخطاف لحواجز الخروج/الأدوات:

• before_tool_call: ‏{ block: true } نهائي ويوقف المعالجات ذات الأولوية الأقل.
• before_tool_call: ‏{ block: false } لا يؤدي لأي إجراء ولا يزيل حظرًا سابقًا.
• before_install: ‏{ block: true } نهائي ويوقف المعالجات ذات الأولوية الأقل.
• before_install: ‏{ block: false } لا يؤدي لأي إجراء ولا يزيل حظرًا سابقًا.
• message_sending: ‏{ cancel: true } نهائي ويوقف المعالجات ذات الأولوية الأقل.
• message_sending: ‏{ cancel: false } لا يؤدي لأي إجراء ولا يزيل إلغاءً سابقًا.

راجع خطافات الإضافات للتعرف على واجهة API الخاصة بالخطافات وتفاصيل التسجيل.

​

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

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

​

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

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

​

تشكيل الرد + منعه

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

​

الضغط + إعادة المحاولة

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

​

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

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

​

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

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

​

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

• القيمة الافتراضية لـ agent.wait: ‏30 ثانية (للانتظار فقط). يمكن للمعلمة timeoutMs تجاوزها.
• وقت تشغيل الوكيل: القيمة الافتراضية لـ agents.defaults.timeoutSeconds هي 172800 ثانية (48 ساعة)؛ ويتم فرضها في runEmbeddedPiAgent عبر مؤقت إجهاض.
• مهلة خمول LLM: ‏agents.defaults.llm.idleTimeoutSeconds تُجهض طلب النموذج عندما لا تصل أي أجزاء استجابة قبل انتهاء نافذة الخمول. اضبطها صراحةً للنماذج المحلية البطيئة أو مزوّدي الاستدلال/استدعاءات الأدوات؛ واضبطها على 0 لتعطيلها. إذا لم يتم ضبطها، يستخدم OpenClaw قيمة agents.defaults.timeoutSeconds عند تهيئتها، وإلا فسيستخدم 120 ثانية. تؤدي عمليات التشغيل المحفّزة بواسطة Cron التي لا تحتوي على مهلة LLM أو مهلة وكيل صريحة إلى تعطيل مراقب الخمول والاعتماد على المهلة الخارجية الخاصة بـ Cron.

​

المواضع التي قد ينتهي فيها التنفيذ مبكرًا

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

​

ذو صلة

• الأدوات — أدوات الوكيل المتاحة
• الخطافات — نصوص برمجية مدفوعة بالأحداث تُشغَّل بواسطة أحداث دورة حياة الوكيل
• الضغط — كيفية تلخيص المحادثات الطويلة
• موافقات التنفيذ — بوابات الموافقة لأوامر الصدفة
• التفكير — إعداد مستوى التفكير/الاستدلال