Agent coordination

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

الوكلاء الفرعيون هم تشغيلات وكلاء في الخلفية تُنشأ من تشغيل وكيل موجود. تعمل في جلستها الخاصة (agent:<agentId>:subagent:<uuid>) و، عند الانتهاء، تعلن نتيجتها مرة أخرى إلى قناة دردشة الطالب. يُتتبَّع كل تشغيل لوكيل فرعي بوصفه مهمة خلفية.

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

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

أمر Slash

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

text
/subagents list/subagents log <id|#> [limit] [tools]/subagents info <id|#>

يعرض /subagents info بيانات تعريف التشغيل (الحالة، الطوابع الزمنية، معرّف الجلسة، مسار النص المسجل، التنظيف). استخدم sessions_history لعرض استرجاع محدود ومرشّح للسلامة؛ افحص مسار النص المسجل على القرص عندما تحتاج إلى النص المسجل الكامل الخام.

عناصر التحكم في ربط الخيوط

تعمل هذه الأوامر على القنوات التي تدعم ربط الخيوط المستمر. راجع القنوات الداعمة للخيوط أدناه.

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

سلوك الإنشاء

يبدأ الوكلاء وكلاء فرعيين في الخلفية باستخدام sessions_spawn. تعود اكتمالات الوكلاء الفرعيين كأحداث داخلية لجلسة الأصل؛ ويقرر وكيل الأصل/الطالب ما إذا كان يلزم تحديث مرئي للمستخدم.

Non-blocking, push-based completion
  • sessions_spawn غير حاجب؛ يعيد معرّف تشغيل فورا.
  • عند الاكتمال، يبلّغ الوكيل الفرعي مرة أخرى إلى جلسة الأصل/الطالب.
  • يجب على دورات الوكيل التي تحتاج إلى نتائج الأبناء استدعاء sessions_yield بعد إنشاء العمل المطلوب. ينهي ذلك الدورة الحالية ويتيح وصول أحداث الاكتمال كالرسالة التالية المرئية للنموذج.
  • الاكتمال قائم على الدفع. بعد الإنشاء، لا تستطلع /subagents list أو sessions_list أو sessions_history في حلقة لمجرد انتظار انتهائه؛ افحص الحالة عند الطلب فقط لرؤية التصحيح.
  • مخرجات الابن هي تقرير/دليل لوكيل الطالب كي يركّبه. وليست نص تعليمات من إنشاء المستخدم، ولا يمكنها تجاوز سياسة النظام أو المطور أو المستخدم.
  • عند الاكتمال، يغلق OpenClaw بأفضل جهد علامات تبويب/عمليات المتصفح المتتبعة التي فتحتها جلسة ذلك الوكيل الفرعي قبل استمرار تدفق تنظيف الإعلان.
Completion delivery
  • يسلّم OpenClaw الاكتمالات مرة أخرى إلى جلسة الطالب عبر دورة agent بمفتاح ثبات مستقر.
  • إذا كان تشغيل الطالب لا يزال نشطا، يحاول OpenClaw أولا إيقاظ/توجيه ذلك التشغيل بدلا من بدء مسار رد مرئي ثان.
  • إذا تعذر إيقاظ طالب نشط، يعود OpenClaw إلى تسليم إلى وكيل الطالب بسياق الاكتمال نفسه بدلا من إسقاط الإعلان.
  • يكمّل تسليم الأصل الناجح تسليم الوكيل الفرعي حتى عندما يقرر الأصل أن تحديثا مرئيا للمستخدم غير مطلوب.
  • لا تحصل الوكلاء الفرعية الأصلية على أداة الرسائل. فهي تعيد نص مساعد عاديا إلى وكيل الأصل/الطالب؛ الردود المرئية للبشر يملكها نهج التسليم العادي لوكيل الأصل/الطالب.
  • إذا تعذر استخدام التسليم المباشر، يعود إلى توجيه الطابور.
  • إذا ظل توجيه الطابور غير متاح، تعاد محاولة الإعلان بتراجع أسي قصير قبل التخلي النهائي.
  • يحتفظ تسليم الاكتمال بمسار الطالب المحلول: تفوز مسارات الاكتمال المرتبطة بالخيط أو بالمحادثة عند توفرها؛ إذا كان أصل الاكتمال لا يوفر إلا قناة، يملأ OpenClaw الهدف/الحساب المفقود من المسار المحلول لجلسة الطالب (lastChannel / lastTo / lastAccountId) كي يظل التسليم المباشر يعمل.
