حلقة الوكيل

فهم كيف يعالج OpenClaw الرسائل، من نقاط الدخول إلى بث الرد النهائي.

نقاط الدخول

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

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

التدفق الرئيسي:

  • يقوم RPC agent بالتحقق من المعاملات، حل الجلسة (sessionKey/sessionId)، حفظ metadata الجلسة، وإرجاع { runId, acceptedAt } فورًا
  • يقوم agentCommand بتشغيل الوكيل وبث الأحداث

agentCommand

  • حل النموذج والإعدادات الافتراضية للتفكير/التفصيل
  • تحميل snapshot المهارات
  • استدعاء runEmbeddedPiAgent (pi-agent-core runtime)
  • بث **lifecycle end/error** إذا لم تقم الحلقة المضمنة ببثه

runEmbeddedPiAgent

  • تسلسل التشغيل عبر طوابير الجلسة والطوابير العامة
  • حل النموذج وملف تعريف المصادقة وبناء جلسة pi
  • الاشتراك في أحداث pi وبث deltas المساعد/الأداة
  • فرض timeout → إيقاف التشغيل عند تجاوزه
  • إرجاع payloads + metadata الاستخدام

subscribeEmbeddedPiSession

يربط أحداث pi-agent-core بدفق agent في OpenClaw:

  • أحداث الأداة ⇒ stream: "tool"
  • deltas المساعد ⇒ stream: "assistant"
  • أحداث lifecycle ⇒ stream: "lifecycle" (phase: "start" | "end" | "error")

agent.wait

يستخدم waitForAgentJob:

  • ينتظر **lifecycle end/error** لـ runId
  • يرجع { status: ok|error|timeout, startedAt, endedAt, error? }

طابور الانتظار + التزامن

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

انظر طابور الأوامر.

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

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

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

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

انظر System prompt لما يراه النموذج.

نقاط الخطاف (أين نقاط الاعتراض)

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

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

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

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

انظر Streaming لسلوك التقسيم والرد بالكتل.

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

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

تنسيق الرد + القمع

يتم تجميع Payloads النهائية من:

  • نص المساعد (والتفكير الاختياري)
  • ملخصات الأدوات المضمنة (عندما verbose + مسموح)
  • نص خطأ المساعد عندما يحدث خطأ في النموذج

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

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

انظر Compaction لconveyor الضغط.

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

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

إدارة قنوات الدردشة

  • يتم تخزين deltas المساعد في رسائل delta للدردشة
  • يتم بث final للدردشة على **lifecycle end/error**

مهلات الانتظار

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

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

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