​

الوكلاء الفرعيون

​

أمر الشرطة المائلة

• /subagents list
• /subagents kill <id|#|all>
• /subagents log <id|#> [limit] [tools]
• /subagents info <id|#>
• /subagents send <id|#> <message>
• /subagents steer <id|#> <message>
• /subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]

• /focus <subagent-label|session-key|session-id|session-label>
• /unfocus
• /agents
• /session idle <duration|off>
• /session max-age <duration|off>

​

سلوك الإنشاء

• أمر الإنشاء غير حاجب؛ إذ يعيد معرّف تشغيل فورًا.
• عند الإكمال، يعلن الوكيل الفرعي رسالة ملخص/نتيجة مرة أخرى إلى قناة دردشة الطالب.
• يكون تسليم الإكمال قائمًا على الدفع. بعد الإنشاء، لا تجرِ استقصاءً لـ /subagents list أو sessions_list أو sessions_history في حلقة لمجرد انتظار انتهائه؛ افحص الحالة عند الطلب فقط من أجل التصحيح أو التدخل.
• عند الإكمال، يغلق OpenClaw بأفضل جهد علامات تبويب/عمليات المتصفح المتتبعة التي فتحها ذلك الوكيل الفرعي قبل متابعة تدفق تنظيف الإعلان.
• بالنسبة إلى الإنشاءات اليدوية، يكون التسليم مرنًا:
  • يحاول OpenClaw أولًا التسليم المباشر عبر agent باستخدام مفتاح idempotency ثابت.
  • إذا فشل التسليم المباشر، فإنه يعود إلى توجيه الطابور.
  • إذا لم يكن توجيه الطابور متاحًا أيضًا، تُعاد محاولة الإعلان مع تراجع أسي قصير قبل التخلي النهائي.
• يحتفظ تسليم الإكمال بمسار الطالب الذي تم حله:
  • تفوز مسارات الإكمال المرتبطة بالخيط أو المحادثة عند توفرها
  • إذا كان أصل الإكمال يوفر قناة فقط، يملأ OpenClaw الهدف/الحساب المفقودين من المسار المحلول لجلسة الطالب (lastChannel / lastTo / lastAccountId) بحيث يستمر التسليم المباشر في العمل
• إن التسليم إلى جلسة الطالب عند الإكمال هو سياق داخلي مولَّد وقت التشغيل (وليس نصًا من تأليف المستخدم) ويتضمن:
  • Result (أحدث نص رد assistant ظاهر، وإلا أحدث نص مُنقّى لـ tool/toolResult)
  • Status (completed successfully / failed / timed out / unknown)
  • إحصاءات وقت تشغيل/رموز مدمجة
  • تعليمة تسليم تخبر وكيل الطالب بإعادة الصياغة بصوت المساعد المعتاد (وليس تمرير البيانات الوصفية الداخلية الخام)
• تتجاوز --model و--thinking القيم الافتراضية لذلك التشغيل المحدد.
• استخدم info/log لفحص التفاصيل والمخرجات بعد الإكمال.
• يعمل /subagents spawn في وضع اللقطة الواحدة (mode: "run"). أما جلسات الارتباط الدائم بالخيط، فاستخدم sessions_spawn مع thread: true وmode: "session".
• بالنسبة إلى جلسات ACP harness ‏(Codex وClaude Code وGemini CLI)، استخدم sessions_spawn مع runtime: "acp" وراجع وكلاء ACP.

• موازاة أعمال “البحث / المهمة الطويلة / الأداة البطيئة” دون حجب التشغيل الرئيسي.
• إبقاء الوكلاء الفرعيين معزولين افتراضيًا (فصل الجلسات + العزل الاختياري).
• إبقاء سطح الأدوات صعب الإساءة: لا تحصل الوكلاء الفرعيون على أدوات الجلسات افتراضيًا.
• دعم عمق تعشيش قابل للضبط لأنماط المنسّق.

​

الأداة

