عامل‌های فرعی

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

برای مدل امنیتی پشت واگذاری، ببینید مرزهای چندعاملی و زیرعامل. زیرعامل‌ها واحدهای مفیدی برای ایزوله‌سازی و جریان کاری هستند، اما درون یک Gateway مشترک، مرز مجوزدهی چندمستاجریِ خصمانه نیستند.

هدف‌های اصلی:

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

# دستور slash

از /subagents برای بررسی یا کنترل اجراهای زیرعامل برای نشست فعلی استفاده کنید:

/subagents list
/subagents kill <id|#|all>
/subagents log <id|#> [limit] [tools]
/subagents info <id|#>
/subagents send <id|#> <message>
/subagents steer <id|#> <message>
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]

از /steer <message> در سطح بالا برای هدایت اجرای فعال نشست درخواست‌دهندهٔ فعلی استفاده کنید. وقتی هدف یک اجرای فرزند است، از /subagents steer <id|#> <message> استفاده کنید.

/subagents info فرادادهٔ اجرا را نشان می‌دهد (وضعیت، زمان‌نماها، شناسهٔ نشست، مسیر رونوشت، پاک‌سازی). برای یک نمای یادآوری محدود و فیلترشده از نظر ایمنی از sessions_history استفاده کنید؛ وقتی به رونوشت کامل خام نیاز دارید، مسیر رونوشت روی دیسک را بررسی کنید.

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

این دستورها روی کانال‌هایی کار می‌کنند که از اتصال‌های پایدار thread پشتیبانی می‌کنند. در پایین کانال‌های پشتیبان thread را ببینید.

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

# رفتار ایجاد

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

# حالت‌های context

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

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

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

# ابزار: sessions_spawn

یک اجرای زیرعامل را با deliver: false روی مسیر سراسری 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 (بدون مهلت) برمی‌گردد.

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

taskstringrequired

شرح وظیفه برای زیرعامل.

labelstring

برچسب اختیاریِ خوانا برای انسان.

agentIdstring

وقتی subagents.allowAgents اجازه دهد، زیر یک شناسهٔ عامل دیگر ایجاد می‌شود.

runtime"subagent" | "acp"

acp فقط برای harnessهای خارجی ACP (claude، droid، gemini، opencode، یا Codex ACP/acpx که صریحا درخواست شده باشد) و برای ورودی‌های agents.list[] است که runtime.type آن‌ها acp است.

resumeSessionIdstring

فقط ACP. وقتی runtime: "acp" باشد، یک نشست harness موجود ACP را از سر می‌گیرد؛ برای ایجادهای native زیرعامل نادیده گرفته می‌شود.

streamTo"parent"

فقط ACP. وقتی runtime: "acp" باشد، خروجی اجرای ACP را به نشست والد stream می‌کند؛ برای ایجادهای native زیرعامل حذف کنید.

modelstring

مدل زیرعامل را override کنید. مقادیر نامعتبر رد می‌شوند و زیرعامل با یک هشدار در نتیجهٔ ابزار، روی مدل پیش‌فرض اجرا می‌شود.

thinkingstring

سطح thinking را برای اجرای زیرعامل override کنید.

runTimeoutSecondsnumber

وقتی تنظیم شده باشد به‌صورت پیش‌فرض agents.defaults.subagents.runTimeoutSeconds است، وگرنه 0. وقتی تنظیم شود، اجرای زیرعامل پس از N ثانیه متوقف می‌شود.

threadboolean

وقتی true باشد، اتصال thread کانال را برای این نشست زیرعامل درخواست می‌کند.

mode"run" | "session"

اگر thread: true باشد و mode حذف شده باشد، پیش‌فرض session می‌شود. mode: "session" به thread: true نیاز دارد.

cleanup"delete" | "keep"

"delete" بلافاصله پس از اعلام آرشیو می‌کند (همچنان رونوشت را از طریق تغییر نام نگه می‌دارد).

sandbox"inherit" | "require"

require ایجاد را رد می‌کند، مگر اینکه runtime فرزند هدف sandbox شده باشد.

context"isolated" | "fork"

