---
read_when:
    - تريد تنفيذ عمل في الخلفية أو بالتوازي عبر الوكيل
    - أنت تغيّر سياسة أداة sessions_spawn أو أداة الوكيل الفرعي
    - أنت تنفذ جلسات وكلاء فرعيين مرتبطة بسلسلة المحادثة أو تستكشف أخطاءها وإصلاحها
sidebarTitle: Sub-agents
summary: تشغيل عمليات وكيل خلفية معزولة تعلن النتائج مرة أخرى في محادثة الطالب
title: الوكلاء الفرعيون
x-i18n:
    generated_at: "2026-06-28T00:14:25Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 144af6e020c86d171fe6c5734efaad229adaea35f8d1c1b07e37c549805c88ff
    source_path: tools/subagents.md
    workflow: 16
---

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

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

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

<Note>
**ملاحظة التكلفة:** لكل وكيل فرعي سياقه الخاص واستخدامه الخاص للرموز
افتراضيا. للمهام الثقيلة أو المتكررة، عيّن نموذجا أقل تكلفة للوكلاء الفرعيين
وأبق وكيلك الرئيسي على نموذج أعلى جودة. اضبط ذلك عبر
`agents.defaults.subagents.model` أو عبر تجاوزات لكل وكيل. عندما يحتاج الوكيل الابن
    فعلا إلى نص سجل الطالب الحالي، يمكن للوكيل طلب
    `context: "fork"` في عملية الإنشاء تلك فقط. جلسات الوكلاء الفرعيين المرتبطة بالخيط تكون افتراضيا
    على `context: "fork"` لأنها تفرّع المحادثة الحالية إلى
    خيط متابعة.
</Note>

## أمر Slash

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

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

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

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