Completion handoff metadata

تسليم الاكتمال إلى جلسة الطالب هو سياق داخلي مولّد وقت التشغيل (وليس نصا أنشأه المستخدم) ويتضمن:

  • Result — أحدث نص رد assistant مرئي من الابن. لا تُرقّى مخرجات tool/toolResult إلى نتائج الابن. لا تعيد التشغيلات الفاشلة نهائيا استخدام نص الرد الملتقط.
  • Statuscompleted; ready for parent review / failed / timed out / unknown.
  • إحصاءات مدمجة لوقت التشغيل/الرموز.
  • تعليمة مراجعة تطلب من وكيل الطالب التحقق من النتيجة قبل تقرير ما إذا كانت المهمة الأصلية قد اكتملت.
  • إرشاد متابعة يطلب من وكيل الطالب متابعة المهمة أو تسجيل متابعة عندما تترك نتيجة الابن مزيدا من الإجراء.
  • تعليمة تحديث نهائية لمسار عدم وجود إجراء إضافي، مكتوبة بصوت المساعد العادي من دون تمرير بيانات تعريف داخلية خام.
Modes and ACP runtime
  • يتجاوز --model و--thinking الإعدادات الافتراضية لذلك التشغيل المحدد.
  • استخدم info/log لفحص التفاصيل والمخرجات بعد الاكتمال.
  • للجلسات المستمرة المرتبطة بالخيط، استخدم sessions_spawn مع thread: true وmode: "session".
  • إذا كانت قناة الطالب لا تدعم ربط الخيوط، فاستخدم mode: "run" بدلا من إعادة محاولة تركيبات مرتبطة بالخيط مستحيلة.
  • لجلسات حزمة ACP (Claude Code أو Gemini CLI أو OpenCode أو Codex ACP/acpx الصريح)، استخدم sessions_spawn مع runtime: "acp" عندما تعلن الأداة ذلك وقت التشغيل. راجع نموذج تسليم ACP عند تصحيح الاكتمالات أو حلقات وكيل إلى وكيل. عندما يكون Plugin codex مفعلا، ينبغي لتَحكّم دردشة/خيط Codex تفضيل /codex ... على ACP ما لم يطلب المستخدم ACP/acpx صراحة.
  • يخفي OpenClaw runtime: "acp" حتى يتم تفعيل ACP، ولا يكون الطالب معزولا في صندوق رمل، ويتم تحميل Plugin خلفية مثل acpx. يتوقع runtime: "acp" معرّف حزمة ACP خارجية، أو إدخالا في agents.list[] مع runtime.type="acp"؛ استخدم وقت تشغيل الوكيل الفرعي الافتراضي لوكلاء تكوين OpenClaw العاديين من agents_list.

أوضاع السياق

تبدأ الوكلاء الفرعية الأصلية معزولة ما لم يطلب المستدعي صراحة تفريع النص المسجل الحالي.

الوضع متى تستخدمه السلوك
isolated بحث جديد، تنفيذ مستقل، عمل أداة بطيء، أو أي شيء يمكن شرحه بإيجاز في نص المهمة ينشئ نصا مسجلا نظيفا للابن. هذا هو الافتراضي ويُبقي استخدام الرموز أقل.
fork عمل يعتمد على المحادثة الحالية، أو نتائج أدوات سابقة، أو تعليمات دقيقة موجودة بالفعل في نص سجل الطالب يفرّع نص سجل الطالب إلى جلسة الابن قبل بدء الابن.