fork رونوشت فعلی درخواست‌دهنده را به نشست فرزند شاخه‌بندی می‌کند. فقط زیرعامل‌های native. ایجادهای وابسته به thread به‌صورت پیش‌فرض fork هستند؛ ایجادهای غیر-thread به‌صورت پیش‌فرض isolated هستند.

# نشست‌های وابسته به 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 پشتیبانی می‌کند.

# جریان سریع

# کنترل‌های دستی

فرمان	اثر
/focus <target>	رشته فعلی را (یا یک رشته ایجاد کند و آن را) به هدف زیرعامل/نشست متصل می‌کند
/unfocus	اتصال رشته متصل فعلی را حذف می‌کند
/agents	اجراهای فعال و وضعیت اتصال را فهرست می‌کند (thread:<id> یا unbound)
/session idle	خروج خودکار از تمرکز هنگام بی‌کاری را بررسی/به‌روزرسانی می‌کند (فقط رشته‌های متصلِ متمرکز)
/session max-age	سقف سخت را بررسی/به‌روزرسانی می‌کند (فقط رشته‌های متصلِ متمرکز)

# سوییچ‌های پیکربندی

• پیش‌فرض سراسری: session.threadBindings.enabled، session.threadBindings.idleHours، session.threadBindings.maxAgeHours.
• کلیدهای بازنویسی کانال و اتصال خودکار هنگام ایجاد نشست مختص آداپتور هستند. به کانال‌های پشتیبان رشته در بالا مراجعه کنید.

برای جزئیات فعلی آداپتور، مرجع پیکربندی و فرمان‌های اسلش را ببینید.

# فهرست مجاز

agents.list[].subagents.allowAgentsstring[]

فهرست شناسه‌های عامل که می‌توانند از طریق agentId صریح هدف قرار گیرند (["*"] هر موردی را مجاز می‌کند). پیش‌فرض: فقط عامل درخواست‌دهنده. اگر فهرستی تنظیم می‌کنید و همچنان می‌خواهید درخواست‌دهنده خودش را با agentId ایجاد کند، شناسه درخواست‌دهنده را در فهرست قرار دهید.

agents.defaults.subagents.allowAgentsstring[]

فهرست مجاز پیش‌فرض عامل‌های هدف که وقتی عامل درخواست‌دهنده subagents.allowAgents خودش را تنظیم نکرده باشد استفاده می‌شود.

agents.defaults.subagents.requireAgentIdboolean

فراخوانی‌های sessions_spawn را که agentId را حذف می‌کنند مسدود می‌کند (انتخاب صریح پروفایل را اجباری می‌کند). بازنویسی برای هر عامل: agents.list[].subagents.requireAgentId.

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

# کشف

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

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

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

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

به‌طور پیش‌فرض، زیرعامل‌ها نمی‌توانند زیرعامل‌های خودشان را ایجاد کنند (maxSpawnDepth: 1). برای فعال کردن یک سطح از تو در تو بودن، maxSpawnDepth: 2 را تنظیم کنید — الگوی هماهنگ‌کننده: اصلی → زیرعامل هماهنگ‌کننده → زیرزیرعامل‌های کاری.

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)
        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)
        maxConcurrent: 8, // global concurrency lane cap (default: 8)
        runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout)
      },
    },
  },
}

# سطوح عمق

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

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

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

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

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

# سیاست ابزار بر اساس عمق

• نقش و دامنه کنترل هنگام ایجاد نشست در فراداده نشست نوشته می‌شوند. این باعث می‌شود کلیدهای نشست تخت یا بازیابی‌شده به‌طور تصادفی امتیازهای هماهنگ‌کننده را دوباره به دست نیاورند.
• عمق ۱ (هماهنگ‌کننده، وقتی 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 پاسخ دهد، چیزی پست نمی‌شود.
• اگر آخرین متن دستیار همان توکن ساکت دقیق NO_REPLY / no_reply باشد، خروجی اعلام سرکوب می‌شود حتی اگر پیشرفت قابل مشاهده قبلی وجود داشته باشد.

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

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

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

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

# زمینه اعلام

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

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

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

# خط آمار

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

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

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

# چرا sessions_history ترجیح داده می‌شود

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

• یادآوری دستیار ابتدا نرمال‌سازی می‌شود: تگ‌های تفکر حذف می‌شوند؛ چارچوب‌بندی <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] جایگزین کنند.
• بررسی رونوشت خام روی دیسک گزینه پشتیبان است وقتی به رونوشت کاملِ بایت‌به‌بایت نیاز دارید.

