حلقة الوكيل

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

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

نقاط الدخول

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

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

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

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

• تُسلسل عمليات التشغيل لكل مفتاح جلسة (مسار الجلسة) واختياريًا عبر مسار عام.
• يمنع هذا تسابق الأدوات/الجلسات ويحافظ على اتساق سجل الجلسة.
• يمكن لقنوات المراسلة اختيار أوضاع قائمة الانتظار (steer/followup/collect/interrupt) التي تغذي نظام المسارات هذا. راجع قائمة انتظار الأوامر.
• كما تتم حماية كتابات السجل النصي بقفل كتابة جلسة على ملف الجلسة. القفل مدرك للعملية وقائم على الملفات، لذلك يلتقط الكتّاب الذين يتجاوزون قائمة الانتظار داخل العملية أو يأتون من عملية أخرى. ينتظر كتّاب سجل الجلسة النصي حتى 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: افحص مادة تثبيت Skill أو Plugin المرحلية بعد تشغيل سياسة تثبيت المشغّل، عندما تكون روابط Plugin محمّلة في عملية OpenClaw الحالية.
• 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 } بلا تأثير ولا يمسح حظرًا سابقًا.
• استخدم security.installPolicy، وليس before_install، لقرارات السماح/الحظر الخاصة بالتثبيت والمملوكة للمشغّل التي يجب أن تغطي مسارات تثبيت CLI والتحديث.
• message_sending: { cancel: true } نهائي ويوقف المعالجات ذات الأولوية الأدنى.
• message_sending: { cancel: false } بلا تأثير ولا يمسح إلغاءً سابقًا.

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

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

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

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

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

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

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

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

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

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

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

• lifecycle: يصدره subscribeEmbeddedAgentSession (وكاحتياطي بواسطة agentCommand)
• assistant: فروق متدفقة من بيئة تشغيل الوكيل
• tool: أحداث أدوات متدفقة من بيئة تشغيل الوكيل

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

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

المهلات

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

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

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

ذو صلة

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