حلقة الوكيل

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

نقاط الدخول

• بوابة RPC: agent و agent.wait.
• واجهة سطر الأوامر: أمر agent.

كيفية عملها (نظرة عامة)

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

الانتظار في قائمة + التزامن

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

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

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

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

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

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

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

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

الخطاطيف الداخلية (خطاطيف البوابة)

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

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

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

تعمل هذه داخل حلقة الوكيل أو خط أنابيب البوابة:

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

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

التدفق + الردود الجزئية

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

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

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

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

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

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

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

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

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

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

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

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

• agent.wait الافتراضي: 30 ثانية (فقط وقت الانتظار). المعامل timeoutMs يتجاوز ذلك.
• وقت تشغيل الوكيل: agents.defaults.timeoutSeconds الافتراضي 600 ثانية؛ يُفرض في مؤقت إيقاف runEmbeddedPiAgent.

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

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

وقت تشغيل الوكيلتوجيه النظام