---
read_when:
    - تريد تنفيذ عمل في الخلفية أو عمل متوازٍ عبر الوكيل
    - أنت تغيّر سياسة أداة sessions_spawn أو سياسة أداة الوكيل الفرعي
    - أنت تنفذ جلسات الوكلاء الفرعيين المرتبطة بالسلاسل أو تستكشف أخطاءها وإصلاحها
sidebarTitle: Sub-agents
summary: أنشئ عمليات تشغيل معزولة لعوامل في الخلفية تعلن النتائج مرة أخرى في دردشة مقدّم الطلب
title: الوكلاء الفرعيون
x-i18n:
    generated_at: "2026-05-11T20:44:14Z"
    model: gpt-5.5
    provider: openai
    source_hash: 02b03bdfd5cddf5618fddf0804f017400c36751095166dac18fa35fa3bfd4c6e
    source_path: tools/subagents.md
    workflow: 16
---

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

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

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

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

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

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

```text
/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>`](/ar/tools/steer) على المستوى الأعلى لتوجيه التشغيل النشط لجلسة الطالب الحالية. استخدم `/subagents steer <id|#> <message>` عندما يكون الهدف تشغيلا فرعيا.

يعرض `/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>
```

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

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

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

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

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

    - `Result` — أحدث نص رد `assistant` مرئي، وإلا فأحدث نص أداة/نتيجة أداة منقح. لا تعيد التشغيلات الطرفية الفاشلة استخدام نص الرد الملتقط.
    - `Status` — `completed successfully` / `failed` / `timed out` / `unknown`.
    - إحصاءات وقت تشغيل/رموز مضغوطة.
    - تعليمة تسليم تخبر الوكيل الطالب بإعادة الصياغة بصوت مساعد عادي (وليس تمرير بيانات التعريف الداخلية الخام).

  </Accordion>
  <Accordion title="الأوضاع وبيئة تشغيل ACP">
    - يتجاوز `--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](/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` لكل وكيل)؛ ولا يزال `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`.

```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">
  مُعرّف ثابت اختياري للاستهداف اللاحق عبر `subagents`. يجب أن يطابق `[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="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="runTimeoutSeconds" type="number">
  تكون القيمة الافتراضية `agents.defaults.subagents.runTimeoutSeconds` عند ضبطها، وإلا فهي `0`. عند ضبطها، يُجهض تشغيل الوكيل الفرعي بعد N ثانية.
</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`.
</ParamField>
<ParamField path="cleanup" type='"delete" | "keep"' default="keep">
  يؤرشف `"delete"` فورًا بعد الإعلان (مع الاحتفاظ بالنص عبر إعادة التسمية).
</ParamField>
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
  يرفض `require` الإنشاء ما لم يكن وقت تشغيل التابع المستهدف معزولًا في صندوق رمل.
</ParamField>
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
  يفرّع `fork` النص الحالي لمقدّم الطلب إلى جلسة التابع. للوكلاء الفرعيين الأصليين فقط. عمليات الإنشاء المرتبطة بسلسلة محادثة تكون افتراضيًا `fork`؛ وعمليات الإنشاء غير المرتبطة بسلسلة محادثة تكون افتراضيًا `isolated`.
</ParamField>

<Warning>
لا تقبل `sessions_spawn` معاملات تسليم القناة (`target`،
`channel`، `to`، `threadId`، `replyTo`، `transport`). للتسليم، استخدم
`message`/`sessions_send` من التشغيل الذي جرى إنشاؤه.
</Warning>

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

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

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

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

إذا كانت جلسة مقدّم الطلب معزولة في صندوق رمل، ترفض `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` لتمكين مستوى واحد من
التداخل — **نمط المنسّق**: الرئيسي → وكيل فرعي منسّق →
وكلاء فرعيون فرعيون عاملون.

```json5
{
  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
      },
    },
  },
}
```

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

| العمق | شكل مفتاح الجلسة                            | الدور                                      | هل يمكنه الإنشاء؟            |
| ----- | -------------------------------------------- | ------------------------------------------ | ---------------------------- |
| 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.
- يؤدي `/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` حتى يتمكنوا من إدارة فروعهم.

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

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

## الإيقاف

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

## ذات صلة

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