حلقة الوكيل

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

في 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 ويبث فروقات المساعد/الأداة
   • يفرض المهلة -> يلغي التشغيل إذا تم تجاوزها
   • بالنسبة إلى دورات خادم تطبيق Codex، يلغي دورة مقبولة تتوقف عن إنتاج تقدم خادم التطبيق قبل حدث نهائي
   • يعيد الحمولات + بيانات تعريف الاستخدام
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? }

# قوائم الانتظار + التزامن

• تُسلسل عمليات التشغيل لكل مفتاح جلسة (مسار الجلسة) واختياريًا عبر مسار عام.
• يمنع هذا سباقات الأدوات/الجلسات ويحافظ على اتساق سجل الجلسة.
• يمكن لقنوات المراسلة اختيار أوضاع قائمة الانتظار (جمع/توجيه/متابعة) التي تغذي نظام المسارات هذا. راجع قائمة انتظار الأوامر.
• كما تُحمى عمليات كتابة النص الكامل بقفل كتابة جلسة على ملف الجلسة. القفل مدرك للعملية ومبني على الملفات، لذلك يلتقط الكاتبين الذين يتجاوزون قائمة الانتظار داخل العملية أو يأتون من عملية أخرى. ينتظر كاتبو النص الكامل للجلسة مدة تصل إلى session.writeLock.acquireTimeoutMs قبل الإبلاغ عن الجلسة كمشغولة؛ الافتراضي هو 60000 مللي ثانية.
• أقفال كتابة الجلسة غير قابلة لإعادة الدخول افتراضيًا. إذا كان مساعد يتداخل عمدًا في اكتساب القفل نفسه مع الحفاظ على كاتب منطقي واحد، فيجب أن يشترك صراحةً عبر allowReentrant: true.

# تحضير الجلسة + مساحة العمل

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

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

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

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

لدى OpenClaw نظاما خطافات:

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

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

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

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

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

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

• before_model_resolve: يعمل قبل الجلسة (بلا messages) لتجاوز المزوّد/النموذج بشكل حتمي قبل حل النموذج.
• before_prompt_build: يعمل بعد تحميل الجلسة (مع messages) لحقن prependContext أو systemPrompt أو prependSystemContext أو appendSystemContext قبل إرسال الموجه. استخدم prependContext للنص الديناميكي لكل دورة، وحقول سياق النظام للإرشادات الثابتة التي يجب أن تبقى في مساحة موجه النظام.
• before_agent_start: خطاف توافق قديم قد يعمل في أي من المرحلتين؛ فضّل الخطافات الصريحة أعلاه.
• before_agent_reply: يعمل بعد الإجراءات المضمنة وقبل استدعاء LLM، ما يتيح لـ Plugin امتلاك الدورة وإرجاع رد اصطناعي أو إسكات الدورة بالكامل.
• agent_end: افحص قائمة الرسائل النهائية وبيانات تعريف التشغيل بعد الاكتمال.
• before_compaction / after_compaction: راقب دورات Compaction أو علّق عليها.
• before_tool_call / after_tool_call: اعترض معلمات/نتائج الأدوات.
• before_install: افحص نتائج الفحص المدمجة واختياريًا امنع تثبيت Skills أو Plugin.
• tool_result_persist: حوّل نتائج الأدوات بشكل متزامن قبل كتابتها إلى نص كامل لجلسة يملكها OpenClaw.
• 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 } بلا تأثير ولا يمسح إلغاءً سابقًا.

راجع خطافات Plugin لتفاصيل واجهة برمجة تطبيقات الخطاف والتسجيل.

قد تكيف أحزمة الاختبار هذه الخطافات بطرق مختلفة. يحافظ حزام خادم تطبيق Codex على خطافات OpenClaw Plugin كعقد توافق للأسطح الموثقة المعكوسة، بينما تبقى خطافات Codex الأصلية آلية Codex منخفضة المستوى منفصلة.

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

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

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

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

