الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

الوكلاء الفرعيون هم تشغيلات وكلاء في الخلفية تُنشأ من تشغيل وكيل موجود. يعملون في جلساتهم الخاصة (agent:<agentId>:subagent:<uuid>)، وعند الانتهاء، يعلنون نتيجتهم إلى قناة دردشة الطالب. يُتتبع كل تشغيل وكيل فرعي بصفته مهمة خلفية. الأهداف الأساسية:
  • موازاة أعمال “البحث / المهمة الطويلة / الأداة البطيئة” دون حظر التشغيل الرئيسي.
  • إبقاء الوكلاء الفرعيين معزولين افتراضيا (فصل الجلسات + عزل اختياري).
  • إبقاء سطح الأدوات صعب الإساءة في الاستخدام: لا يحصل الوكلاء الفرعيون على أدوات الجلسة افتراضيا.
  • دعم عمق تداخل قابل للتهيئة لأنماط المنسق.
ملاحظة تكلفة: لكل وكيل فرعي سياقه واستهلاكه من الرموز افتراضيا. للمهام الثقيلة أو المتكررة، عيّن نموذجا أرخص للوكلاء الفرعيين وأبق وكيلك الرئيسي على نموذج أعلى جودة. هيّئ ذلك عبر agents.defaults.subagents.model أو التجاوزات لكل وكيل. عندما يحتاج فرع حقا إلى النص الحالي للطالب، يمكن للوكيل طلب context: "fork" عند ذلك الإنشاء فقط. جلسات الوكلاء الفرعيين المرتبطة بسلسلة تكون افتراضيا على context: "fork" لأنها تفرّع المحادثة الحالية إلى سلسلة متابعة.

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

استخدم /subagents لفحص تشغيلات الوكلاء الفرعيين أو التحكم بها في الجلسة الحالية: 
/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>]
استخدم /steer <message> على المستوى الأعلى لتوجيه التشغيل النشط لجلسة الطالب الحالية. استخدم /subagents steer <id|#> <message> عندما يكون الهدف تشغيلا فرعيا. يعرض /subagents info بيانات تعريف التشغيل (الحالة، الطوابع الزمنية، معرّف الجلسة، مسار النص، التنظيف). استخدم sessions_history للحصول على عرض استدعاء محدود ومرشح للسلامة؛ افحص مسار النص على القرص عندما تحتاج إلى النص الخام الكامل.

​
عناصر التحكم في ربط السلاسل

تعمل هذه الأوامر على القنوات التي تدعم روابط السلاسل المستمرة. راجع القنوات الداعمة للسلاسل أدناه. 
/focus <subagent-label|session-key|session-id|session-label>
/unfocus
/agents
/session idle <duration|off>
/session max-age <duration|off>

​
سلوك الإنشاء