• يبدأ تشغيل وكيل فرعي (deliver: false، المسار العام: subagent)
• ثم يشغّل خطوة إعلان وينشر رد الإعلان إلى قناة دردشة الطالب
• النموذج الافتراضي: يرث من المستدعي إلا إذا عيّنت agents.defaults.subagents.model (أو agents.list[].subagents.model لكل وكيل)؛ وتظل sessions_spawn.model الصريحة لها الأولوية.
• التفكير الافتراضي: يرث من المستدعي إلا إذا عيّنت agents.defaults.subagents.thinking (أو agents.list[].subagents.thinking لكل وكيل)؛ وتظل sessions_spawn.thinking الصريحة لها الأولوية.
• المهلة الافتراضية للتشغيل: إذا تم حذف sessions_spawn.runTimeoutSeconds، يستخدم OpenClaw القيمة agents.defaults.subagents.runTimeoutSeconds عند تعيينها؛ وإلا يعود إلى 0 (من دون مهلة).

• task (مطلوب)
• label? (اختياري)
• agentId? (اختياري؛ الإنشاء تحت معرّف وكيل آخر إذا كان مسموحًا)
• model? (اختياري؛ يتجاوز نموذج الوكيل الفرعي؛ يتم تخطي القيم غير الصالحة ويعمل الوكيل الفرعي على النموذج الافتراضي مع تحذير في نتيجة الأداة)
• thinking? (اختياري؛ يتجاوز مستوى التفكير لتشغيل الوكيل الفرعي)
• runTimeoutSeconds? (القيمة الافتراضية هي agents.defaults.subagents.runTimeoutSeconds عند تعيينها، وإلا 0؛ وعند التعيين، يُجهض تشغيل الوكيل الفرعي بعد N ثانية)
• thread? (الافتراضي false؛ وعند true يطلب ربط خيط القناة لهذه الجلسة الفرعية)
• mode? (run|session)
  • الافتراضي هو run
  • إذا كانت thread: true وتم حذف mode، تصبح القيمة الافتراضية session
  • يتطلب mode: "session" القيمة thread: true
• cleanup? (delete|keep، الافتراضي keep)
• sandbox? (inherit|require، الافتراضي inherit؛ وترفض require الإنشاء ما لم يكن وقت تشغيل الطفل الهدف معزولًا)
• لا يقبل sessions_spawn معلمات تسليم القنوات (target، channel، to، threadId، replyTo، transport). بالنسبة إلى التسليم، استخدم message/sessions_send من التشغيل المُنشأ.

​

الجلسات المرتبطة بالخيوط

​

القنوات الداعمة للخيوط

• Discord (وهي حاليًا القناة الوحيدة المدعومة): تدعم جلسات وكلاء فرعيين ثابتة مرتبطة بالخيط (sessions_spawn مع thread: true)، وعناصر تحكم يدوية بالخيوط (/focus و/unfocus و/agents و/session idle و/session max-age)، ومفاتيح المهايئ channels.discord.threadBindings.enabled وchannels.discord.threadBindings.idleHours وchannels.discord.threadBindings.maxAgeHours وchannels.discord.threadBindings.spawnSubagentSessions.

1. أنشئ باستخدام sessions_spawn مع thread: true (واختياريًا mode: "session").
2. ينشئ OpenClaw خيطًا أو يربطه بهدف تلك الجلسة في القناة النشطة.
3. تُوجَّه الردود ورسائل المتابعة في ذلك الخيط إلى الجلسة المرتبطة.
4. استخدم /session idle لفحص/تحديث إلغاء التركيز التلقائي عند عدم النشاط واستخدم /session max-age للتحكم في الحد الصلب.
5. استخدم /unfocus لفك الارتباط يدويًا.

• يربط /focus <target> الخيط الحالي (أو ينشئ واحدًا) بهدف وكيل فرعي/جلسة.
• يزيل /unfocus الربط للخيط المرتبط الحالي.
• يسرد /agents التشغيلات النشطة وحالة الربط (thread:<id> أو unbound).
• يعمل /session idle و/session max-age فقط للخيوط المركّزة المرتبطة.

• الافتراضي العام: session.threadBindings.enabled وsession.threadBindings.idleHours وsession.threadBindings.maxAgeHours
• يكون تجاوز القناة ومفاتيح الربط التلقائي عند الإنشاء خاصة بالمهايئ. راجع القنوات الداعمة للخيوط أعلاه.

