---
read_when:
    - می‌خواهید کار پس‌زمینه یا موازی را از طریق عامل انجام دهید
    - شما در حال تغییر sessions_spawn یا سیاست ابزار عامل فرعی هستید
    - شما در حال پیاده‌سازی یا عیب‌یابی نشست‌های زیرعاملِ مقید به رشته هستید
sidebarTitle: Sub-agents
summary: اجراهای عامل پس‌زمینهٔ ایزوله‌ای را راه‌اندازی کنید که نتایج را به گفت‌وگوی درخواست‌دهنده اعلام می‌کنند
title: عامل‌های فرعی
x-i18n:
    generated_at: "2026-05-02T12:06:56Z"
    model: gpt-5.5
    provider: openai
    source_hash: 0e964df543bd19435daf94f2c85a34b9d32e07662405d2eac7635935f1e7bf64
    source_path: tools/subagents.md
    workflow: 16
---

زیرعامل‌ها اجراهای عامل در پس‌زمینه هستند که از یک اجرای عامل موجود ایجاد می‌شوند.
آن‌ها در نشست خودشان (`agent:<agentId>:subagent:<uuid>`) اجرا می‌شوند و،
پس از پایان، نتیجهٔ خود را به کانال گفت‌وگوی درخواست‌کننده **اعلام** می‌کنند.
هر اجرای زیرعامل به‌عنوان یک
[وظیفهٔ پس‌زمینه](/fa/automation/tasks) ردیابی می‌شود.

اهداف اصلی:

- موازی‌سازی کارهای «پژوهش / وظیفهٔ طولانی / ابزار کند» بدون مسدود کردن اجرای اصلی.
- ایزوله نگه‌داشتن زیرعامل‌ها به‌صورت پیش‌فرض (جداسازی نشست + sandboxing اختیاری).
- سخت‌کردن استفادهٔ نادرست از سطح ابزار: زیرعامل‌ها به‌صورت پیش‌فرض ابزارهای نشست را دریافت نمی‌کنند.
- پشتیبانی از عمق تودرتوی قابل پیکربندی برای الگوهای orchestrator.

<Note>
**یادداشت هزینه:** هر زیرعامل به‌صورت پیش‌فرض زمینه و مصرف توکن خودش را دارد.
برای وظایف سنگین یا تکراری، مدلی ارزان‌تر برای زیرعامل‌ها تنظیم کنید
و عامل اصلی خود را روی مدلی با کیفیت بالاتر نگه دارید. از طریق
`agents.defaults.subagents.model` یا بازنویسی‌های هر عامل پیکربندی کنید. وقتی یک فرزند
    واقعاً به transcript فعلی درخواست‌کننده نیاز دارد، عامل می‌تواند برای همان spawn
    مقدار `context: "fork"` را درخواست کند. نشست‌های زیرعامل وابسته به thread به‌صورت پیش‌فرض
    از `context: "fork"` استفاده می‌کنند، چون گفت‌وگوی فعلی را به یک
    thread پیگیری منشعب می‌کنند.
</Note>

## فرمان Slash

از `/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` فرادادهٔ اجرا را نشان می‌دهد (وضعیت، زمان‌مهرها، شناسهٔ نشست،
مسیر transcript، پاک‌سازی). برای نمای یادآوری محدود و فیلترشده از نظر ایمنی
از `sessions_history` استفاده کنید؛ وقتی به transcript کامل خام نیاز دارید،
مسیر transcript روی دیسک را بررسی کنید.

### کنترل‌های اتصال thread