يبدأ /subagents spawn وكيلا فرعيا في الخلفية كأمر مستخدم (وليس ترحيلا داخليا) ويرسل تحديث إكمال نهائيا واحدا إلى دردشة الطالب عند انتهاء التشغيل.
  • أمر الإنشاء غير حاجز؛ يعيد معرّف تشغيل فورا.
  • عند الإكمال، يعلن الوكيل الفرعي رسالة ملخص/نتيجة إلى قناة دردشة الطالب.
  • ينبغي لدورات الوكيل التي تحتاج إلى نتائج الفروع استدعاء sessions_yield بعد إنشاء العمل المطلوب. ينهي ذلك الدورة الحالية ويسمح بوصول أحداث الإكمال كالرسالة التالية المرئية للنموذج.
  • الإكمال قائم على الدفع. بعد الإنشاء، لا تستطلع /subagents list أو sessions_list أو sessions_history في حلقة لمجرد انتظار انتهائه؛ افحص الحالة عند الطلب فقط للتصحيح أو التدخل.
  • مخرج الفرع هو تقرير/دليل لكي يصوغه الوكيل الطالب. ليس نص تعليمات كتبه المستخدم ولا يمكنه تجاوز سياسة النظام أو المطور أو المستخدم.
  • عند الإكمال، يغلق OpenClaw بأفضل جهد علامات تبويب/عمليات المتصفح المتتبعة التي فتحتها جلسة ذلك الوكيل الفرعي قبل أن يستمر تدفق تنظيف الإعلان.
  • يعيد OpenClaw الإكمالات إلى جلسة الطالب عبر دورة agent بمفتاح ثبات مستقر.
  • إذا كان تشغيل الطالب لا يزال نشطا، يحاول OpenClaw أولا إيقاظ/توجيه ذلك التشغيل بدلا من بدء مسار رد مرئي ثان.
  • إذا فشل تسليم إكمال الوكيل الطالب أو لم ينتج مخرجا مرئيا، يعامل OpenClaw التسليم كفاشل ويرجع إلى توجيه/إعادة محاولة قائمة الانتظار. لا يرسل نتيجة الفرع الخام مباشرة إلى الدردشة الخارجية.
  • إذا تعذر استخدام التسليم المباشر، يرجع إلى توجيه قائمة الانتظار.
  • إذا ظل توجيه قائمة الانتظار غير متاح، يعاد تنفيذ الإعلان بتراجع أسي قصير قبل الاستسلام النهائي.
  • يحافظ تسليم الإكمال على مسار الطالب المحلول: تفوز مسارات الإكمال المرتبطة بسلسلة أو المرتبطة بمحادثة عند توفرها؛ إذا كان أصل الإكمال يوفر قناة فقط، يملأ OpenClaw الهدف/الحساب المفقود من المسار المحلول لجلسة الطالب (lastChannel / lastTo / lastAccountId) كي يستمر التسليم المباشر في العمل.
تسليم الإكمال إلى جلسة الطالب هو سياق داخلي مولد في وقت التشغيل (وليس نصا كتبه المستخدم) ويتضمن:
  • Result — أحدث نص رد assistant مرئي، وإلا فأحدث نص أداة/نتيجة أداة منقح. لا تعيد التشغيلات الطرفية الفاشلة استخدام نص الرد الملتقط.
  • Status — completed successfully / failed / timed out / unknown.
  • إحصاءات وقت تشغيل/رموز مضغوطة.
  • تعليمة تسليم تخبر الوكيل الطالب بإعادة الصياغة بصوت مساعد عادي (وليس تمرير بيانات التعريف الداخلية الخام).
  • يتجاوز --model و--thinking الإعدادات الافتراضية لذلك التشغيل المحدد.
  • استخدم info/log لفحص التفاصيل والمخرج بعد الإكمال.
  • /subagents spawn هو وضع أحادي اللقطة (mode: "run"). للجلسات المستمرة المرتبطة بسلسلة، استخدم sessions_spawn مع thread: true وmode: "session".
  • لجلسات حزمة 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 لكل وكيل)؛ ولا يزال sessions_spawn.model الصريح يفوز.
  • التفكير: يرث المستدعي ما لم تضبط agents.defaults.subagents.thinking (أو agents.list[].subagents.thinking لكل وكيل)؛ ولا يزال sessions_spawn.thinking الصريح يفوز.
  • مهلة التشغيل: إذا حُذف sessions_spawn.runTimeoutSeconds، يستخدم OpenClaw agents.defaults.subagents.runTimeoutSeconds عند ضبطه؛ وإلا فيرجع إلى 0 (بلا مهلة).

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

يتحكم agents.defaults.subagents.delegationMode في إرشاد المطالبة فقط؛ ولا يغير سياسة الأدوات أو يفرض التفويض.
  • suggest (افتراضي): أبق التنبيه القياسي لاستخدام الوكلاء الفرعيين للأعمال الأكبر أو الأبطأ.
  • prefer: أخبر الوكيل الرئيسي أن يبقى سريع الاستجابة وأن يفوض أي شيء أكثر تعقيدا من رد مباشر عبر sessions_spawn.
تستخدم التجاوزات لكل وكيل agents.list[].subagents.delegationMode. 
{
  agents: {
    defaults: {
      subagents: {
        delegationMode: "prefer",
        maxConcurrent: 4,
      },
    },
    list: [
      {
        id: "coordinator",
        subagents: { delegationMode: "prefer" },
      },
    ],
  },
}

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

