زیرعامل‌ها

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

اهداف:

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

دستور اسلش

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

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

/subagents info فرادادهٔ اجرا (وضعیت، مُهرهای زمانی، شناسهٔ نشست، مسیر رونوشت و پاک‌سازی) را نشان می‌دهد. /subagents log نوبت‌های اخیر گفت‌وگوی یک اجرا را چاپ می‌کند؛ برای افزودن پیام‌های فراخوانی ابزار/نتیجه، توکن tools را اضافه کنید (به‌طور پیش‌فرض حذف می‌شوند). برای بازیابی محدود و پالایش‌شده از نظر ایمنی درون یک نوبت عامل، از sessions_history استفاده کنید، یا برای مشاهدهٔ رونوشت کامل و خام، مسیر رونوشت روی دیسک را بررسی کنید.

کنترل‌های اتصال به رشته

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

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

رفتار ایجاد

عامل‌ها زیرعامل‌های پس‌زمینه را با ابزار sessions_spawn آغاز می‌کنند. نتیجهٔ تکمیل‌ها به‌صورت رویدادهای داخلی نشست والد بازمی‌گردد؛ عامل والد/درخواست‌کننده تصمیم می‌گیرد که آیا به‌روزرسانی قابل‌مشاهده برای کاربر لازم است یا نه.

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

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

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

ابزار: sessions_spawn

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

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

پیش‌فرض‌ها:

• مدل: زیرعامل‌های بومی از فراخواننده ارث می‌برند، مگر اینکه agents.defaults.subagents.model (یا agents.list[].subagents.model مخصوص هر عامل) را تنظیم کنید. ایجادهای زمان اجرای ACP نیز در صورت وجود از همان مدل پیکربندی‌شدهٔ زیرعامل استفاده می‌کنند؛ در غیر این صورت، چارچوب ACP پیش‌فرض خودش را نگه می‌دارد. مقدار صریح sessions_spawn.model همچنان اولویت دارد.
• تفکر: زیرعامل‌های بومی از فراخواننده ارث می‌برند، مگر اینکه agents.defaults.subagents.thinking (یا agents.list[].subagents.thinking مخصوص هر عامل) را تنظیم کنید. ایجادهای زمان اجرای ACP همچنین agents.defaults.models["provider/model"].params.thinking را برای مدل انتخاب‌شده اعمال می‌کنند. مقدار صریح sessions_spawn.thinking همچنان اولویت دارد.
• مهلت اجرای کار: OpenClaw در صورت تنظیم، از agents.defaults.subagents.runTimeoutSeconds استفاده می‌کند؛ در غیر این صورت به 0 (بدون مهلت) بازمی‌گردد. sessions_spawn بازنویسی مهلت برای هر فراخوانی را نمی‌پذیرد.
• تحویل وظیفه: زیرعامل‌های بومی وظیفهٔ واگذارشده را در نخستین پیام قابل‌مشاهدهٔ [Subagent Task] دریافت می‌کنند. درخواست سیستمی زیرعامل شامل قواعد زمان اجرا و زمینهٔ مسیریابی است، نه نسخهٔ پنهان و تکراری وظیفه.

ایجادهای پذیرفته‌شدهٔ زیرعامل بومی، فرادادهٔ مدل حل‌شدهٔ فرزند را در نتیجهٔ ابزار شامل می‌شوند: resolvedModel ارجاع مدل اعمال‌شده را در بر دارد و وقتی ارجاع دارای پیشوند باشد، resolvedProvider پیشوند ارائه‌دهنده را شامل می‌شود.

حالت درخواست واگذاری

agents.defaults.subagents.delegationMode فقط راهنمایی درخواست را کنترل می‌کند؛ سیاست ابزار را تغییر نمی‌دهد و واگذاری را اجباری نمی‌کند.

• suggest (پیش‌فرض): یادآوری استاندارد درخواست برای استفاده از زیرعامل‌ها در کارهای بزرگ‌تر یا کندتر را حفظ می‌کند.
• prefer: به عامل اصلی می‌گوید پاسخ‌گو بماند و هر کاری پیچیده‌تر از یک پاسخ مستقیم را از طریق sessions_spawn واگذار کند.

بازنویسی مخصوص هر عامل: agents.list[].subagents.delegationMode.

