تنسيق الوكلاء

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

الوكلاء الفرعيون هي عمليات وكيل خلفية يتم إنشاؤها من عملية وكيل موجودة. تعمل في جلستها الخاصة (agent::subagent:) وعند انتهائها، تعلن عن نتيجتها مرة أخرى إلى قناة الدردشة للمطلب.

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

استخدم /subagents لفحص أو التحكم في عمليات الوكلاء الفرعيين للـ الجلسة الحالية:

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

أوامر التحكم في ربط الخيوط: تعمل هذه الأوامر على القنوات التي تدعم ربط الخيوط المستمر. انظر القنوات الداعمة للخيوط أدناه.

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

يظهر /subagents info بيانات وصفية عن التشغيل (الحالة، الطوابع الزمنية، معرف الجلسة، مسار النص، التنظيف).

سلوك الإنشاء

يبدأ /subagents spawn وكيلًا فرعيًا في الخلفية كأمر مستخدم، وليس كوسيلة إرسال داخلية، ويرسل تحديث إتمام نهائي واحدًا مرة أخرى إلى دردشة المطلب عند انتهاء التشغيل.

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

الأهداف الأساسية:

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

ملاحظة التكلفة: لكل وكيل فرعي سياقه الخاص واستخدام الرموز. للمهام الثقيلة أو المتكررة، اضبط نموذجًا أرخص للوكلاء الفرعيين واحتفظ بوكيلك الرئيسي على نموذج أعلى جودة. يمكنك تكوين هذا عبر agents.defaults.subagents.model أو التجاوزات لكل وكيل.

الأداة

استخدم sessions_spawn:

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

مفاتيح التبديل التكوينية:

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

انظر مرجع التكوين و أوامر الشرطة المائلة للحصول على تفاصيل المحول الحالية. قائمة السماح:

• agents.list[].subagents.allowAgents: قائمة معرفات الوكلاء التي يمكن استهدافها عبر agentId (["*"] للسماح بأي). الافتراضي: فقط وكيل المطلب.
• حارس وراثة الحماية: إذا كانت جلسة المطلب محمية، يرفض sessions_spawn الأهداف التي ستعمل بدون حماية.

الاكتشاف:

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

الأرشفة التلقائية:

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

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

افتراضيًا، لا يمكن للوكلاء الفرعيين إنشاء وكلاء فرعيين خاصين بهم (maxSpawnDepth: 1). يمكنك تمكين مستوى واحد من التداخل عن طريق تعيين maxSpawnDepth: 2، مما يسمح بـ نمط المنسق: رئيسي → وكيل فرعي منسق → وكلاء فرعيون فرعيون عاملون.

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

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

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

العمق	شكل مفتاح الجلسة	الدور	هل يمكن الإنشاء؟
0	agent::main	الوكيل الرئيسي	دائمًا
1	agent::subagent:	الوكيل الفرعي (المنسق عندما يُسمح بالعمق 2)	فقط إذا كان maxSpawnDepth >= 2
2	agent::subagent::subagent:	الوكيل الفرعي الفرعي (عامل ورقة)	أبدًا

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

تتدفق النتائج مرة أخرى لأعلى السلسلة:

1. ينتهي العامل في العمق-2 → يعلن إلى والده (المنسق في العمق-1)
2. يتلقى المنسق في العمق-1 الإعلان، يجمع النتائج، ينتهي → يعلن إلى الرئيسي
3. يتلقى الوكيل الرئيسي الإعلان ويقوم بتسليمه إلى المستخدم

كل مستوى يرى إعلانات من أطفاله المباشرين فقط.

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

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

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

يمكن لكل جلسة وكيل (في أي عمق) أن يكون لديها على الأكثر maxChildrenPerAgent (الافتراضي: 5) طفل نشط في وقت واحد. هذا يمنع التفرع الجامح من منسق واحد.

التوقف المتتالي

يتوقف إيقاف منسق في العمق-1 تلقائيًا جميع أطفاله في العمق-2:

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

المصادقة

يتم حل مصادقة الوكيل الفرعي بواسطة معرف الوكيل، وليس بنوع الجلسة:

• مفتاح جلسة الوكيل الفرعي هو agent::subagent:.
• يتم تحميل مخزن المصادقة من agentDir لذلك الوكيل.
• يتم دمج ملفات تعريف مصادقة الوكيل الرئيسي كـ تراجع؛ تتعارض ملفات تعريف الوكيل مع ملفات التعريف الرئيسية في حالات التعارض.

ملاحظة: الدمج إضافي، لذا تكون ملفات التعريف الرئيسية متاحة دائمًا كتراجعات. المصادقة المعزولة بالكامل لكل وكيل غير مدعومة بعد.

الإعلان

يبلغ الوكلاء الفرعيون مرة أخرى عبر خطوة إعلان:

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

تتضمن حمولات الإعلان سطر إحصائيات في النهاية (حتى عند التغليف):

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

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

افتراضيًا، يحصل الوكلاء الفرعيون على جميع الأدوات باستثناء أدوات الجلسة وأدوات النظام:

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

عندما يكون maxSpawnDepth >= 2، يتلقى وكلاء المنسق الفرعيون في العمق-1 بالإضافة إلى ذلك sessions_spawn, subagents, sessions_list, و sessions_history حتى يتمكنوا من إدارة أطفالهم. تجاوز عبر التكوين:

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // deny يفوز
        deny: ["gateway", "cron"],
        // إذا تم تعيين allow، تصبح allow-only (لا يزال deny يفوز)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

التزامن

يستخدم الوكلاء الفرعيون مسار قائمة انتظار داخلية مخصص:

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

الإيقاف

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

القيود

• إعلان الوكيل الفرعي هو أفضل جهد. إذا أعيد تشغيل البوابة، تضيع أعمال "الإعلان مرة أخرى" المعلقة.
• لا يزال الوكلاء الفرعيون يشاركون نفس موارد عملية البوابة؛ عالج 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).

إرسال الوكيلوكلاء ACP