​
task
string
مطلوب
وصف المهمة للوكيل الفرعي.
​
taskName
string
مُعرّف ثابت اختياري للاستهداف اللاحق عبر subagents. يجب أن يطابق [a-z][a-z0-9_]{0,63} ولا يمكن أن يكون من الأهداف المحجوزة مثل last أو all. يُفضَّل استخدامه عندما قد يحتاج المنسّق إلى توجيه تابع معيّن أو إيقافه أو تحديده بعد إنشاء عدة توابع.
​
label
string
تسمية اختيارية قابلة للقراءة البشرية.
​
agentId
string
أنشئه تحت معرّف وكيل آخر عندما يسمح subagents.allowAgents بذلك.
​
runtime
"subagent" | "acp"
افتراضي:"subagent"
يُستخدم acp فقط لحِزَم ACP الخارجية (claude، droid، gemini، opencode، أو Codex ACP/acpx المطلوب صراحةً) ولإدخالات agents.list[] التي يكون فيها runtime.type هو acp.
​
resumeSessionId
string
خاص بـ ACP فقط. يستأنف جلسة حزمة ACP موجودة عندما يكون runtime: "acp"؛ ويُتجاهل عند إنشاء الوكلاء الفرعيين الأصليين.
​
streamTo
"parent"
خاص بـ ACP فقط. يبث مخرجات تشغيل ACP إلى جلسة الأصل عندما يكون runtime: "acp"؛ احذفه عند إنشاء الوكلاء الفرعيين الأصليين.
​
model
string
يتجاوز نموذج الوكيل الفرعي. تُتخطّى القيم غير الصالحة ويعمل الوكيل الفرعي على النموذج الافتراضي مع تحذير في نتيجة الأداة.
​
thinking
string
يتجاوز مستوى التفكير لتشغيل الوكيل الفرعي.
​
runTimeoutSeconds
number
تكون القيمة الافتراضية agents.defaults.subagents.runTimeoutSeconds عند ضبطها، وإلا فهي 0. عند ضبطها، يُجهض تشغيل الوكيل الفرعي بعد N ثانية.
​
thread
boolean
افتراضي:"false"
عندما تكون true، يطلب ربط سلسلة المحادثة في القناة لجلسة هذا الوكيل الفرعي.
​
mode
"run" | "session"
افتراضي:"run"
إذا كانت thread: true وجرى حذف mode، تصبح القيمة الافتراضية session. يتطلب mode: "session" وجود thread: true.
​
cleanup
"delete" | "keep"
افتراضي:"keep"
يؤرشف "delete" فورًا بعد الإعلان (مع الاحتفاظ بالنص عبر إعادة التسمية).
​
sandbox
"inherit" | "require"
افتراضي:"inherit"
يرفض require الإنشاء ما لم يكن وقت تشغيل التابع المستهدف معزولًا في صندوق رمل.
​
context
"isolated" | "fork"
افتراضي:"isolated"
يفرّع fork النص الحالي لمقدّم الطلب إلى جلسة التابع. للوكلاء الفرعيين الأصليين فقط. عمليات الإنشاء المرتبطة بسلسلة محادثة تكون افتراضيًا fork؛ وعمليات الإنشاء غير المرتبطة بسلسلة محادثة تكون افتراضيًا isolated.
لا تقبل sessions_spawn معاملات تسليم القناة (target، channel، to، threadId، replyTo، transport). للتسليم، استخدم message/sessions_send من التشغيل الذي جرى إنشاؤه.

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

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

​
الأداة: sessions_yield