{  agents: {    defaults: {      subagents: {        delegationMode: "prefer",        maxConcurrent: 4,      },    },    list: [      {        id: "coordinator",        subagents: { delegationMode: "prefer" },      },    ],  },}

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

نام‌گذاری وظیفه‌ها و هدف‌گیری

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 استفاده کنید.

نشست‌های متصل به رشته

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

کانال‌های پشتیبان رشته

یک کانال زمانی از نشست‌های پایدار زیرعامل متصل به رشته (sessions_spawn با thread: true) پشتیبانی می‌کند که یک سازگارکنندهٔ اتصال مکالمه ثبت کند. کانال‌های همراه دارای این پشتیبانی عبارت‌اند از: Discord، iMessage، Matrix و Telegram. Discord و Matrix به‌طور پیش‌فرض یک رشتهٔ فرزند ایجاد می‌کنند؛ Telegram و iMessage به‌طور پیش‌فرض مکالمهٔ فعلی را متصل می‌کنند. برای فعال‌سازی، مهلت‌ها و spawnSessions از کلیدهای پیکربندی threadBindings مختص هر کانال استفاده کنید.

روند سریع

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

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

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

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

فهرست مجاز

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

کشف

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

ورودی‌های allowAgents باید به شناسه‌های عامل پیکربندی‌شده در agents.list[] اشاره کنند. ["*"] یعنی هر عامل هدف پیکربندی‌شده به‌علاوهٔ درخواست‌کننده. اگر پیکربندی عاملی حذف شود اما شناسهٔ آن در allowAgents باقی بماند، sessions_spawn آن شناسه را رد می‌کند و agents_list آن را نمایش نمی‌دهد. برای پاک‌سازی ورودی‌های قدیمی فهرست مجاز، openclaw doctor --fix را اجرا کنید، یا وقتی هدف باید ضمن به‌ارث‌بردن پیش‌فرض‌ها همچنان قابل ایجاد بماند، یک ورودی حداقلی agents.list[] اضافه کنید.

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

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

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

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

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // اجازه به زیرعامل‌ها برای ایجاد فرزند (پیش‌فرض: 1، بازهٔ 1-5)        maxChildrenPerAgent: 5, // حداکثر فرزندان فعال در هر نشست عامل (پیش‌فرض: 5، بازهٔ 1-20)        maxConcurrent: 8, // سقف سراسری مسیر هم‌زمانی (پیش‌فرض: 8)        runTimeoutSeconds: 900, // مهلت پیش‌فرض برای sessions_spawn (0 = بدون مهلت)        announceTimeoutMs: 120000, // مهلت اعلام Gateway برای هر فراخوانی      },    },  },}

سطوح عمق

زنجیره اعلان

نتایج در طول زنجیره به سطوح بالاتر بازمی‌گردند:

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

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

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

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

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

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

توقف آبشاری

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

• /stop در گفت‌وگوی اصلی همه عامل‌های عمق ۱ را متوقف می‌کند و توقف را به فرزندان عمق ۲ آن‌ها گسترش می‌دهد.

احراز هویت

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

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

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

اعلان

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

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

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

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

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

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

زمینه اعلان

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

اجراهای پایانی ناموفق، وضعیت شکست را بدون بازپخش متن پاسخ ثبت‌شده گزارش می‌کنند. خروجی tool/toolResult به متن نتیجه فرزند ارتقا نمی‌یابد.

خط آمار

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

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

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

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

sessions_history مسیر هماهنگ‌سازی امن‌تری برای خواندن رونوشت فرزند از درون نوبت عامل است:

