حلقة الوكيل

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

نقاط الدخول

• ‏Gateway RPC: ‏agent وagent.wait.
• ‏CLI: ‏openclaw agent.

تسلسل التشغيل

1. تتحقق واجهة RPC ‏agent من المعلمات، وتحلّ الجلسة (sessionKey/sessionId)، وتحفظ بيانات الجلسة الوصفية، وتُرجع { runId, acceptedAt } فورًا.
2. ينفّذ agentCommand الدورة: يحلّ النموذج + الإعدادات الافتراضية للتفكير/الإسهاب/التتبّع، ويحمّل لقطة Skills، ويستدعي runEmbeddedAgent، ويصدر حدثًا احتياطيًا لانتهاء دورة الحياة/خطئها إذا لم تكن الحلقة المضمّنة قد أصدرته بالفعل.
3. ‏runEmbeddedAgent: يُسلسل عمليات التشغيل عبر طوابير خاصة بكل جلسة وطوابير عامة، ويحلّ النموذج + ملف تعريف المصادقة، ويبني جلسة OpenClaw، ويشترك في أحداث وقت التشغيل، ويبث فروق المساعد/الأداة، ويفرض مهلة التشغيل (مع الإلغاء عند انتهائها)، ويُرجع الحمولات إلى جانب بيانات الاستخدام الوصفية. وبالنسبة إلى دورات خادم تطبيق Codex، يُلغي أيضًا دورة مقبولة تتوقف عن إحراز تقدم في خادم التطبيق قبل وقوع حدث نهائي.
4. يربط subscribeEmbeddedAgentSession أحداث وقت التشغيل بتدفق 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 مللي ثانية؛ تجاوز متغير البيئة OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS) قبل الإبلاغ بأن الجلسة مشغولة.

أقفال كتابة الجلسة غير قابلة لإعادة الدخول افتراضيًا. يجب على دالة مساعدة تتعمد تداخل الحصول على القفل نفسه مع الحفاظ على كاتب منطقي واحد الاشتراك باستخدام allowReentrant: true.

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

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

تجميع الموجّه

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

الخطافات

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

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

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

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

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

خطافات Plugin

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

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

• ‏before_tool_call: ‏{ block: true } نهائي ويوقف المعالجات ذات الأولوية الأدنى. ‏{ block: false } لا ينفّذ أي إجراء ولا يلغي حظرًا سابقًا.
• ‏before_install: دلالات النهاية/عدم الإجراء نفسها المذكورة أعلاه. استخدم security.installPolicy، وليس before_install، لقرارات السماح/الحظر لتثبيت مملوك للمشغّل التي يجب أن تشمل مسارات تثبيت CLI وتحديثه.
• ‏message_sending: ‏{ cancel: true } نهائي ويوقف المعالجات ذات الأولوية الأدنى. ‏{ cancel: false } لا ينفّذ أي إجراء ولا يلغي إلغاءً سابقًا.

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

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

البث

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

تنفيذ الأدوات

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

تشكيل الرد

تُجمّع الحمولات النهائية من نص المساعد (بالإضافة إلى الاستدلال الاختياري)، وملخصات الأدوات المضمّنة (عند تفعيل الإسهاب والسماح بها)، ونص خطأ المساعد عند حدوث خطأ في النموذج.

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

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

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

تدفقات الأحداث

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

يسقط Gateway أحداث دورة الحياة وبدء/نهاية الأدوات على سجل التدقيق المحدود والذي يحتوي على بيانات وصفية فقط. يسجل هذا الإسقاط المصدر ورموز النتائج دون نسخ الموجّهات أو الرسائل أو وسائط الأدوات أو نتائج الأدوات أو الأخطاء الخام خارج مسار النص المنقول/وقت التشغيل.

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

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

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

تشخيص الجلسات العالقة

عند تمكين التشخيص، يصنّف diagnostics.stuckSessionWarnMs (القيمة الافتراضية 120000 ms) جلسات processing الطويلة التي لم يُرصد فيها أي رد أو أداة أو حالة أو حظر أو تقدم في ACP:

• يُبلَّغ عن عمليات التشغيل المضمّنة النشطة واستدعاءات النماذج واستدعاءات الأدوات على أنها session.long_running. تظل استدعاءات النماذج الصامتة المملوكة session.long_running حتى diagnostics.stuckSessionAbortMs، كي لا تُصنَّف الجهات الموفرة البطيئة أو غير المتدفقة على أنها متوقفة مبكرًا جدًا.
• يُبلَّغ عن العمل النشط الذي لم يحرز تقدمًا حديثًا على أنه session.stalled. تتحول استدعاءات النماذج المملوكة إلى session.stalled عند عتبة الإجهاض أو بعدها؛ ولا يُخفى نشاط النماذج/الأدوات القديم غير المملوك باعتباره نشاطًا طويل التشغيل.
• يُحجز session.stuck لسجلات الجلسات القديمة القابلة للاسترداد، بما في ذلك الجلسات الخاملة الموضوعة في قائمة الانتظار التي تحتوي على نشاط قديم غير مملوك لنموذج/أداة.

تكون القيمة الافتراضية لـ diagnostics.stuckSessionAbortMs خمس دقائق على الأقل و3 أضعاف عتبة التحذير. تحرر معالجة سجلات الجلسات القديمة مسار الجلسة المتأثرة فور اجتياز بوابات الاسترداد؛ ولا تُصرَّف عمليات التشغيل المضمّنة المتوقفة عن طريق الإجهاض إلا بعد عتبة الإجهاض، بحيث يُستأنف العمل الموضوع في قائمة الانتظار دون قطع عمليات التشغيل البطيئة فحسب. يصدر الاسترداد نتائج مطلوبة/مكتملة منظَّمة؛ ولا تُعلَّم حالة التشخيص بأنها خاملة إلا إذا ظل جيل المعالجة نفسه هو الحالي، كما تتباعد تشخيصات session.stuck المتكررة تدريجيًا ما دامت الجلسة دون تغيير.

الحالات التي قد تنتهي فيها الأمور مبكرًا

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

ذو صلة

• الأدوات - أدوات الوكيل المتاحة
• الخطافات - نصوص برمجية قائمة على الأحداث تشغّلها أحداث دورة حياة الوكيل
• Compaction - كيفية تلخيص المحادثات الطويلة
• موافقات التنفيذ - بوابات الموافقة لأوامر الصدفة
• التفكير - ضبط مستوى التفكير/الاستدلال