تنهي دور النموذج الحالي وتنتظر أحداث وقت التشغيل، وبشكل أساسي أحداث اكتمال الوكلاء الفرعيين، لتصل كرسالة تالية. استخدمها بعد إنشاء عمل تابع مطلوب عندما لا يستطيع مقدّم الطلب إنتاج إجابة نهائية حتى تصل تلك الاكتمالات. sessions_yield هي أداة الانتظار الأساسية. لا تستبدلها بحلقات استطلاع على subagents أو sessions_list أو sessions_history أو sleep في الصدفة أو استطلاع العمليات لمجرد اكتشاف اكتمال التابع. استخدم sessions_yield فقط عندما تتضمنها قائمة الأدوات الفعالة للجلسة. قد تعرض بعض ملفات تعريف الأدوات الدنيا أو المخصصة sessions_spawn و subagents من دون عرض sessions_yield؛ في هذه الحالة، لا تخترع حلقة استطلاع لمجرد انتظار الاكتمال. عند وجود توابع نشطة، يحقن OpenClaw كتلة مدمجة منشأة بواسطة وقت التشغيل بعنوان Active Subagents في الأدوار العادية كي يرى مقدّم الطلب جلسات التوابع الحالية، ومعرّفات التشغيل، والحالات، والتسميات، والمهام، والأسماء البديلة taskName من دون استطلاع. تُقتبس حقول المهمة والتسمية في تلك الكتلة كبيانات، لا كتعليمات، لأنها قد تنشأ من معاملات إنشاء مقدّمة من المستخدم/النموذج.

​
الأداة: subagents

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

​
الجلسات المرتبطة بسلاسل المحادثة

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

​
القنوات الداعمة لسلاسل المحادثة

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.spawnSessions.

​
التدفق السريع

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
string[]
قائمة بمعرّفات الوكلاء التي يمكن استهدافها عبر agentId صريح (["*"] يسمح بأي معرّف). الافتراضي: وكيل مقدّم الطلب فقط. إذا ضبطت قائمة وما زلت تريد أن ينشئ مقدّم الطلب نفسه باستخدام agentId، فأدرج معرّف مقدّم الطلب في القائمة.
​
agents.defaults.subagents.allowAgents
string[]
قائمة السماح الافتراضية للوكلاء المستهدفين المستخدمة عندما لا يضبط وكيل مقدّم الطلب subagents.allowAgents الخاص به.
​
agents.defaults.subagents.requireAgentId
boolean
افتراضي:"false"
يحظر استدعاءات sessions_spawn التي تحذف agentId (يفرض اختيار ملف تعريف صريحًا). تجاوز لكل وكيل: agents.list[].subagents.requireAgentId.
​
agents.defaults.subagents.announceTimeoutMs
number
افتراضي:"120000"
مهلة لكل استدعاء لمحاولات تسليم إعلان agent في Gateway. القيم هي أعداد صحيحة موجبة بالمللي ثانية وتُقيَّد بالحد الأقصى الآمن لمؤقت المنصة. قد تجعل إعادة المحاولة العابرة إجمالي انتظار الإعلان أطول من مهلة واحدة مضبوطة.
إذا كانت جلسة مقدّم الطلب معزولة في صندوق رمل، ترفض sessions_spawn الأهداف التي قد تعمل من دون صندوق رمل.

​
الاكتشاف

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

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

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

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

افتراضيًا، لا يستطيع الوكلاء الفرعيون إنشاء وكلائهم الفرعيين (maxSpawnDepth: 1). اضبط maxSpawnDepth: 2 لتمكين مستوى واحد من التداخل — نمط المنسّق: الرئيسي → وكيل فرعي منسّق → وكلاء فرعيون فرعيون عاملون. 
{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)
        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)
        maxConcurrent: 8, // global concurrency lane cap (default: 8)
        runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout)
        announceTimeoutMs: 120000, // per-call gateway announce timeout
      },
    },
  },
}

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

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

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

تتدفق النتائج صعودًا في السلسلة:
  1. ينتهي عامل العمق 2 → يعلن إلى أصله (منسّق العمق 1).
  2. يتلقى منسّق العمق 1 الإعلان، يركّب النتائج، ينتهي → يعلن إلى الرئيسي.
  3. يتلقى الوكيل الرئيسي الإعلان ويسلّمه إلى المستخدم.
