​

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

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

​

نقاط الدخول

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

​

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

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

​

الاصطفاف + التوازي

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

​

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

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

​

تجميع prompt + system prompt

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

​

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

يحتوي OpenClaw على نظامي hook:

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

​

hooks داخلية (Gateway hooks)

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

راجع Hooks للحصول على الإعداد والأمثلة.

​

Plugin hooks (دورة حياة الوكيل + Gateway)

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

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

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

• 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 } بلا تأثير ولا تلغي إلغاءً سابقًا.

راجع Plugin hooks للاطلاع على API الخاص بالـ hook وتفاصيل التسجيل.

​

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

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

​

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

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

​

تشكيل الرد + الكبت

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

​

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

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

​

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

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

​

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

• يتم تخزين فروق المساعد مؤقتًا في رسائل delta للدردشة.
• يتم إصدار final للدردشة عند lifecycle end/error.

​

المهلات

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

​

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

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

​

ذو صلة

• الأدوات — أدوات الوكيل المتاحة
• Hooks — برامج نصية مدفوعة بالأحداث يتم تشغيلها بواسطة أحداث دورة حياة الوكيل
• Compaction — كيف يتم تلخيص المحادثات الطويلة
• Exec Approvals — بوابات الموافقة لأوامر shell
• Thinking — إعداد مستوى thinking/reasoning