استخدم fork باقتصاد. فهو لتفويض حساس للسياق، وليس بديلا عن كتابة مطالبة مهمة واضحة.

الأداة: sessions_spawn

تبدأ تشغيل وكيل فرعي مع deliver: false على مسار subagent العام، ثم تشغّل خطوة إعلان وتنشر رد الإعلان إلى قناة دردشة الطالب.

يعتمد التوفر على سياسة الأدوات الفعلية للمستدعي. يعرّض ملفا التعريف coding و full sessions_spawn افتراضيا. لا يعرّضه ملف التعريف messaging؛ أضف tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"] أو استخدم tools.profile: "coding" للوكلاء الذين ينبغي أن يفوضوا العمل. يمكن لسياسات السماح/المنع الخاصة بالقناة/المجموعة، والمزود، وصندوق الرمل، ولكل وكيل أن تظل تزيل الأداة بعد مرحلة ملف التعريف. استخدم /tools من الجلسة نفسها لتأكيد قائمة الأدوات الفعلية.

الإعدادات الافتراضية:

  • النموذج: ترث الوكلاء الفرعية الأصلية المستدعي ما لم تضبط agents.defaults.subagents.model (أو agents.list[].subagents.model لكل وكيل). تستخدم عمليات إنشاء وقت تشغيل ACP نموذج الوكيل الفرعي المكوّن نفسه عند وجوده؛ وإلا تحتفظ حزمة ACP بافتراضيها الخاص. يظل sessions_spawn.model الصريح هو الفائز.
  • التفكير: ترث الوكلاء الفرعية الأصلية المستدعي ما لم تضبط agents.defaults.subagents.thinking (أو agents.list[].subagents.thinking لكل وكيل). تطبق عمليات إنشاء وقت تشغيل ACP أيضا agents.defaults.models["provider/model"].params.thinking للنموذج المحدد. يظل sessions_spawn.thinking الصريح هو الفائز.
  • مهلة التشغيل: يستخدم OpenClaw agents.defaults.subagents.runTimeoutSeconds عند ضبطه؛ وإلا يعود إلى 0 (بلا مهلة). لا يقبل sessions_spawn تجاوزات مهلة لكل استدعاء.
  • تسليم المهمة: تتلقى الوكلاء الفرعية الأصلية المهمة المفوضة في أول رسالة [Subagent Task] مرئية لها. تحمل مطالبة نظام الوكيل الفرعي قواعد وقت التشغيل وسياق التوجيه، لا نسخة مخفية مكررة من المهمة.

تتضمن عمليات إنشاء الوكيل الفرعي الأصلية المقبولة بيانات تعريف النموذج الابن المحلولة في نتيجة الأداة: يحتوي resolvedModel على مرجع النموذج المطبق، ويحتوي resolvedProvider على بادئة المزود عندما يكون للمرجع واحدة.

وضع مطالبة التفويض

يتحكم agents.defaults.subagents.delegationMode في إرشاد المطالبة فقط؛ ولا يغير سياسة الأدوات أو يفرض التفويض.

  • suggest (افتراضي): احتفظ بدفعة المطالبة القياسية لاستخدام الوكلاء الفرعيين للأعمال الأكبر أو الأبطأ.
  • prefer: اطلب من الوكيل الرئيسي أن يبقى سريع الاستجابة وأن يفوض أي شيء أكثر تعقيدا من رد مباشر عبر sessions_spawn.

تستخدم التجاوزات لكل وكيل agents.list[].subagents.delegationMode.

json5
{  agents: {    defaults: {      subagents: {        delegationMode: "prefer",        maxConcurrent: 4,      },    },    list: [      {        id: "coordinator",        subagents: { delegationMode: "prefer" },      },    ],  },}

معاملات الأداة

taskstringrequired

وصف المهمة للوكيل الفرعي.

taskNamestring

معرّف مستقر اختياري لتعريف فرع محدد في مخرجات الحالة اللاحقة. يجب أن يطابق [a-z][a-z0-9_-]{0,63} ولا يمكن أن يكون من الأهداف المحجوزة مثل last أو all.