• agents.list[].subagents.allowAgents: قائمة بمعرّفات الوكلاء التي يمكن استهدافها عبر agentId ‏(["*"] للسماح بأي منها). الافتراضي: وكيل الطالب فقط.
• agents.defaults.subagents.allowAgents: قائمة السماح الافتراضية لوكيل الهدف والمستخدمة عندما لا يعيّن وكيل الطالب subagents.allowAgents الخاص به.
• حارس وراثة العزل: إذا كانت جلسة الطالب معزولة، يرفض sessions_spawn الأهداف التي ستعمل من دون عزل.
• agents.defaults.subagents.requireAgentId / agents.list[].subagents.requireAgentId: عند true، تُحظر استدعاءات sessions_spawn التي تحذف agentId (لفرض اختيار ملف تعريف صريح). الافتراضي: false.

• استخدم agents_list لمعرفة معرّفات الوكلاء المسموح بها حاليًا لـ sessions_spawn.

• تُؤرشف جلسات الوكلاء الفرعيين تلقائيًا بعد agents.defaults.subagents.archiveAfterMinutes (الافتراضي: 60).
• تستخدم الأرشفة sessions.delete وتعيد تسمية النص الحواري إلى *.deleted.<timestamp> (في المجلد نفسه).
• يؤدي cleanup: "delete" إلى الأرشفة فورًا بعد الإعلان (مع الإبقاء على النص الحواري عبر إعادة التسمية).
• الأرشفة التلقائية تتم بأفضل جهد؛ وتُفقد المؤقتات المعلّقة إذا أُعيد تشغيل البوابة.
• لا تؤدي runTimeoutSeconds إلى الأرشفة التلقائية؛ فهي توقف التشغيل فقط. وتبقى الجلسة حتى الأرشفة التلقائية.
• تنطبق الأرشفة التلقائية بالتساوي على الجلسات ذات العمق 1 و2.
• تنظيف المتصفح منفصل عن تنظيف الأرشفة: تُغلق علامات التبويب/العمليات المتتبعة بأفضل جهد عند انتهاء التشغيل، حتى إذا تم الاحتفاظ بسجل النص الحواري/الجلسة.

​

الوكلاء الفرعيون المتداخلون

​

كيفية التمكين

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // السماح للوكلاء الفرعيين بإنشاء أطفال (الافتراضي: 1)
        maxChildrenPerAgent: 5, // الحد الأقصى للأطفال النشطين لكل جلسة وكيل (الافتراضي: 5)
        maxConcurrent: 8, // الحد الأقصى العام للتزامن في المسار (الافتراضي: 8)
        runTimeoutSeconds: 900, // المهلة الافتراضية لـ sessions_spawn عند الحذف (0 = بلا مهلة)
      },
    },
  },
}

​

مستويات العمق

​

سلسلة الإعلان

1. ينتهي العامل ذو العمق 2 ← ويعلن إلى الأصل ذي العمق 1 (المنسّق)
2. يتلقى المنسّق ذو العمق 1 الإعلان، ويولّف النتائج، وينتهي ← ثم يعلن إلى الرئيسي
3. يتلقى الوكيل الرئيسي الإعلان ويسلّمه إلى المستخدم

• ابدأ عمل الطفل مرة واحدة وانتظر أحداث الإكمال بدلًا من بناء حلقات استقصاء حول sessions_list أو sessions_history أو /subagents list أو أوامر exec مع sleep.
• إذا وصل حدث إكمال طفل بعد أن أرسلت الإجابة النهائية بالفعل، فالمتابعة الصحيحة هي الرمز الصامت الدقيق NO_REPLY / no_reply.

​

سياسة الأدوات حسب العمق

