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

زیرعامل‌ها اجراهای پس‌زمینهٔ عامل هستند که از یک اجرای عامل موجود ایجاد می‌شوند. هرکدام در نشست خود (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 راه‌اندازی مجدد شود، زمان‌سنج‌های در انتظار از دست می‌روند.
• مهلت‌های اجرای پیکربندی‌شده به‌طور خودکار بایگانی نمی‌کنند؛ آن‌ها فقط اجرا را متوقف می‌کنند. نشست تا زمان بایگانی خودکار باقی می‌ماند.
• بایگانی خودکار به‌طور یکسان برای نشست‌های عمق 1 و عمق 2 اعمال می‌شود.
• پاک‌سازی مرورگر از پاک‌سازی بایگانی جدا است: هنگام پایان اجرا، برگه‌ها/فرایندهای مرورگر ردیابی‌شده بر مبنای بهترین تلاش بسته می‌شوند، حتی اگر رونوشت/رکورد نشست نگه داشته شود.

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

به‌طور پیش‌فرض، زیرعامل‌ها نمی‌توانند زیرعامل‌های خودشان را ایجاد کنند (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 کارش را تمام می‌کند ← به والد خود (هماهنگ‌کننده عمق 1) اعلام می‌کند.
2. هماهنگ‌کننده عمق 1 اعلام را دریافت می‌کند، نتایج را ترکیب می‌کند و کارش را تمام می‌کند ← به عامل اصلی اعلام می‌کند.
3. عامل اصلی اعلام را دریافت می‌کند و نتیجه را به کاربر تحویل می‌دهد.

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

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

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

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

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

توقف آبشاری

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

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

احراز هویت

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

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

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

اعلام

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

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

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

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

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

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

زمینه اعلام

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

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

خط آمار

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

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

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

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

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

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

سیاست ابزار

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

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

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

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

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

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

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

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

هم‌زمانی

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

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

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

OpenClaw نبود endedAt را مدرک دائمی زنده‌بودن یک زیرعامل تلقی نمی‌کند. اجراهای پایان‌نیافته‌ای که از پنجره اجرای منقضی‌شده قدیمی‌ترند (2 ساعت، یا مهلت اجرای پیکربندی‌شده به‌اضافه یک دوره مهلت کوتاه، هرکدام طولانی‌تر باشد) دیگر در /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 باقی می‌ماند، درحالی‌که پرسونای مختص والد، هویت و فایل‌های کاربر به‌صورت دستورالعمل‌های همکاری محدود به نوبت تزریق می‌شوند تا فرزندان آن‌ها را شبیه‌سازی نکنند.
• حداکثر عمق تودرتویی 5 است (بازه maxSpawnDepth: 1-5). عمق 2 برای بیشتر موارد استفاده توصیه می‌شود.
• maxChildrenPerAgent تعداد فرزندان فعال در هر نشست را محدود می‌کند (مقدار پیش‌فرض 5، بازه 1-20).

مرتبط

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