labelstring

تسمية اختيارية قابلة للقراءة البشرية.

agentIdstring

أنشئ تحت معرّف وكيل آخر مكوّن عندما يسمح subagents.allowAgents بذلك.

cwdstring

دليل عمل اختياري للمهمة لتشغيل الفرع. لا تزال الوكلاء الفرعية الأصلية تحمّل ملفات التمهيد من مساحة عمل الوكيل الهدف؛ لا يغيّر cwd إلا المكان الذي تنفذ فيه أدوات وقت التشغيل وأطر CLI العمل المفوّض.

runtime"subagent" | "acp"default: subagent

acp مخصص فقط لأطر ACP الخارجية (claude، droid، gemini، opencode، أو Codex ACP/acpx المطلوب صراحة) ولإدخالات agents.list[] التي يكون runtime.type فيها هو acp.

resumeSessionIdstring

خاص بـ ACP فقط. يستأنف جلسة إطار ACP موجودة عندما يكون runtime: "acp"؛ ويتم تجاهله عند إنشاء وكلاء فرعية أصلية.

streamTo"parent"

خاص بـ ACP فقط. يبث مخرجات تشغيل ACP إلى الجلسة الأصل عندما يكون runtime: "acp"؛ احذفه عند إنشاء وكلاء فرعية أصلية.

modelstring

تجاوز نموذج الوكيل الفرعي. تُتخطى القيم غير الصالحة ويعمل الوكيل الفرعي على النموذج الافتراضي مع تحذير في نتيجة الأداة.

thinkingstring

تجاوز مستوى التفكير لتشغيل الوكيل الفرعي.

threadbooleandefault: false

عندما تكون true، يطلب ربط سلسلة القناة لهذه الجلسة الفرعية.

mode"run" | "session"default: run

إذا كانت thread: true وجرى حذف mode، يصبح الافتراضي session. يتطلب mode: "session" أن تكون thread: true. إذا كان ربط السلسلة غير متاح لقناة الطالب، فاستخدم mode: "run" بدلاً من ذلك.

cleanup"delete" | "keep"default: keep

تؤرشف "delete" فورًا بعد الإعلان (مع الاستمرار في الاحتفاظ بالنص عبر إعادة التسمية).

sandbox"inherit" | "require"default: inherit

يرفض require الإنشاء ما لم يكن وقت تشغيل الفرع الهدف معزولاً في sandbox.

context"isolated" | "fork"default: isolated

يفرّع fork النص الحالي للطالب إلى جلسة الفرع. للوكلاء الفرعية الأصلية فقط. عمليات الإنشاء المرتبطة بسلسلة تكون افتراضيًا fork؛ وعمليات الإنشاء غير المرتبطة بسلسلة تكون افتراضيًا isolated.

أسماء المهام والاستهداف

taskName هو معرّف موجه للنموذج للتنسيق، وليس مفتاح جلسة. استخدمه لأسماء الفروع المستقرة مثل review_subagents، linux_validation، أو docs_update عندما قد يحتاج المنسق إلى فحص ذلك الفرع لاحقًا.

يقبل حل الهدف مطابقات taskName الدقيقة والبادئات غير الملتبسة. تقتصر المطابقة على نافذة الهدف النشطة/الحديثة نفسها المستخدمة بواسطة أهداف /subagents المرقمة، لذلك لا يجعل الفرع المكتمل القديم إعادة استخدام معرّف ما ملتبسة. إذا تشارك فرعان نشطان أو حديثان القيمة نفسها لـ taskName، يكون الهدف ملتبسًا؛ استخدم فهرس القائمة أو مفتاح الجلسة أو معرّف التشغيل بدلاً من ذلك.

الأهداف المحجوزة last وall ليست قيم taskName صالحة لأن لها بالفعل معاني تحكم.

الأداة: sessions_yield

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

sessions_yield هي بدائية الانتظار. لا تستبدلها بحلقات استطلاع على subagents أو sessions_list أو sessions_history أو sleep في shell أو استطلاع العمليات لمجرد اكتشاف إكمال الفرع.