• يُكتب الدور ونطاق التحكم في بيانات الجلسة الوصفية وقت الإنشاء. وهذا يمنع مفاتيح الجلسات المسطحة أو المستعادة من استعادة امتيازات المنسّق عن طريق الخطأ.
• العمق 1 (منسّق، عند maxSpawnDepth >= 2): يحصل على sessions_spawn وsubagents وsessions_list وsessions_history حتى يتمكن من إدارة أطفاله. وتظل أدوات الجلسة/النظام الأخرى مرفوضة.
• العمق 1 (طرفي، عند maxSpawnDepth == 1): لا توجد أدوات جلسات (السلوك الافتراضي الحالي).
• العمق 2 (عامل طرفي): لا توجد أدوات جلسات — ويُرفض sessions_spawn دائمًا عند العمق 2. ولا يمكنه إنشاء أطفال إضافيين.

​

حد الإنشاء لكل وكيل

​

الإيقاف المتسلسل

• يؤدي /stop في الدردشة الرئيسية إلى إيقاف جميع الوكلاء ذوي العمق 1 وينتقل ذلك تسلسليًا إلى أطفالهم ذوي العمق 2.
• يؤدي /subagents kill <id> إلى إيقاف وكيل فرعي محدد وينتقل ذلك تسلسليًا إلى أطفاله.
• يؤدي /subagents kill all إلى إيقاف جميع الوكلاء الفرعيين للطالب وينتقل ذلك تسلسليًا.

​

المصادقة

• مفتاح جلسة الوكيل الفرعي هو agent:<agentId>:subagent:<uuid>.
• يُحمَّل مخزن المصادقة من agentDir الخاص بذلك الوكيل.
• تُدمج ملفات تعريف مصادقة الوكيل الرئيسي باعتبارها احتياطيًا؛ وتتجاوز ملفات تعريف الوكيل ملفات تعريف الرئيسي عند التعارض.

​

الإعلان

• تعمل خطوة الإعلان داخل جلسة الوكيل الفرعي (وليس جلسة الطالب).
• إذا رد الوكيل الفرعي بالنص الدقيق ANNOUNCE_SKIP، فلن يُنشر شيء.
• إذا كان أحدث نص مساعد هو الرمز الصامت الدقيق NO_REPLY / no_reply، فسيتم كتم مخرجات الإعلان حتى إذا وُجد تقدم ظاهر سابق.
• بخلاف ذلك يعتمد التسليم على عمق الطالب:
  • تستخدم جلسات الطالب ذات المستوى الأعلى استدعاء agent لاحقًا مع تسليم خارجي (deliver=true)
  • تتلقى جلسات الوكلاء الفرعيين المتداخلة للطالب حقن متابعة داخليًا (deliver=false) حتى يتمكن المنسّق من توليف نتائج الأطفال داخل الجلسة
  • إذا اختفت جلسة وكيل فرعي متداخلة للطالب، يعود OpenClaw إلى طالب تلك الجلسة عند توفره
• بالنسبة إلى جلسات الطالب ذات المستوى الأعلى، يحل التسليم المباشر في وضع الإكمال أولًا أي مسار محادثة/خيط مرتبط وأي تجاوز hook، ثم يملأ حقول هدف القناة المفقودة من المسار المخزن لجلسة الطالب. وهذا يُبقي عمليات الإكمال على الدردشة/الموضوع الصحيحين حتى عندما لا يحدد أصل الإكمال سوى القناة.
• يقتصر تجميع إكمالات الأطفال على تشغيل الطالب الحالي عند بناء نتائج الإكمال المتداخلة، مما يمنع تسرب مخرجات أطفال قديمة من تشغيل سابق إلى الإعلان الحالي.
• تحافظ ردود الإعلان على توجيه الخيط/الموضوع عند توفره في مهايئات القنوات.
• يُطبَّع سياق الإعلان إلى كتلة أحداث داخلية مستقرة:
  • المصدر (subagent أو cron)
  • مفتاح/معرّف جلسة الطفل
  • نوع الإعلان + تسمية المهمة
  • سطر حالة مشتق من ناتج وقت التشغيل (success أو error أو timeout أو unknown)
  • محتوى النتيجة المختار من أحدث نص مساعد ظاهر، وإلا أحدث نص مُنقّى لـ tool/toolResult
  • تعليمة متابعة تصف متى يجب الرد ومتى يجب البقاء صامتًا