تعمل هذه الأوامر على القنوات التي تدعم ربط الخيوط المستمر.
راجع [القنوات الداعمة للخيوط](#thread-supporting-channels) أدناه.

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

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

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

<AccordionGroup>
  <Accordion title="Non-blocking, push-based completion">
    - `sessions_spawn` غير حاجب؛ يعيد معرّف تشغيل فورا.
    - عند الاكتمال، يبلّغ الوكيل الفرعي مرة أخرى إلى جلسة الأصل/الطالب.
    - يجب على دورات الوكيل التي تحتاج إلى نتائج الأبناء استدعاء `sessions_yield` بعد إنشاء العمل المطلوب. ينهي ذلك الدورة الحالية ويتيح وصول أحداث الاكتمال كالرسالة التالية المرئية للنموذج.
    - الاكتمال قائم على الدفع. بعد الإنشاء، لا تستطلع `/subagents list` أو `sessions_list` أو `sessions_history` في حلقة لمجرد انتظار انتهائه؛ افحص الحالة عند الطلب فقط لرؤية التصحيح.
    - مخرجات الابن هي تقرير/دليل لوكيل الطالب كي يركّبه. وليست نص تعليمات من إنشاء المستخدم، ولا يمكنها تجاوز سياسة النظام أو المطور أو المستخدم.
    - عند الاكتمال، يغلق OpenClaw بأفضل جهد علامات تبويب/عمليات المتصفح المتتبعة التي فتحتها جلسة ذلك الوكيل الفرعي قبل استمرار تدفق تنظيف الإعلان.

  </Accordion>
  <Accordion title="Completion delivery">
    - يسلّم OpenClaw الاكتمالات مرة أخرى إلى جلسة الطالب عبر دورة `agent` بمفتاح ثبات مستقر.
    - إذا كان تشغيل الطالب لا يزال نشطا، يحاول OpenClaw أولا إيقاظ/توجيه ذلك التشغيل بدلا من بدء مسار رد مرئي ثان.
    - إذا تعذر إيقاظ طالب نشط، يعود OpenClaw إلى تسليم إلى وكيل الطالب بسياق الاكتمال نفسه بدلا من إسقاط الإعلان.
    - يكمّل تسليم الأصل الناجح تسليم الوكيل الفرعي حتى عندما يقرر الأصل أن تحديثا مرئيا للمستخدم غير مطلوب.
    - لا تحصل الوكلاء الفرعية الأصلية على أداة الرسائل. فهي تعيد نص مساعد عاديا إلى وكيل الأصل/الطالب؛ الردود المرئية للبشر يملكها نهج التسليم العادي لوكيل الأصل/الطالب.
    - إذا تعذر استخدام التسليم المباشر، يعود إلى توجيه الطابور.
    - إذا ظل توجيه الطابور غير متاح، تعاد محاولة الإعلان بتراجع أسي قصير قبل التخلي النهائي.
    - يحتفظ تسليم الاكتمال بمسار الطالب المحلول: تفوز مسارات الاكتمال المرتبطة بالخيط أو بالمحادثة عند توفرها؛ إذا كان أصل الاكتمال لا يوفر إلا قناة، يملأ OpenClaw الهدف/الحساب المفقود من المسار المحلول لجلسة الطالب (`lastChannel` / `lastTo` / `lastAccountId`) كي يظل التسليم المباشر يعمل.

  </Accordion>
  <Accordion title="Completion handoff metadata">
    تسليم الاكتمال إلى جلسة الطالب هو سياق داخلي مولّد وقت التشغيل
    (وليس نصا أنشأه المستخدم) ويتضمن:

    - `Result` — أحدث نص رد `assistant` مرئي من الابن. لا تُرقّى مخرجات tool/toolResult إلى نتائج الابن. لا تعيد التشغيلات الفاشلة نهائيا استخدام نص الرد الملتقط.
    - `Status` — `completed; ready for parent review` / `failed` / `timed out` / `unknown`.
    - إحصاءات مدمجة لوقت التشغيل/الرموز.
    - تعليمة مراجعة تطلب من وكيل الطالب التحقق من النتيجة قبل تقرير ما إذا كانت المهمة الأصلية قد اكتملت.
    - إرشاد متابعة يطلب من وكيل الطالب متابعة المهمة أو تسجيل متابعة عندما تترك نتيجة الابن مزيدا من الإجراء.
    - تعليمة تحديث نهائية لمسار عدم وجود إجراء إضافي، مكتوبة بصوت المساعد العادي من دون تمرير بيانات تعريف داخلية خام.

  </Accordion>
  <Accordion title="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](/ar/tools/acp-agents#delivery-model) عند تصحيح الاكتمالات أو حلقات وكيل إلى وكيل. عندما يكون Plugin `codex` مفعلا، ينبغي لتَحكّم دردشة/خيط Codex تفضيل `/codex ...` على ACP ما لم يطلب المستخدم ACP/acpx صراحة.
    - يخفي OpenClaw `runtime: "acp"` حتى يتم تفعيل ACP، ولا يكون الطالب معزولا في صندوق رمل، ويتم تحميل Plugin خلفية مثل `acpx`. يتوقع `runtime: "acp"` معرّف حزمة ACP خارجية، أو إدخالا في `agents.list[]` مع `runtime.type="acp"`؛ استخدم وقت تشغيل الوكيل الفرعي الافتراضي لوكلاء تكوين OpenClaw العاديين من `agents_list`.

  </Accordion>
</AccordionGroup>

## أوضاع السياق

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

| الوضع       | متى تستخدمه                                                                                                                         | السلوك                                                                          |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `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" },
      },
    ],
  },
}
```

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

<ParamField path="task" type="string" required>
  وصف المهمة للوكيل الفرعي.
</ParamField>
<ParamField path="taskName" type="string">
  معرّف مستقر اختياري لتعريف فرع محدد في مخرجات الحالة اللاحقة. يجب أن يطابق `[a-z][a-z0-9_-]{0,63}` ولا يمكن أن يكون من الأهداف المحجوزة مثل `last` أو `all`.
</ParamField>
<ParamField path="label" type="string">
  تسمية اختيارية قابلة للقراءة البشرية.
</ParamField>
<ParamField path="agentId" type="string">
  أنشئ تحت معرّف وكيل آخر مكوّن عندما يسمح `subagents.allowAgents` بذلك.
</ParamField>
<ParamField path="cwd" type="string">
  دليل عمل اختياري للمهمة لتشغيل الفرع. لا تزال الوكلاء الفرعية الأصلية تحمّل ملفات التمهيد من مساحة عمل الوكيل الهدف؛ لا يغيّر `cwd` إلا المكان الذي تنفذ فيه أدوات وقت التشغيل وأطر CLI العمل المفوّض.
</ParamField>
<ParamField path="runtime" type='"subagent" | "acp"' default="subagent">
  `acp` مخصص فقط لأطر ACP الخارجية (`claude`، `droid`، `gemini`، `opencode`، أو Codex ACP/acpx المطلوب صراحة) ولإدخالات `agents.list[]` التي يكون `runtime.type` فيها هو `acp`.
</ParamField>
<ParamField path="resumeSessionId" type="string">
  خاص بـ ACP فقط. يستأنف جلسة إطار ACP موجودة عندما يكون `runtime: "acp"`؛ ويتم تجاهله عند إنشاء وكلاء فرعية أصلية.
</ParamField>
<ParamField path="streamTo" type='"parent"'>
  خاص بـ ACP فقط. يبث مخرجات تشغيل ACP إلى الجلسة الأصل عندما يكون `runtime: "acp"`؛ احذفه عند إنشاء وكلاء فرعية أصلية.
</ParamField>
<ParamField path="model" type="string">
  تجاوز نموذج الوكيل الفرعي. تُتخطى القيم غير الصالحة ويعمل الوكيل الفرعي على النموذج الافتراضي مع تحذير في نتيجة الأداة.
</ParamField>
<ParamField path="thinking" type="string">
  تجاوز مستوى التفكير لتشغيل الوكيل الفرعي.
</ParamField>
<ParamField path="thread" type="boolean" default="false">
  عندما تكون `true`، يطلب ربط سلسلة القناة لهذه الجلسة الفرعية.
</ParamField>
<ParamField path="mode" type='"run" | "session"' default="run">
  إذا كانت `thread: true` وجرى حذف `mode`، يصبح الافتراضي `session`. يتطلب `mode: "session"` أن تكون `thread: true`.
  إذا كان ربط السلسلة غير متاح لقناة الطالب، فاستخدم `mode: "run"` بدلاً من ذلك.
</ParamField>
<ParamField path="cleanup" type='"delete" | "keep"' default="keep">
  تؤرشف `"delete"` فورًا بعد الإعلان (مع الاستمرار في الاحتفاظ بالنص عبر إعادة التسمية).
</ParamField>
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
  يرفض `require` الإنشاء ما لم يكن وقت تشغيل الفرع الهدف معزولاً في sandbox.
</ParamField>
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
  يفرّع `fork` النص الحالي للطالب إلى جلسة الفرع. للوكلاء الفرعية الأصلية فقط. عمليات الإنشاء المرتبطة بسلسلة تكون افتراضيًا `fork`؛ وعمليات الإنشاء غير المرتبطة بسلسلة تكون افتراضيًا `isolated`.
</ParamField>

<Warning>
لا تقبل `sessions_spawn` معلمات تسليم القناة (`target`،
`channel`، `to`، `threadId`، `replyTo`، `transport`). تبلّغ الوكلاء الفرعية الأصلية
آخر دور للمساعد لديها إلى الطالب؛ ويبقى التسليم الخارجي مع
الوكيل الأصل/الطالب.
</Warning>

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

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

### تدفق سريع

<Steps>
  <Step title="الإنشاء">
    `sessions_spawn` مع `thread: true` (واختياريًا `mode: "session"`).
  </Step>
  <Step title="الربط">
    ينشئ OpenClaw سلسلة أو يربطها بهدف تلك الجلسة في القناة النشطة.
  </Step>
  <Step title="توجيه المتابعات">
    تُوجّه الردود ورسائل المتابعة في تلك السلسلة إلى الجلسة المرتبطة.
  </Step>
  <Step title="فحص المهل">
    استخدم `/session idle` لفحص/تحديث إلغاء التركيز التلقائي عند الخمول و
    `/session max-age` للتحكم في الحد الأقصى الصارم.
  </Step>
  <Step title="الفصل">
    استخدم `/unfocus` للفصل يدويًا.
  </Step>
</Steps>

### عناصر التحكم اليدوية

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

### مفاتيح الإعداد

- **الافتراضي العام:** `session.threadBindings.enabled`، `session.threadBindings.idleHours`، `session.threadBindings.maxAgeHours`.
- **مفاتيح تجاوز القناة والربط التلقائي عند الإنشاء** خاصة بالمحوّل. راجع [القنوات الداعمة للسلاسل](#thread-supporting-channels) أعلاه.

راجع [مرجع الإعداد](/ar/gateway/configuration-reference) و
[أوامر الشرطة المائلة](/ar/tools/slash-commands) للاطلاع على تفاصيل المحوّل الحالية.

### قائمة السماح

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

إذا كانت جلسة الطالب معزولة في 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. يتلقى الوكيل الرئيسي الإعلان ويسلمه إلى المستخدم.

لا يرى كل مستوى إلا الإعلانات الواردة من أبنائه المباشرين.

<Note>
**إرشاد تشغيلي:** ابدأ عمل الأبناء مرة واحدة وانتظر أحداث الاكتمال
بدلا من بناء حلقات استطلاع حول `sessions_list` أو
`sessions_history` أو `/subagents list` أو أوامر السكون في `exec`.
تحافظ `sessions_list` و`/subagents list` على تركيز علاقات جلسات الأبناء
على العمل الحي — يظل الأبناء الأحياء مرفقين، ويبقى الأبناء المنتهون
مرئيين ضمن نافذة حديثة قصيرة، ويتم تجاهل روابط الأبناء القديمة الموجودة
في المخزن فقط بعد انتهاء نافذة حداثتها. يمنع هذا بيانات `spawnedBy` /
`parentSessionKey` الوصفية القديمة من إحياء أبناء وهميين بعد إعادة
التشغيل. إذا وصل حدث اكتمال ابن بعد أن تكون قد أرسلت الإجابة النهائية
بالفعل، فالمتابعة الصحيحة هي الرمز الصامت الحرفي
`NO_REPLY` / `no_reply`.
</Note>

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

- يكتب الدور ونطاق التحكم في بيانات الجلسة الوصفية عند وقت الإنشاء. يحافظ ذلك على مفاتيح الجلسات المسطحة أو المستعادة من استعادة امتيازات المنسق بالخطأ.
- **العمق 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` لمسح علامات استرداد الإجهاض الراكدة على
الجلسات الموسومة بشواهد.

<Note>
إذا فشل إنشاء وكيل فرعي مع Gateway `PAIRING_REQUIRED` /
`scope-upgrade`، فتحقق من مستدعي RPC قبل تحرير حالة الاقتران.
يرسل تنسيق `sessions_spawn` الداخلي داخل العملية عندما يكون المستدعي
يعمل بالفعل داخل سياق طلب Gateway، لذلك لا يفتح WebSocket عبر loopback
ولا يعتمد على خط أساس نطاق الجهاز المقترن الخاص بـ CLI. لا يزال
المستدعون خارج عملية Gateway يستخدمون احتياط WebSocket كـ
`client.id: "gateway-client"` مع `client.mode: "backend"`
عبر مصادقة رمز/كلمة مرور مشتركة مباشرة عبر loopback. لا يزال المستدعون
عن بعد، و`deviceIdentity` الصريح، ومسارات رمز الجهاز الصريحة، وعملاء
المتصفح/Node بحاجة إلى موافقة جهاز عادية لترقيات النطاق.
</Note>

## الإيقاف

- يؤدي إرسال `/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`).

## ذو صلة

- [وكلاء ACP](/ar/tools/acp-agents)
- [إرسال الوكيل](/ar/tools/agent-send)
- [المهام الخلفية](/ar/automation/tasks)
- [أدوات صندوق حماية متعدد الوكلاء](/ar/tools/multi-agent-sandbox-tools)