---
read_when:
    - تريد تنفيذ أعمال في الخلفية أو بالتوازي عبر الوكيل
    - أنت تغيّر سياسة أداة `sessions_spawn` أو سياسة الوكيل الفرعي
    - أنت تنفّذ جلسات الوكيل الفرعي المرتبطة بالخيوط أو تستكشف أخطاءها وإصلاحها
sidebarTitle: Sub-agents
summary: شغّل عمليات وكيل معزولة في الخلفية تُعلن النتائج مرة أخرى إلى محادثة الطالب
title: الوكلاء الفرعيون
x-i18n:
    generated_at: "2026-04-26T11:42:43Z"
    model: gpt-5.4
    provider: openai
    source_hash: e7f2f1b8ae08026dd0f8c1b466bb7a8b044ae1d12c2ae61735dcf9f380179986
    source_path: tools/subagents.md
    workflow: 15
---

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

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

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

<Note>
**ملاحظة حول التكلفة:** لكل وكيل فرعي سياقه الخاص واستهلاكه الخاص من الرموز
افتراضيًا. بالنسبة إلى المهام الثقيلة أو المتكررة، اضبط نموذجًا أرخص للوكلاء الفرعيين
وأبقِ وكيلك الرئيسي على نموذج أعلى جودة. اضبط ذلك عبر
`agents.defaults.subagents.model` أو عبر تجاوزات خاصة بكل وكيل. وعندما
يحتاج الابن فعلًا إلى النص المفرغ الحالي للجهة الطالبة، يمكن للوكيل طلب
`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>]
```

يعرض `/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="اكتمال غير حاجب ومعتمد على الدفع">
    - أمر التشغيل غير حاجب؛ إذ يعيد معرّف العملية فورًا.
    - عند الاكتمال، يعلن الوكيل الفرعي رسالة ملخص/نتيجة مرة أخرى إلى قناة محادثة الجهة الطالبة.
    - يعتمد الاكتمال على الدفع. بعد التشغيل، **لا** تستعلم عن `/subagents list` أو `sessions_list` أو `sessions_history` داخل حلقة فقط من أجل انتظار انتهائه؛ افحص الحالة عند الطلب فقط لأغراض التصحيح أو التدخل.
    - عند الاكتمال، يغلق OpenClaw على أساس أفضل جهد علامات تبويب المتصفح/العمليات المتعقبة التي فتحها ذلك الوكيل الفرعي قبل استمرار تدفق تنظيف الإعلان.

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

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

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

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

  </Accordion>
</AccordionGroup>

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

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

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

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

## الأداة: `sessions_spawn`

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

**الافتراضيات:**

- **النموذج:** يرثه من المستدعي ما لم تضبط `agents.defaults.subagents.model` (أو `agents.list[].subagents.model` الخاص بكل وكيل)؛ ولا يزال `sessions_spawn.model` الصريح هو الغالب.
- **التفكير:** يرثه من المستدعي ما لم تضبط `agents.defaults.subagents.thinking` (أو `agents.list[].subagents.thinking` الخاص بكل وكيل)؛ ولا يزال `sessions_spawn.thinking` الصريح هو الغالب.
- **مهلة التشغيل:** إذا تم حذف `sessions_spawn.runTimeoutSeconds`، يستخدم OpenClaw القيمة `agents.defaults.subagents.runTimeoutSeconds` عند ضبطها؛ وإلا فإنه يرجع إلى `0` (بلا مهلة).

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

<ParamField path="task" type="string" required>
  وصف المهمة الخاصة بالوكيل الفرعي.
</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="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` إلى رفض التشغيل ما لم تكن Runtime الفرعية المستهدفة داخل sandbox.
</ParamField>
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
  تؤدي `fork` إلى تفريع النص المفرغ الحالي للجهة الطالبة إلى الجلسة الفرعية. وهذا خاص بالوكلاء الفرعيين الأصليين فقط. استخدم `fork` فقط عندما يحتاج الفرع الابن إلى النص المفرغ الحالي.
</ParamField>

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

## الجلسات المرتبطة بالخيوط

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

### القنوات الداعمة للخيوط

**Discord** هي القناة المدعومة الوحيدة حاليًا. وهي تدعم
جلسات الوكلاء الفرعيين المرتبطة بالخيوط بشكل مستمر (`sessions_spawn` مع
`thread: true`)، وعناصر التحكم اليدوية بالخيوط (`/focus` و`/unfocus` و`/agents` و
`/session idle` و`/session max-age`)، ومفاتيح المهايئ
`channels.discord.threadBindings.enabled`،
`channels.discord.threadBindings.idleHours`،
`channels.discord.threadBindings.maxAgeHours`، و
`channels.discord.threadBindings.spawnSubagentSessions`.

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

<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` (تسمح `["*"]` بأي وكيل). الافتراضي: وكيل الجهة الطالبة فقط.
</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>

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

### الاكتشاف

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

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

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

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

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

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

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

| العمق | شكل مفتاح الجلسة                           | الدور                                         | هل يمكنه التشغيل؟             |
| ----- | ------------------------------------------ | --------------------------------------------- | ----------------------------- |
| 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`                                                                                           |
| معرّفات الجلسة | مفتاح/معرّف الجلسة الفرعية                                                                                     |
| النوع          | نوع الإعلان + تسمية المهمة                                                                                     |
| الحالة         | مشتقة من نتيجة Runtime (`success` أو `error` أو `timeout` أو `unknown`) — **ولا** تُستنتج من نص النموذج       |
| محتوى النتيجة  | أحدث نص مرئي للمساعد، وإلا أحدث نص منقّى من tool/toolResult                                                  |
| المتابعة       | تعليمات تصف متى يجب الرد ومتى يجب البقاء صامتًا                                                               |

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

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

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

- Runtime (مثل `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: ["gateway", "cron"],
        // إذا تم ضبط allow، فسيصبح السماح فقط (ولا يزال المنع هو الغالب)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}
```

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

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

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

## التوازي

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

- **اسم المسار:** `subagent`
- **التوازي:** `agents.defaults.subagents.maxConcurrent` (الافتراضي `8`)

## الحيوية والاستعادة

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

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

<Note>
إذا فشل تشغيل وكيل فرعي مع Gateway `PAIRING_REQUIRED` /
`scope-upgrade`، فتحقق من مستدعي RPC قبل تعديل حالة الاقتران.
يجب أن يتصل التنسيق الداخلي لـ `sessions_spawn` على هيئة
`client.id: "gateway-client"` مع `client.mode: "backend"` عبر
مصادقة loopback مباشرة باستخدام shared-token/password؛ ولا يعتمد هذا المسار على
خط الأساس لنطاق الجهاز المقترن الخاص بـ CLI. أما المستدعون البعيدون، و
`deviceIdentity` الصريحة، ومسارات رموز الجهاز الصريحة، وعملاء browser/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` أو `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)
- [أدوات sandbox متعددة الوكلاء](/ar/tools/multi-agent-sandbox-tools)