• لا يُستنتج Status من مخرجات النموذج؛ بل يأتي من إشارات ناتج وقت التشغيل.
• عند انتهاء المهلة، إذا لم يحصل الطفل إلا على استدعاءات أدوات، يمكن للإعلان أن يختزل ذلك السجل إلى ملخص قصير للتقدم الجزئي بدلًا من إعادة تشغيل مخرجات الأدوات الخام.

• وقت التشغيل (مثل runtime 5m12s)
• استخدام الرموز (الإدخال/الإخراج/الإجمالي)
• التكلفة المقدّرة عند ضبط تسعير النموذج (models.providers.*.models[].cost)
• sessionKey وsessionId ومسار النص الحواري (حتى يتمكن الوكيل الرئيسي من جلب السجل عبر sessions_history أو فحص الملف على القرص)
• البيانات الوصفية الداخلية مخصصة للتنسيق فقط؛ ويجب إعادة كتابة الردود الموجهة للمستخدم بصوت مساعد طبيعي.

• يُطبَّع استرجاع المساعد أولًا:
  • تُزال وسوم التفكير
  • تُزال كتل البنية <relevant-memories> / <relevant_memories>
  • تُزال كتل حمولات XML النصية العادية لاستدعاءات الأدوات مثل <tool_call>...</tool_call>، و<function_call>...</function_call>، و<tool_calls>...</tool_calls>، و <function_calls>...</function_calls>، بما في ذلك الحمولات المقتطعة التي لا تُغلق بشكل صحيح
  • تُزال بنية استدعاءات/نتائج الأدوات المخفّضة وعلامات السياق التاريخي
  • تُزال رموز التحكم بالنموذج المسرّبة مثل <|assistant|>، وغيرها من رموز ASCII من الشكل <|...|>، والمتغيرات كاملة العرض <｜...｜>
  • يُزال XML المشوّه لاستدعاءات أدوات MiniMax
• يُحجب النص الشبيه ببيانات الاعتماد/الرموز
• قد تُقتطع الكتل الطويلة
• قد تُسقط السجلات الكبيرة جدًا الصفوف الأقدم أو تستبدل صفًا كبيرًا جدًا بالقيمة [sessions_history omitted: message too large]
• يكون فحص النص الحواري الخام على القرص هو الاحتياطي عندما تحتاج إلى النص الحواري الكامل بايتًا لبايت

​

سياسة الأدوات (أدوات الوكلاء الفرعيين)

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // الرفض له الأولوية
        deny: ["gateway", "cron"],
        // إذا تم تعيين allow، فإنه يصبح السماح فقط (ويظل deny له الأولوية)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

​

التزامن

• اسم المسار: subagent
• التزامن: agents.defaults.subagents.maxConcurrent (الافتراضي 8)

​

الإيقاف

• يؤدي إرسال /stop في دردشة الطالب إلى إجهاض جلسة الطالب وإيقاف أي تشغيلات وكلاء فرعيين نشطة تم إنشاؤها منها، مع الانتقال تسلسليًا إلى الأطفال المتداخلين.
• يؤدي /subagents kill <id> إلى إيقاف وكيل فرعي محدد وينتقل ذلك تسلسليًا إلى أطفاله.

​

القيود

• الإعلان الرجوعي للوكيل الفرعي يتم بأفضل جهد. إذا أُعيد تشغيل البوابة، فستُفقد أعمال “الإعلان رجوعًا” المعلقة.
• لا تزال الوكلاء الفرعيون تشترك في موارد عملية البوابة نفسها؛ فاعتبر maxConcurrent صمام أمان.
• يكون sessions_spawn دائمًا غير حاجب: إذ يعيد { status: "accepted", runId, childSessionKey } فورًا.
• لا يحقن سياق الوكيل الفرعي إلا AGENTS.md + TOOLS.md (من دون SOUL.md أو IDENTITY.md أو USER.md أو HEARTBEAT.md أو BOOTSTRAP.md).
• الحد الأقصى لعمق التداخل هو 5 (maxSpawnDepth ضمن المجال 1–5). ويُوصى بالعمق 2 لمعظم حالات الاستخدام.
• يحد maxChildrenPerAgent من عدد الأطفال النشطين لكل جلسة (الافتراضي: 5، المجال: 1–20).