استخدم sessions_yield فقط عندما تتضمن قائمة الأدوات الفعلية للجلسة هذه الأداة. قد تعرض بعض ملفات تعريف الأدوات الدنيا أو المخصصة sessions_spawn و subagents دون عرض sessions_yield؛ في هذه الحالة، لا تخترع حلقة استطلاع لمجرد انتظار الإكمال.

عند وجود فروع نشطة، يحقن OpenClaw كتلة مطالبة مضغوطة ومنشأة من وقت التشغيل بعنوان Active Subagents في الأدوار العادية حتى يستطيع الطالب رؤية جلسات الفروع الحالية، ومعرّفات التشغيل، والحالات، والتسميات، والمهام، وأسماء taskName المستعارة دون استطلاع. تُقتبس حقول المهمة والتسمية في تلك الكتلة كبيانات، لا كتعليمات، لأنها قد تنشأ من وسيطات إنشاء مقدمة من المستخدم/النموذج.

الأداة: subagents

تسرد تشغيلات الوكلاء الفرعية المنشأة التي تملكها جلسة الطالب. وهي محددة النطاق بالطالب الحالي؛ لا يستطيع الفرع رؤية إلا فروعه الخاضعة للتحكم.

استخدم subagents للحالة عند الطلب وتصحيح الأخطاء. استخدم sessions_yield من أجل انتظار أحداث الإكمال.

الجلسات المرتبطة بسلسلة

عند تمكين روابط السلاسل لقناة ما، يمكن أن يبقى الوكيل الفرعي مرتبطًا بسلسلة بحيث تظل رسائل المتابعة من المستخدم في تلك السلسلة موجهة إلى جلسة الوكيل الفرعي نفسها.

القنوات الداعمة للسلاسل

يمكن لأي قناة لديها محوّل ربط جلسة أن تدعم جلسات وكلاء فرعية مستمرة مرتبطة بسلسلة (sessions_spawn مع thread: true). تتضمن المحوّلات المجمعة حاليًا سلاسل Discord، وسلاسل Matrix، وموضوعات منتدى Telegram، وروابط المحادثة الحالية لـ Feishu. استخدم مفاتيح إعداد threadBindings الخاصة بكل قناة للتمكين، والمهل، وspawnSessions.