این فرمان‌ها روی کانال‌هایی کار می‌کنند که از اتصال‌های thread پایدار پشتیبانی می‌کنند.
در پایین، [کانال‌های پشتیبان thread](#thread-supporting-channels) را ببینید.

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

### رفتار spawn

`/subagents spawn` یک زیرعامل پس‌زمینه را به‌عنوان فرمان کاربر شروع می‌کند (نه یک
رلهٔ داخلی) و پس از پایان اجرا، یک به‌روزرسانی نهایی تکمیل را به
گفت‌وگوی درخواست‌کننده می‌فرستد.

<AccordionGroup>
  <Accordion title="تکمیل غیرمسدودکننده و مبتنی بر push">
    - فرمان spawn غیرمسدودکننده است؛ فوراً یک شناسهٔ اجرا برمی‌گرداند.
    - هنگام تکمیل، زیرعامل یک پیام خلاصه/نتیجه به کانال گفت‌وگوی درخواست‌کننده اعلام می‌کند.
    - تکمیل مبتنی بر push است. پس از spawn، فقط برای انتظار پایان، `/subagents list`، `sessions_list` یا `sessions_history` را در یک حلقه poll نکنید؛ وضعیت را فقط در صورت نیاز برای اشکال‌زدایی یا مداخله بررسی کنید.
    - هنگام تکمیل، OpenClaw با بهترین تلاش tabهای مرورگر/فرایندهای ردیابی‌شده‌ای را که توسط آن نشست زیرعامل باز شده‌اند می‌بندد، سپس جریان پاک‌سازی اعلام ادامه پیدا می‌کند.

  </Accordion>
  <Accordion title="تاب‌آوری تحویل spawn دستی">
    - OpenClaw ابتدا تحویل مستقیم `agent` را با یک کلید idempotency پایدار امتحان می‌کند.
    - اگر تحویل مستقیم ناموفق باشد، به مسیریابی صف fallback می‌کند.
    - اگر مسیریابی صف همچنان در دسترس نباشد، اعلام با backoff نمایی کوتاه دوباره تلاش می‌شود، سپس در نهایت رها می‌شود.
    - تحویل تکمیل مسیر حل‌شدهٔ درخواست‌کننده را حفظ می‌کند: مسیرهای تکمیل وابسته به thread یا وابسته به مکالمه، وقتی در دسترس باشند، اولویت دارند؛ اگر مبدأ تکمیل فقط یک کانال فراهم کند، OpenClaw هدف/حساب گمشده را از مسیر حل‌شدهٔ نشست درخواست‌کننده (`lastChannel` / `lastTo` / `lastAccountId`) پر می‌کند تا تحویل مستقیم همچنان کار کند.

  </Accordion>
  <Accordion title="فرادادهٔ واگذاری تکمیل">
    واگذاری تکمیل به نشست درخواست‌کننده، زمینهٔ داخلی تولیدشده در زمان اجرا
    است (نه متن نوشته‌شده توسط کاربر) و شامل این موارد است:

    - `Result` — جدیدترین متن پاسخ قابل مشاهدهٔ `assistant`، در غیر این صورت جدیدترین متن پاک‌سازی‌شدهٔ tool/toolResult. اجراهای شکست‌خوردهٔ پایانی از متن پاسخ ضبط‌شده دوباره استفاده نمی‌کنند.
    - `Status` — `completed successfully` / `failed` / `timed out` / `unknown`.
    - آمار فشردهٔ runtime/توکن.
    - یک دستور تحویل که به عامل درخواست‌کننده می‌گوید با صدای معمول assistant بازنویسی کند (نه اینکه فرادادهٔ داخلی خام را forward کند).

  </Accordion>
  <Accordion title="حالت‌ها و runtime ACP">
    - `--model` و `--thinking` پیش‌فرض‌ها را برای همان اجرای مشخص بازنویسی می‌کنند.
    - از `info`/`log` برای بررسی جزئیات و خروجی پس از تکمیل استفاده کنید.
    - `/subagents spawn` حالت یک‌باره است (`mode: "run"`). برای نشست‌های پایدار وابسته به thread، از `sessions_spawn` با `thread: true` و `mode: "session"` استفاده کنید.
    - برای نشست‌های harness مربوط به ACP (Claude Code، Gemini CLI، OpenCode، یا Codex ACP/acpx صریح)، وقتی ابزار آن runtime را اعلام می‌کند، از `sessions_spawn` با `runtime: "acp"` استفاده کنید. هنگام اشکال‌زدایی تکمیل‌ها یا حلقه‌های عامل‌به‌عامل، [مدل تحویل ACP](/fa/tools/acp-agents#delivery-model) را ببینید. وقتی Plugin `codex` فعال است، کنترل گفت‌وگو/thread در Codex باید `/codex ...` را به ACP ترجیح دهد، مگر اینکه کاربر صریحاً ACP/acpx را بخواهد.
    - OpenClaw تا زمانی که ACP فعال نشده، درخواست‌کننده sandboxed نباشد، و یک Plugin پشتیبان مانند `acpx` بارگذاری نشده باشد، `runtime: "acp"` را پنهان می‌کند. `runtime: "acp"` یک شناسهٔ harness خارجی ACP، یا یک ورودی `agents.list[]` با `runtime.type="acp"` انتظار دارد؛ برای عامل‌های پیکربندی معمول OpenClaw از `agents_list`، از runtime پیش‌فرض زیرعامل استفاده کنید.

  </Accordion>
</AccordionGroup>

## حالت‌های زمینه

زیرعامل‌های بومی به‌صورت ایزوله شروع می‌شوند، مگر اینکه فراخوان صریحاً بخواهد
transcript فعلی را fork کند.

| حالت       | زمان استفاده                                                                                                                         | رفتار                                                                          |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `isolated` | پژوهش تازه، پیاده‌سازی مستقل، کار ابزار کند، یا هر چیزی که بتوان آن را در متن وظیفه خلاصه کرد                           | یک transcript فرزند پاک ایجاد می‌کند. این حالت پیش‌فرض است و مصرف توکن را پایین‌تر نگه می‌دارد.  |
| `fork`     | کاری که به گفت‌وگوی فعلی، نتایج ابزار قبلی، یا دستورهای ظریفی که از قبل در transcript درخواست‌کننده وجود دارند وابسته است | transcript درخواست‌کننده را پیش از شروع فرزند، به نشست فرزند منشعب می‌کند. |

از `fork` با صرفه‌جویی استفاده کنید. این حالت برای واگذاری حساس به زمینه است،
نه جایگزینی برای نوشتن prompt وظیفهٔ روشن.

## ابزار: `sessions_spawn`

یک اجرای زیرعامل را با `deliver: false` روی lane سراسری `subagent` شروع می‌کند،
سپس یک مرحلهٔ اعلام اجرا می‌کند و پاسخ اعلام را به کانال گفت‌وگوی درخواست‌کننده
ارسال می‌کند.

دسترسی به سیاست ابزار مؤثر فراخوان بستگی دارد. پروفایل‌های `coding` و
`full` به‌صورت پیش‌فرض `sessions_spawn` را در معرض قرار می‌دهند. پروفایل `messaging`
این کار را نمی‌کند؛ برای عامل‌هایی که باید کار را واگذار کنند،
`tools.alsoAllow: ["sessions_spawn", "sessions_yield",
"subagents"]` را اضافه کنید یا از `tools.profile: "coding"` استفاده کنید.
سیاست‌های اجازه/رد مربوط به کانال/گروه، provider، sandbox و هر عامل همچنان می‌توانند
پس از مرحلهٔ پروفایل ابزار را حذف کنند. از `/tools` در همان نشست
برای تأیید فهرست ابزار مؤثر استفاده کنید.

**پیش‌فرض‌ها:**

- **مدل:** از فراخوان ارث‌بری می‌کند، مگر اینکه `agents.defaults.subagents.model` را تنظیم کنید (یا `agents.list[].subagents.model` برای هر عامل)؛ مقدار صریح `sessions_spawn.model` همچنان اولویت دارد.
- **Thinking:** از فراخوان ارث‌بری می‌کند، مگر اینکه `agents.defaults.subagents.thinking` را تنظیم کنید (یا `agents.list[].subagents.thinking` برای هر عامل)؛ مقدار صریح `sessions_spawn.thinking` همچنان اولویت دارد.
- **مهلت اجرای run:** اگر `sessions_spawn.runTimeoutSeconds` حذف شود، OpenClaw در صورت تنظیم بودن از `agents.defaults.subagents.runTimeoutSeconds` استفاده می‌کند؛ در غیر این صورت به `0` fallback می‌کند (بدون timeout).

### پارامترهای ابزار

<ParamField path="task" type="string" required>
  شرح وظیفه برای زیرعامل.
</ParamField>
<ParamField path="label" type="string">
  برچسب اختیاری قابل خواندن برای انسان.
</ParamField>
<ParamField path="agentId" type="string">
  وقتی `subagents.allowAgents` اجازه دهد، زیر یک شناسهٔ عامل دیگر spawn کنید.
</ParamField>
<ParamField path="runtime" type='"subagent" | "acp"' default="subagent">
  `acp` فقط برای harnessهای خارجی ACP (`claude`، `droid`، `gemini`، `opencode`، یا Codex ACP/acpx که صریحاً درخواست شده باشد) و برای ورودی‌های `agents.list[]` است که `runtime.type` آن‌ها `acp` است.
</ParamField>
<ParamField path="resumeSessionId" type="string">
  فقط ACP. وقتی `runtime: "acp"` باشد، یک نشست harness موجود ACP را از سر می‌گیرد؛ برای spawnهای زیرعامل بومی نادیده گرفته می‌شود.
</ParamField>
<ParamField path="streamTo" type='"parent"'>
  فقط ACP. وقتی `runtime: "acp"` باشد، خروجی اجرای ACP را به نشست والد stream می‌کند؛ برای spawnهای زیرعامل بومی حذف کنید.
</ParamField>
<ParamField path="model" type="string">
  مدل زیرعامل را بازنویسی می‌کند. مقادیر نامعتبر رد می‌شوند و زیرعامل با یک هشدار در نتیجهٔ ابزار، روی مدل پیش‌فرض اجرا می‌شود.
</ParamField>
<ParamField path="thinking" type="string">
  سطح thinking را برای اجرای زیرعامل بازنویسی می‌کند.
</ParamField>
<ParamField path="runTimeoutSeconds" type="number">
  وقتی تنظیم شده باشد به‌صورت پیش‌فرض `agents.defaults.subagents.runTimeoutSeconds` است، در غیر این صورت `0`. وقتی تنظیم شود، اجرای زیرعامل پس از N ثانیه abort می‌شود.
</ParamField>
<ParamField path="thread" type="boolean" default="false">
  وقتی `true` باشد، اتصال thread کانال را برای این نشست زیرعامل درخواست می‌کند.
</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"` بلافاصله پس از اعلام archive می‌کند (همچنان transcript را از طریق rename نگه می‌دارد).
</ParamField>
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
  `require` مگر اینکه runtime فرزند هدف sandboxed باشد، spawn را رد می‌کند.
</ParamField>
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
  `fork` transcript فعلی درخواست‌کننده را به نشست فرزند منشعب می‌کند. فقط زیرعامل‌های بومی. spawnهای وابسته به thread به‌صورت پیش‌فرض `fork` هستند؛ spawnهای غیر thread به‌صورت پیش‌فرض `isolated` هستند.
</ParamField>

<Warning>
`sessions_spawn` پارامترهای تحویل کانال (`target`،
`channel`، `to`، `threadId`، `replyTo`، `transport`) را نمی‌پذیرد. برای تحویل، از
`message`/`sessions_send` از اجرای spawn‌شده استفاده کنید.
</Warning>

## نشست‌های وابسته به thread

وقتی اتصال‌های thread برای یک کانال فعال باشند، یک زیرعامل می‌تواند به یک thread
متصل بماند تا پیام‌های پیگیری کاربر در آن thread همچنان به همان
نشست زیرعامل مسیریابی شوند.

### کانال‌های پشتیبان thread

**Discord** در حال حاضر تنها کانال پشتیبانی‌شده است. این کانال از
نشست‌های زیرعامل پایدار وابسته به thread (`sessions_spawn` با
`thread: true`)، کنترل‌های دستی thread (`/focus`، `/unfocus`، `/agents`،
`/session idle`، `/session max-age`) و کلیدهای adapter
`channels.discord.threadBindings.enabled`،
`channels.discord.threadBindings.idleHours`،
`channels.discord.threadBindings.maxAgeHours`، و
`channels.discord.threadBindings.spawnSessions` پشتیبانی می‌کند.

### جریان سریع

<Steps>
  <Step title="Spawn">
    `sessions_spawn` با `thread: true` (و به‌صورت اختیاری `mode: "session"`).
  </Step>
  <Step title="اتصال">
    OpenClaw یک thread را به آن هدف نشست در کانال فعال ایجاد یا متصل می‌کند.
  </Step>
  <Step title="مسیریابی پیگیری‌ها">
    پاسخ‌ها و پیام‌های پیگیری در آن thread به نشست متصل‌شده مسیریابی می‌شوند.
  </Step>
  <Step title="بررسی timeoutها">
    از `/session idle` برای بررسی/به‌روزرسانی auto-unfocus در زمان عدم فعالیت و
    از `/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) در بالا را ببینید.

برای جزئیات فعلی آداپتر، [مرجع پیکربندی](/fa/gateway/configuration-reference) و
[فرمان‌های اسلش](/fa/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>

اگر نشست درخواست‌کننده سندباکس شده باشد، `sessions_spawn` هدف‌هایی را که
بدون سندباکس اجرا می‌شوند رد می‌کند.

### کشف

از `agents_list` استفاده کنید تا ببینید کدام شناسه‌های عامل در حال حاضر برای
`sessions_spawn` مجاز هستند. پاسخ شامل مدل مؤثر هر عامل فهرست‌شده
و فرادادهٔ runtime جاسازی‌شده است تا فراخوان‌ها بتوانند PI، سرور برنامهٔ Codex
و runtimeهای بومی پیکربندی‌شدهٔ دیگر را از هم تشخیص دهند.

### بایگانی خودکار

- نشست‌های زیرعامل پس از `agents.defaults.subagents.archiveAfterMinutes` به‌طور خودکار بایگانی می‌شوند (پیش‌فرض `60`).
- بایگانی از `sessions.delete` استفاده می‌کند و رونوشت را به `*.deleted.<timestamp>` تغییر نام می‌دهد (در همان پوشه).
- `cleanup: "delete"` بلافاصله پس از اعلان، بایگانی می‌کند (همچنان رونوشت را با تغییر نام نگه می‌دارد).
- بایگانی خودکار به‌صورت بهترین تلاش است؛ اگر gateway بازراه‌اندازی شود، تایمرهای در انتظار از دست می‌روند.
- `runTimeoutSeconds` بایگانی خودکار انجام نمی‌دهد؛ فقط اجرا را متوقف می‌کند. نشست تا زمان بایگانی خودکار باقی می‌ماند.
- بایگانی خودکار به‌طور یکسان برای نشست‌های عمق ۱ و عمق ۲ اعمال می‌شود.
- پاک‌سازی مرورگر از پاک‌سازی بایگانی جدا است: تب‌ها/فرایندهای مرورگرِ ردیابی‌شده هنگام پایان اجرا به‌صورت بهترین تلاش بسته می‌شوند، حتی اگر رونوشت/رکورد نشست نگه داشته شود.

## زیرعامل‌های تودرتو

به‌طور پیش‌فرض، زیرعامل‌ها نمی‌توانند زیرعامل‌های خودشان را ایجاد کنند
(`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)
      },
    },
  },
}
```

### سطح‌های عمق

| عمق | شکل کلید نشست                            | نقش                                          | می‌تواند ایجاد کند؟                   |
| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
| 0     | `agent:<id>:main`                            | عامل اصلی                                    | همیشه                       |
| 1     | `agent:<id>:subagent:<uuid>`                 | زیرعامل (هماهنگ‌کننده وقتی عمق ۲ مجاز باشد) | فقط اگر `maxSpawnDepth >= 2` |
| 2     | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | زیر-زیرعامل (کارگر برگ)                   | هرگز                        |

### زنجیرهٔ اعلان

نتایج در زنجیره به بالا برمی‌گردند:

1. کارگر عمق ۲ تمام می‌شود → به والد خود اعلان می‌کند (هماهنگ‌کنندهٔ عمق ۱).
2. هماهنگ‌کنندهٔ عمق ۱ اعلان را دریافت می‌کند، نتایج را ترکیب می‌کند، تمام می‌شود → به اصلی اعلان می‌کند.
3. عامل اصلی اعلان را دریافت می‌کند و به کاربر تحویل می‌دهد.

هر سطح فقط اعلان‌های فرزندان مستقیم خود را می‌بیند.

<Note>
**راهنمای عملیاتی:** کار فرزند را یک‌بار شروع کنید و به‌جای ساختن حلقه‌های نظرسنجی پیرامون `sessions_list`،
`sessions_history`، `/subagents list` یا فرمان‌های خواب `exec`، منتظر رویدادهای تکمیل بمانید.
`sessions_list` و `/subagents list` رابطه‌های نشست فرزند را
روی کار زنده متمرکز نگه می‌دارند — فرزندان زنده متصل می‌مانند، فرزندان پایان‌یافته
برای یک بازهٔ کوتاه اخیر قابل مشاهده می‌مانند، و پیوندهای فرزند فقط-ذخیرهٔ کهنه
پس از بازهٔ تازگی‌شان نادیده گرفته می‌شوند. این کار مانع می‌شود فرادادهٔ قدیمی `spawnedBy` /
`parentSessionKey` پس از بازراه‌اندازی فرزندان شبح را دوباره زنده کند. اگر رویداد تکمیل فرزند پس از آن برسد که
پاسخ نهایی را فرستاده‌اید، پیگیری درست همان توکن خاموش دقیق
`NO_REPLY` / `no_reply` است.
</Note>

### سیاست ابزار بر پایهٔ عمق

- نقش و محدودهٔ کنترل هنگام ایجاد در فرادادهٔ نشست نوشته می‌شوند. این کار مانع می‌شود کلیدهای نشست تخت یا بازیابی‌شده به‌اشتباه امتیازهای هماهنگ‌کننده را دوباره به دست آورند.
- **عمق ۱ (هماهنگ‌کننده، وقتی `maxSpawnDepth >= 2`):** `sessions_spawn`، `subagents`، `sessions_list`، `sessions_history` را دریافت می‌کند تا بتواند فرزندانش را مدیریت کند. ابزارهای نشست/سیستم دیگر همچنان رد می‌شوند.
- **عمق ۱ (برگ، وقتی `maxSpawnDepth == 1`):** هیچ ابزار نشستی ندارد (رفتار پیش‌فرض فعلی).
- **عمق ۲ (کارگر برگ):** هیچ ابزار نشستی ندارد — `sessions_spawn` همیشه در عمق ۲ رد می‌شود. نمی‌تواند فرزندان بیشتری ایجاد کند.

### محدودیت ایجاد برای هر عامل

هر نشست عامل (در هر عمقی) می‌تواند هم‌زمان حداکثر `maxChildrenPerAgent`
فرزند فعال داشته باشد (پیش‌فرض `5`). این کار از انشعاب مهارنشده
از سوی یک هماهنگ‌کنندهٔ واحد جلوگیری می‌کند.

### توقف آبشاری

متوقف کردن یک هماهنگ‌کنندهٔ عمق ۱ به‌طور خودکار همهٔ فرزندان عمق ۲ آن را
متوقف می‌کند:

- `/stop` در گفت‌وگوی اصلی همهٔ عامل‌های عمق ۱ را متوقف می‌کند و به فرزندان عمق ۲ آن‌ها آبشار می‌دهد.
- `/subagents kill <id>` یک زیرعامل مشخص را متوقف می‌کند و به فرزندانش آبشار می‌دهد.
- `/subagents kill all` همهٔ زیرعامل‌های درخواست‌کننده را متوقف می‌کند و آبشار می‌دهد.

## احراز هویت

احراز هویت زیرعامل بر اساس **شناسهٔ عامل** حل می‌شود، نه بر اساس نوع نشست:

- کلید نشست زیرعامل `agent:<agentId>:subagent:<uuid>` است.
- ذخیرهٔ احراز هویت از `agentDir` آن عامل بارگذاری می‌شود.
- پروفایل‌های احراز هویت عامل اصلی به‌عنوان **پشتیبان** ادغام می‌شوند؛ در تعارض‌ها، پروفایل‌های عامل بر پروفایل‌های اصلی برتری دارند.

ادغام افزایشی است، بنابراین پروفایل‌های اصلی همیشه به‌عنوان
پشتیبان در دسترس هستند. احراز هویت کاملاً ایزوله برای هر عامل هنوز پشتیبانی نمی‌شود.

## اعلان

زیرعامل‌ها از طریق یک گام اعلان گزارش می‌دهند:

- گام اعلان داخل نشست زیرعامل اجرا می‌شود (نه نشست درخواست‌کننده).
- اگر زیرعامل دقیقاً `ANNOUNCE_SKIP` پاسخ دهد، هیچ چیزی ارسال نمی‌شود.
- اگر آخرین متن assistant همان توکن خاموش دقیق `NO_REPLY` / `no_reply` باشد، خروجی اعلان حتی اگر پیشرفت قابل‌مشاهدهٔ قبلی وجود داشته باشد سرکوب می‌شود.

تحویل به عمق درخواست‌کننده بستگی دارد:

- نشست‌های درخواست‌کنندهٔ سطح بالا از یک فراخوان پیگیری `agent` با تحویل خارجی (`deliver=true`) استفاده می‌کنند.
- نشست‌های زیرعاملِ درخواست‌کنندهٔ تودرتو یک تزریق پیگیری داخلی (`deliver=false`) دریافت می‌کنند تا هماهنگ‌کننده بتواند نتایج فرزند را درون نشست ترکیب کند.
- اگر نشست زیرعاملِ درخواست‌کنندهٔ تودرتو از بین رفته باشد، OpenClaw در صورت دسترس بودن به درخواست‌کنندهٔ آن نشست بازمی‌گردد.

برای نشست‌های درخواست‌کنندهٔ سطح بالا، تحویل مستقیم در حالت تکمیل ابتدا
هر مسیر گفت‌وگو/نخ متصل و بازنویسی hook را حل می‌کند، سپس
فیلدهای هدف-کانالِ گمشده را از مسیر ذخیره‌شدهٔ نشست درخواست‌کننده پر می‌کند.
این کار تکمیل‌ها را روی گفت‌وگو/موضوع درست نگه می‌دارد حتی وقتی مبدأ تکمیل
فقط کانال را شناسایی کند.

تجمیع تکمیل فرزند هنگام ساخت یافته‌های تکمیل تودرتو به اجرای فعلی درخواست‌کننده محدود می‌شود
و از نشت خروجی‌های فرزندِ اجرای قبلی کهنه
به اعلان فعلی جلوگیری می‌کند. پاسخ‌های اعلان در صورت دسترس بودن در آداپترهای کانال،
مسیر نخ/موضوع را حفظ می‌کنند.

### زمینهٔ اعلان

زمینهٔ اعلان به یک بلوک رویداد داخلی پایدار نرمال‌سازی می‌شود:

| فیلد          | منبع                                                                                                        |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| منبع         | `subagent` یا `cron`                                                                                          |
| شناسه‌های نشست    | کلید/شناسهٔ نشست فرزند                                                                                          |
| نوع           | نوع اعلان + برچسب کار                                                                                    |
| وضعیت         | مشتق‌شده از نتیجهٔ runtime (`success`، `error`، `timeout` یا `unknown`) — **نه** استنباط‌شده از متن مدل |
| محتوای نتیجه | آخرین متن قابل‌مشاهدهٔ assistant، در غیر این صورت آخرین متن ابزار/toolResult پاک‌سازی‌شده                                |
| پیگیری      | دستورالعملی که توضیح می‌دهد چه زمانی پاسخ دهید و چه زمانی خاموش بمانید                                                           |

اجراهای ناموفق نهایی، وضعیت شکست را بدون بازپخش متن پاسخِ
ضبط‌شده گزارش می‌کنند. هنگام timeout، اگر فرزند فقط تا فراخوانی‌های ابزار پیش رفته باشد، اعلان
می‌تواند آن تاریخچه را به یک خلاصهٔ کوتاه از پیشرفت جزئی فشرده کند
به‌جای بازپخش خروجی خام ابزار.

### خط آمار

payloadهای اعلان در پایان یک خط آمار دارند (حتی وقتی بسته‌بندی شده باشند):

- Runtime (مثلاً `runtime 5m12s`).
- مصرف توکن (ورودی/خروجی/کل).
- هزینهٔ تخمینی وقتی قیمت‌گذاری مدل پیکربندی شده باشد (`models.providers.*.models[].cost`).
- `sessionKey`، `sessionId` و مسیر رونوشت تا عامل اصلی بتواند تاریخچه را از طریق `sessions_history` واکشی کند یا فایل روی دیسک را بررسی کند.

فرادادهٔ داخلی فقط برای هماهنگ‌سازی در نظر گرفته شده است؛ پاسخ‌های کاربرمحور
باید با صدای معمول assistant بازنویسی شوند.

### چرا `sessions_history` را ترجیح دهیم

`sessions_history` مسیر هماهنگ‌سازی امن‌تری است:

- یادآوری assistant ابتدا نرمال‌سازی می‌شود: تگ‌های تفکر حذف می‌شوند؛ داربست `<relevant-memories>` / `<relevant_memories>` حذف می‌شود؛ بلوک‌های payload XML فراخوانی ابزارِ متن ساده (`<tool_call>`، `<function_call>`، `<tool_calls>`، `<function_calls>`) حذف می‌شوند، شامل payloadهای بریده‌ای که هرگز تمیز بسته نمی‌شوند؛ داربست فراخوانی/نتیجهٔ ابزارِ تنزل‌یافته و نشانگرهای زمینهٔ تاریخی حذف می‌شوند؛ توکن‌های کنترل مدلِ نشت‌کرده (`<|assistant|>`، سایر ASCII `<|...|>`، تمام‌عرض `<｜...｜>`) حذف می‌شوند؛ XML فراخوانی ابزار MiniMax بدشکل حذف می‌شود.
- متن‌های شبیه اعتبارنامه/توکن ردکت می‌شوند.
- بلوک‌های طولانی می‌توانند کوتاه شوند.
- تاریخچه‌های بسیار بزرگ می‌توانند ردیف‌های قدیمی‌تر را حذف کنند یا یک ردیف بیش‌ازحد بزرگ را با `[sessions_history omitted: message too large]` جایگزین کنند.
- بررسی رونوشت خام روی دیسک گزینهٔ پشتیبان است وقتی به رونوشت کامل بایت‌به‌بایت نیاز دارید.

## سیاست ابزار

زیرعامل‌ها ابتدا همان پروفایل و pipeline سیاست ابزارِ والد یا
عامل هدف را استفاده می‌کنند. پس از آن، OpenClaw لایهٔ محدودیت
زیرعامل را اعمال می‌کند.

بدون `tools.profile` محدودکننده، زیرعامل‌ها **همهٔ ابزارها به‌جز
ابزارهای نشست** و ابزارهای سیستم را دریافت می‌کنند:

- `sessions_list`
- `sessions_history`
- `sessions_send`
- `sessions_spawn`

`sessions_history` در اینجا نیز یک نمای یادآوری محدود و پاک‌سازی‌شده باقی می‌ماند —
dump خام رونوشت نیست.

وقتی `maxSpawnDepth >= 2` باشد، زیرعامل‌های هماهنگ‌کنندهٔ عمق ۱ علاوه بر این
`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` را شامل نمی‌شود. برای اینکه زیرعامل‌های دارای پروفایل coding بتوانند از خودکارسازی مرورگر استفاده کنند، 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"` از طریق احراز هویت مستقیم loopback با توکن/گذرواژه مشترک وصل شود؛ این مسیر به خط مبنای دامنه دستگاه جفت‌شده CLI وابسته نیست. فراخوان‌های راه‌دور، `deviceIdentity` صریح، مسیرهای صریح device-token، و کلاینت‌های مرورگر/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](/fa/tools/acp-agents)
- [ارسال عامل](/fa/tools/agent-send)
- [وظایف پس‌زمینه](/fa/automation/tasks)
- [ابزارهای sandbox چندعاملی](/fa/tools/multi-agent-sandbox-tools)