# سیاست ابزار

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

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

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

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

وقتی maxSpawnDepth >= 2 باشد، زیرعامل‌های هماهنگ‌کنندهٔ عمق ۱ علاوه بر این sessions_spawn، subagents، sessions_list و sessions_history را دریافت می‌کنند تا بتوانند فرزندان خود را مدیریت کنند.

# بازنویسی از طریق پیکربندی

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // deny wins
        deny: ["gateway", "cron"],
        // if allow is set, it becomes allow-only (deny still wins)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

tools.subagents.tools.allow یک فیلتر نهایی فقط-مجاز است. می‌تواند مجموعهٔ ابزارهای ازپیش‌حل‌شده را محدودتر کند، اما نمی‌تواند ابزاری را که توسط tools.profile حذف شده است دوباره اضافه کند. برای مثال، tools.profile: "coding" شامل web_search/web_fetch است اما ابزار browser را شامل نمی‌شود. برای اینکه زیرعامل‌های پروفایل کدنویسی بتوانند از اتوماسیون مرورگر استفاده کنند، browser را در مرحلهٔ پروفایل اضافه کنید:

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

وقتی فقط یک عامل باید اتوماسیون مرورگر دریافت کند، از agents.list[].tools.alsoAllow: ["browser"] برای همان عامل استفاده کنید.

# هم‌روندی

زیرعامل‌ها از یک مسیر صف اختصاصی درون‌فرایندی استفاده می‌کنند:

• نام مسیر: subagent
• هم‌روندی: agents.defaults.subagents.maxConcurrent (پیش‌فرض 8)

# زنده‌بودن و بازیابی

OpenClaw نبودِ endedAt را مدرک دائمی زنده بودن یک زیرعامل تلقی نمی‌کند. اجراهای پایان‌نیافته‌ای که از پنجرهٔ اجرای کهنه قدیمی‌تر باشند، دیگر در /subagents list، خلاصه‌های وضعیت، دروازه‌گذاری تکمیل فرزندان، و بررسی‌های هم‌روندی هر جلسه به‌عنوان فعال/در انتظار شمرده نمی‌شوند.

پس از راه‌اندازی مجدد Gateway، اجراهای بازیابی‌شدهٔ کهنه و پایان‌نیافته هرس می‌شوند، مگر اینکه جلسهٔ فرزند آن‌ها با abortedLastRun: true علامت‌گذاری شده باشد. آن جلسه‌های فرزند که با راه‌اندازی مجدد متوقف شده‌اند از طریق جریان بازیابی یتیم زیرعامل همچنان قابل بازیابی می‌مانند؛ این جریان پیش از پاک کردن نشانگر توقف، یک پیام ادامهٔ مصنوعی ارسال می‌کند.

بازیابی خودکار پس از راه‌اندازی مجدد، برای هر جلسهٔ فرزند محدود است. اگر همان فرزند زیرعامل به‌طور مکرر درون پنجرهٔ گیرکردن سریع برای بازیابی یتیم پذیرفته شود، OpenClaw یک سنگ‌نشان بازیابی روی آن جلسه پایدار می‌کند و در راه‌اندازی‌های مجدد بعدی دیگر آن را خودکار ادامه نمی‌دهد. برای همساز کردن رکورد وظیفه، openclaw tasks maintenance --apply را اجرا کنید، یا برای پاک کردن پرچم‌های کهنهٔ بازیابیِ متوقف‌شده روی جلسه‌های سنگ‌نشان‌شده، openclaw doctor --fix را اجرا کنید.

# توقف

• ارسال /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).
• بیشینهٔ عمق تودرتویی ۵ است (بازهٔ maxSpawnDepth: ۱–۵). عمق ۲ برای بیشتر کاربردها توصیه می‌شود.
• maxChildrenPerAgent سقف فرزندان فعال برای هر جلسه را تعیین می‌کند (پیش‌فرض 5، بازهٔ 1–20).

# مرتبط

• عامل‌های ACP
• ارسال عامل
• وظایف پس‌زمینه
• ابزارهای سندباکس چندعاملی