تدفق سريع

  • الإنشاء

    sessions_spawn مع thread: true (واختياريًا mode: "session").

  • الربط

    ينشئ OpenClaw سلسلة أو يربطها بهدف تلك الجلسة في القناة النشطة.

  • توجيه المتابعات

    تُوجّه الردود ورسائل المتابعة في تلك السلسلة إلى الجلسة المرتبطة.

  • فحص المهل

    استخدم /session idle لفحص/تحديث إلغاء التركيز التلقائي عند الخمول و /session max-age للتحكم في الحد الأقصى الصارم.

  • الفصل

    استخدم /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.allowAgentsstring[]

    قائمة معرّفات الوكلاء المكوّنة التي يمكن استهدافها عبر agentId صريح (["*"] تسمح بأي هدف مكوّن). الافتراضي: وكيل الطالب فقط. إذا عيّنت قائمة وما زلت تريد أن ينشئ الطالب نفسه باستخدام agentId، فأدرج معرّف الطالب في القائمة.

    agents.defaults.subagents.allowAgentsstring[]

    قائمة السماح الافتراضية للوكلاء الهدف المكوّنين المستخدمة عندما لا يعيّن وكيل الطالب subagents.allowAgents الخاص به.

    agents.defaults.subagents.requireAgentIdbooleandefault: false

    امنع استدعاءات sessions_spawn التي تحذف agentId (يفرض اختيار ملف تعريف صريح). تجاوز لكل وكيل: agents.list[].subagents.requireAgentId.

    agents.defaults.subagents.announceTimeoutMsnumberdefault: 120000

    مهلة لكل استدعاء لمحاولات تسليم إعلان agent في Gateway. القيم أعداد صحيحة موجبة بالمللي ثانية وتُقيد بالحد الأقصى للمؤقت الآمن للمنصة. يمكن أن تجعل إعادة المحاولة العابرة إجمالي انتظار الإعلان أطول من مهلة واحدة مكوّنة.

    إذا كانت جلسة الطالب معزولة في sandbox، ترفض sessions_spawn الأهداف التي ستعمل دون عزل.

    الاكتشاف

    استخدم agents_list لمعرفة معرّفات الوكلاء المسموح بها حاليًا لـ sessions_spawn. تتضمن الاستجابة النموذج الفعلي لكل وكيل مدرج وبيانات وصفية مضمّنة لوقت التشغيل حتى يستطيع المستدعون التمييز بين OpenClaw وخادم تطبيق Codex وأوقات التشغيل الأصلية الأخرى المكوّنة.

    يجب أن تشير إدخالات allowAgents إلى معرّفات وكلاء مكوّنة في agents.list[]. تعني ["*"] أي وكيل هدف مكوّن بالإضافة إلى الطالب. إذا حُذف إعداد وكيل لكن بقي معرّفه في allowAgents، ترفض sessions_spawn ذلك المعرّف وتحذفه agents_list. شغّل openclaw doctor --fix لتنظيف إدخالات قائمة السماح القديمة، أو أضف إدخال agents.list[] أدنى عندما ينبغي أن يبقى الهدف قابلاً للإنشاء مع وراثة الافتراضيات.

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

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

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

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

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

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

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

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

    تتدفق النتائج صعودًا عبر السلسلة:

    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.

    المصادقة

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

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

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

    الإعلان

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

    • تعمل خطوة الإعلان داخل جلسة الوكيل الفرعي (وليس جلسة الطالب).
    • إذا رد الوكيل الفرعي بالضبط ANNOUNCE_SKIP، فلا ينشر شيء.
    • إذا كان أحدث نص من المساعد هو الرمز الصامت الحرفي NO_REPLY / no_reply، يكبت خرج الإعلان حتى لو كان هناك تقدم مرئي سابق.

    يعتمد التسليم على عمق الطالب:

    • تستخدم جلسات الطالب ذات المستوى الأعلى استدعاء agent للمتابعة مع تسليم خارجي (deliver=true).
    • تتلقى جلسات الوكيل الفرعي الطالبة المتداخلة حقن متابعة داخليا (deliver=false) كي يتمكن المنسق من تركيب نتائج الأبناء داخل الجلسة.
    • إذا اختفت جلسة وكيل فرعي طالبة متداخلة، يعود OpenClaw إلى طالب تلك الجلسة عند توفره.

    بالنسبة إلى جلسات الطالب ذات المستوى الأعلى، يحل التسليم المباشر في وضع الإكمال أولا أي مسار محادثة/سلسلة مرتبط وأي تجاوز للخطاف، ثم يملأ حقول هدف القناة المفقودة من المسار المخزن في جلسة الطالب. يحافظ ذلك على الإكمالات في المحادثة/الموضوع الصحيح حتى عندما لا يحدد مصدر الإكمال إلا القناة.

    يقتصر تجميع اكتمال الأبناء على تشغيل الطالب الحالي عند بناء نتائج الإكمال المتداخلة، ما يمنع تسرب مخرجات أبناء من تشغيل سابق إلى الإعلان الحالي. وتحافظ ردود الإعلان على توجيه السلسلة/الموضوع عند توفره في محولات القنوات.

    سياق الإعلان

    يطبع سياق الإعلان إلى كتلة حدث داخلية مستقرة:

    الحقل المصدر
    المصدر subagent أو cron
    معرفات الجلسة مفتاح/معرف جلسة الابن
    النوع نوع الإعلان + تسمية المهمة
    الحالة مشتقة من نتيجة وقت التشغيل (success أو error أو timeout أو unknown) — ليست مستنتجة من نص النموذج
    محتوى النتيجة أحدث نص مساعد مرئي من الابن
    المتابعة تعليمة تصف متى يجب الرد ومتى يجب البقاء صامتا

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

    سطر الإحصاءات

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

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

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

    لماذا تفضل sessions_history

    تعد sessions_history مسار التنسيق الأكثر أمانا:

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

    سياسة الأدوات

    تستخدم الوكلاء الفرعية مسار الملف الشخصي وسياسة الأدوات نفسه الخاص بالوالد أو الوكيل الهدف أولا. بعد ذلك، يطبق OpenClaw طبقة تقييد الوكيل الفرعي.

    من دون tools.profile تقييدي، تحصل الوكلاء الفرعية على جميع الأدوات باستثناء أداة الرسائل وأدوات الجلسة وأدوات النظام:

    • sessions_list
    • sessions_history
    • sessions_send
    • sessions_spawn
    • message

    تبقى sessions_history هنا أيضا عرض استدعاء محدودا ومنقحا — فهي ليست تفريغا خاما للنص.

    عندما يكون maxSpawnDepth >= 2، تتلقى الوكلاء الفرعية المنسقة من العمق 1 أيضا sessions_spawn وsubagents وsessions_list و sessions_history كي تتمكن من إدارة أبنائها.

    التجاوز عبر التكوين

    json5
    {  agents: {    defaults: {      subagents: {        maxConcurrent: 1,      },    },  },  tools: {    subagents: {      tools: {        // deny wins        deny: ["gateway", "cron"],        // if allow is set, it becomes allow-only (deny still wins)        // allow: ["read", "exec", "process"]      },    },  },}

    tools.subagents.tools.allow مرشح نهائي للسماح فقط. يمكنه تضييق مجموعة الأدوات المحلولة مسبقا، لكنه لا يستطيع إضافة أداة أزيلت بواسطة tools.profile. على سبيل المثال، يتضمن tools.profile: "coding" web_search/web_fetch لكن لا يتضمن أداة browser. للسماح للوكلاء الفرعية ذات ملف البرمجة الشخصي باستخدام أتمتة المتصفح، أضف المتصفح في مرحلة الملف الشخصي:

    json5
    {  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

    استخدم agents.list[].tools.alsoAllow: ["browser"] لكل وكيل عندما يجب أن يحصل وكيل واحد فقط على أتمتة المتصفح.

    التزامن

    تستخدم الوكلاء الفرعية مسار طابور مخصصا داخل العملية:

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

    الحيوية والاسترداد

    لا يتعامل OpenClaw مع غياب endedAt كدليل دائم على أن وكيلا فرعيا ما زال حيا. تتوقف عمليات التشغيل غير المنتهية الأقدم من نافذة التشغيل الراكد عن الاحتساب كنشطة/معلقة في /subagents list وملخصات الحالة وبوابة اكتمال الأحفاد وفحوص التزامن لكل جلسة.

    بعد إعادة تشغيل Gateway، تزال عمليات التشغيل المستعادة الراكدة غير المنتهية ما لم تكن جلسة ابنها موسومة بـ abortedLastRun: true. وتبقى جلسات الأبناء المجهضة عند إعادة التشغيل هذه قابلة للاسترداد عبر تدفق استرداد الوكيل الفرعي اليتيم، الذي يرسل رسالة استئناف اصطناعية قبل مسح علامة الإجهاض.

    استرداد إعادة التشغيل التلقائي محدود لكل جلسة ابن. إذا قبل الوكيل الفرعي نفسه لاسترداد اليتيم مرارا داخل نافذة إعادة التعطل السريع، يثبت OpenClaw شاهدة استرداد على تلك الجلسة ويتوقف عن استئنافها تلقائيا في عمليات إعادة التشغيل اللاحقة. شغل openclaw tasks maintenance --apply لمطابقة سجل المهمة، أو openclaw doctor --fix لمسح علامات استرداد الإجهاض الراكدة على الجلسات الموسومة بشواهد.

    الإيقاف

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

    القيود

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

    ذو صلة

    Was this useful?
    On this page

    On this page