# تشكيل الرد + الإخماد

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

# Compaction + إعادة المحاولات

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

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

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

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

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

# المهل

• افتراضي agent.wait: 30 ثانية (الانتظار فقط). تتجاوز معلمة timeoutMs ذلك.
• وقت تشغيل الوكيل: افتراضي agents.defaults.timeoutSeconds هو 172800 ثانية (48 ساعة)؛ ويُفرض في مؤقت إلغاء runEmbeddedPiAgent.
• وقت تشغيل Cron: تملك Cron قيمة timeoutSeconds لدورة الوكيل المعزولة. يبدأ المجدول ذلك المؤقت عند بدء التنفيذ، ويلغي التشغيل الأساسي عند الموعد النهائي المضبوط، ثم يجري تنظيفًا محدودًا قبل تسجيل انتهاء المهلة بحيث لا تبقي جلسة فرعية قديمة المسار عالقًا.
• تشخيصات حيوية الجلسة: مع تفعيل التشخيصات، يصنف diagnostics.stuckSessionWarnMs جلسات processing الطويلة التي لا يوجد لها رد أو أداة أو حالة أو كتلة أو تقدم ACP مرصود. تُبلّغ عمليات التشغيل المضمنة النشطة واستدعاءات النموذج واستدعاءات الأدوات كـ session.long_running؛ ويُبلّغ العمل النشط بلا تقدم حديث كـ session.stalled؛ ويُحجز session.stuck لتدبير جلسة قديمة بلا عمل نشط. يحرر تدبير الجلسات القديمة مسار الجلسة المتأثر فورًا؛ ولا تُلغى وتُصفّى عمليات التشغيل المضمنة المتوقفة إلا بعد diagnostics.stuckSessionAbortMs (الافتراضي: 10 دقائق على الأقل و5 أضعاف عتبة التحذير) حتى يمكن للعمل في قائمة الانتظار أن يستأنف دون قطع عمليات بطيئة فحسب. يصدر الاسترداد نتائج منظمة مطلوبة/مكتملة، ولا تُعلّم الحالة التشخيصية كخاملة إلا إذا كان جيل المعالجة نفسه ما يزال هو الحالي. تتراجع تشخيصات session.stuck المتكررة بينما تبقى الجلسة دون تغيير.
• مهلة خمول النموذج: يلغي OpenClaw طلب نموذج عندما لا تصل أي أجزاء استجابة قبل نافذة الخمول. يمدد models.providers.<id>.timeoutSeconds حارس الخمول هذا للمزوّدين المحليين/المستضافين ذاتيًا البطيئين؛ وإلا يستخدم OpenClaw قيمة agents.defaults.timeoutSeconds عند ضبطها، مع حد أقصى افتراضي 120 ثانية. عمليات التشغيل المشغلة بواسطة Cron من دون مهلة نموذج أو وكيل صريحة تعطل حارس الخمول وتعتمد على مهلة Cron الخارجية.
• مهلة طلب HTTP للمزوّد: ينطبق models.providers.<id>.timeoutSeconds على عمليات جلب HTTP لنموذج ذلك المزوّد، بما في ذلك الاتصال، والترويسات، والجسم، ومهلة طلب SDK، ومعالجة إلغاء guarded-fetch الإجمالي، وحارس خمول تدفق النموذج. استخدم هذا للمزوّدين المحليين/المستضافين ذاتيًا البطيئين مثل Ollama قبل رفع مهلة وقت تشغيل الوكيل بأكمله.

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

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

# ذات صلة

• الأدوات — أدوات الوكيل المتاحة
• الخطافات — سكربتات مدفوعة بالأحداث تُشغّلها أحداث دورة حياة الوكيل
• Compaction — كيف تُلخّص المحادثات الطويلة
• موافقات Exec — بوابات الموافقة لأوامر الصدفة
• التفكير — تهيئة مستوى التفكير/الاستدلال