• متن‌های شبیه اعتبارنامه/توکن را حتی هنگامی که پوشاندن عمومی گزارش‌ها غیرفعال است، می‌پوشاند.
• بلوک‌های متنی طولانی را کوتاه می‌کند (۴۰۰۰ نویسه برای هر بلوک) و امضاهای تفکر، بارهای بازپخش استدلال و داده‌های تصویر درون‌خطی را حذف می‌کند.
• سقف پاسخ ۸۰ کیلوبایت را اعمال می‌کند؛ ردیف‌های بیش‌ازحد بزرگ با [sessions_history omitted: message too large] جایگزین می‌شوند.
• در صورت وجود nextOffset، از آن برای صفحه‌بندی رو به عقب در پنجره‌های قدیمی‌تر رونوشت استفاده کنید.
• sessions_history برچسب‌های استدلال، داربست <relevant-memories> یا XML فراخوانی ابزار را از متن پیام حذف نمی‌کند — بلوک‌های محتوای ساخت‌یافته نزدیک به شکل خام رونوشت را برمی‌گرداند که فقط پوشانده و از نظر اندازه محدود شده‌اند. /subagents log پاک‌سازی متنی سنگین‌تری را اعمال می‌کند (برچسب‌های استدلال، داربست حافظه و XML فراخوانی ابزار را حذف می‌کند)، زیرا به‌جای بلوک‌های ساخت‌یافته، خطوط گفت‌وگوی ساده را نمایش می‌دهد.
• بررسی رونوشت خام روی دیسک، زمانی که به رونوشت کامل و دقیق بایت‌به‌بایت نیاز دارید، مسیر جایگزین است.

سیاست ابزار

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

زیرعامل‌ها صرف‌نظر از عمق یا نقش، همیشه دسترسی به gateway، agents_list، session_status و cron را از دست می‌دهند (ابزارهای سطح سیستم/تعاملی یا ابزارهایی که عامل اصلی باید هماهنگ کند). زیرعامل‌های نهایی (رفتار پیش‌فرض عمق ۱ و همیشه در عمق ۲) علاوه بر این دسترسی به subagents، sessions_list، sessions_history و sessions_spawn را از دست می‌دهند. زیرعامل‌ها هرگز ابزار message را دریافت نمی‌کنند — این ابزار هنگام ایجاد غیرفعال می‌شود، نه اینکه توسط این فهرست منع فیلتر شود — و sessions_send نیز ممنوع می‌ماند تا زیرعامل‌ها فقط از طریق زنجیره اعلان ارتباط برقرار کنند.

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 را شامل نمی‌شود. برای اینکه زیرعامل‌های پروفایل کدنویسی بتوانند از خودکارسازی مرورگر استفاده کنند، مرورگر را در مرحله پروفایل اضافه کنید:

{  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 در گفت‌وگوی درخواست‌کننده، نشست درخواست‌کننده را متوقف می‌کند و همه اجراهای فعال زیرعامل ایجادشده از آن را نیز متوقف می‌کند؛ این توقف به فرزندان تو‌در‌تو نیز گسترش می‌یابد.

محدودیت‌ها

• اعلام زیرعامل به‌صورت نهایت تلاش انجام می‌شود. اگر Gateway راه‌اندازی مجدد شود، کارهای در انتظار برای «اعلام نتیجه به والد» از دست می‌روند.
• زیرعامل‌ها همچنان منابع همان فرایند Gateway را به اشتراک می‌گذارند؛ maxConcurrent را به‌عنوان یک سازوکار ایمنی در نظر بگیرید.
• sessions_spawn همیشه غیربلوکه‌کننده است: بلافاصله { status: "accepted", runId, childSessionKey } را برمی‌گرداند.
• زمینهٔ زیرعامل فقط AGENTS.md و TOOLS.md را وارد می‌کند (بدون SOUL.md، IDENTITY.md، USER.md، MEMORY.md، HEARTBEAT.md یا BOOTSTRAP.md). زیرعامل‌های بومی Codex نیز از همین مرز پیروی می‌کنند: TOOLS.md در دستورالعمل‌های به‌ارث‌رسیدهٔ رشتهٔ Codex باقی می‌ماند، درحالی‌که فایل‌های شخصیت، هویت و کاربرِ مختص والد به‌صورت دستورالعمل‌های همکاریِ محدود به نوبت وارد می‌شوند تا فرزندان آن‌ها را همانندسازی نکنند.
• حداکثر عمق تودرتویی ۵ است (محدودهٔ maxSpawnDepth: ۱ تا ۵). برای بیشتر موارد استفاده، عمق ۲ توصیه می‌شود.
• maxChildrenPerAgent تعداد فرزندان فعال در هر نشست را محدود می‌کند (پیش‌فرض 5، محدودهٔ 1-20).

مرتبط

• ابزارهای نشست و تغییرات وضعیت
• عامل‌های ACP
• ارسال عامل
• وظایف پس‌زمینه
• ابزارهای محیط ایزولهٔ چندعاملی