يرى كل مستوى الإعلانات الواردة من توابعه المباشرين فقط.
إرشادات تشغيلية: ابدأ العمل الفرعي مرة واحدة وانتظر أحداث الاكتمال بدلًا من بناء حلقات استطلاع حول sessions_list أو sessions_history أو /subagents list أو أوامر السكون في exec. يحافظ sessions_list و/subagents list على تركيز علاقات الجلسات الفرعية على العمل الحي — إذ تظل الفروع الحية مرتبطة، وتبقى الفروع المنتهية مرئية ضمن نافذة حديثة قصيرة، ويتم تجاهل روابط الفروع القديمة الموجودة في المخزن فقط بعد انتهاء نافذة حداثتها. يمنع هذا بيانات spawnedBy / parentSessionKey الوصفية القديمة من إحياء فروع وهمية بعد إعادة التشغيل. إذا وصل حدث اكتمال فرعي بعد أن تكون قد أرسلت الإجابة النهائية بالفعل، فالمتابعة الصحيحة هي الرمز الصامت الدقيق NO_REPLY / no_reply.

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

  • تتم كتابة الدور ونطاق التحكم في بيانات الجلسة الوصفية عند وقت الإنشاء. يحافظ ذلك على مفاتيح الجلسات المسطحة أو المستعادة من استعادة امتيازات المنسق عن طريق الخطأ.
  • العمق 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 <id> إلى إيقاف وكيل فرعي محدد ويتتالى إلى فروعه.
  • يؤدي /subagents kill all إلى إيقاف جميع الوكلاء الفرعيين لمقدم الطلب ويتتالى.

​
المصادقة

تُحل مصادقة الوكيل الفرعي بواسطة معرف الوكيل، وليس بواسطة نوع الجلسة:
  • مفتاح جلسة الوكيل الفرعي هو 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].
  • فحص النص الكامل الخام على القرص هو البديل عندما تحتاج إلى النص الكامل بايتًا مقابل بايت.

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

يستخدم الوكلاء الفرعيون خط سير ملف التعريف وسياسة الأدوات نفسه الخاص بالوالد أو الوكيل الهدف أولًا. بعد ذلك، يطبق OpenClaw طبقة تقييد الوكيل الفرعي. عند عدم وجود tools.profile تقييدي، يحصل الوكلاء الفرعيون على كل الأدوات باستثناء أدوات الجلسة وأدوات النظام:
  • sessions_list
  • sessions_history
  • sessions_send
  • sessions_spawn
يبقى sessions_history عرض تذكر محدودًا ومنظفًا هنا أيضًا — وليس تفريغًا خامًا للنص الكامل. عندما يكون maxSpawnDepth >= 2، يتلقى الوكلاء الفرعيون المنسقون عند العمق 1 أيضًا sessions_spawn وsubagents وsessions_list وsessions_history حتى يتمكنوا من إدارة فروعهم.

​
التجاوز عبر الإعدادات

{
  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. للسماح للوكلاء الفرعيين ذوي ملف تعريف البرمجة باستخدام أتمتة المتصفح، أضف browser في مرحلة ملف التعريف: 
{
  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 لمسح علامات استرداد الإجهاض القديمة على الجلسات ذات شواهد القبور.
إذا فشل إنشاء وكيل فرعي مع Gateway PAIRING_REQUIRED / scope-upgrade، فتحقق من مستدعي RPC قبل تعديل حالة الاقتران. يجب أن يتصل تنسيق sessions_spawn الداخلي كـ client.id: "gateway-client" مع client.mode: "backend" عبر مصادقة مباشرة باستخدام local loopback ورمز/كلمة مرور مشتركة؛ لا يعتمد ذلك المسار على خط أساس نطاق الجهاز المقترن الخاص بـ CLI. لا يزال المستدعون البعيدون، وdeviceIdentity الصريح، ومسارات رمز الجهاز الصريحة، وعملاء المتصفح/node بحاجة إلى موافقة الجهاز العادية لترقيات النطاق.

​
الإيقاف

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

​
القيود

  • إعلان الوكيل الفرعي هو أفضل جهد. إذا أعيد تشغيل 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).
  • أقصى عمق للتداخل هو 5 (نطاق maxSpawnDepth: 1–5). يوصى بالعمق 2 لمعظم حالات الاستخدام.
  • يحدد maxChildrenPerAgent الحد الأقصى للفروع النشطة لكل جلسة (القيمة الافتراضية 5، النطاق 1–20).

​
ذات صلة