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

زیرعامل‌ها اجراهای پس‌زمینه‌ای عامل هستند که از یک اجرای عامل موجود ایجاد می‌شوند. هرکدام در نشست مخصوص خود (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 و messaging شامل sessions_spawn، sessions_yield و subagents هستند؛ minimal شامل آن‌ها نیست. full همهٔ ابزارها را مجاز می‌کند. برای عاملی با پروفایل سفارشی محدودتر که همچنان باید کار را تفویض کند، این ابزارها را با tools.alsoAllow اضافه کنید یا یکی از پروفایل‌های بالا را به‌کار ببرید. خط‌مشی‌های کانال/گروه، ارائه‌دهنده، سندباکس و مجاز/غیرمجاز مختص هر عامل همچنان می‌توانند ابزار را پس از مرحلهٔ پروفایل حذف کنند. برای تأیید فهرست مؤثر ابزار، از همان نشست /tools را به‌کار ببرید.

پیش‌فرض‌ها:

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

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

حالت درخواست تفویض

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

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

بازنویسی مختص هر عامل: agents.entries.*.subagents.delegationMode.

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

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

با visible: true، از model، cwd و یک context: "fork" متعلق به همان عامل پشتیبانی می‌شود. هدفِ در محیط ایزوله، cwd را به فضای کاری همان عامل محدود می‌کند. اتصال رشته، mode، بازنویسی‌های تفکر، lightContext، attachments و attachAs در این مسیر در دسترس نیستند، زیرا نشست‌های قابل‌مشاهده، نشست‌های پایدار داشبورد هستند که از طریق sessions.create ایجاد می‌شوند. اگر خود درخواست‌کننده با فهرست مجاز یا فهرست ممنوع ابزارِ ارث‌برده‌شده ایجاد شده باشد، ایجاد قابل‌مشاهده رد می‌شود؛ این محدودیت هنگام ایجاد تثبیت می‌شود و هیچ بازنویسی پیکربندی ندارد. فهرست‌کردن و آدرس‌دهی نشست‌ها از tools.sessions.visibility پیروی می‌کند؛ دامنهٔ پیش‌فرض tree نشست فعلی و زیردرخت ایجادشدهٔ خودش را پوشش می‌دهد. برای رفتار نام‌گذاری، راه‌اندازی، پاک‌سازی و بازیابی checkout، به درخت‌های کاری مدیریت‌شده مراجعه کنید.

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

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

اجراهای زیرعامل ایجادشده و رکوردهای وظیفهٔ پس‌زمینهٔ متعلق به درخت نشست درخواست‌کننده را فهرست می‌کند. ردیف‌های وظیفه، زیرعامل‌های بومی، اجراهای ACP، کارهای CLI/رسانه‌ای Gateway و اجراهای cron را پوشش می‌دهند. دامنهٔ آن به درخواست‌کنندهٔ فعلی محدود است؛ یک فرزند فقط می‌تواند فرزندان تحت کنترل خودش را ببیند.

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

برای توقف یک وظیفه، از action: "cancel" همراه با taskId بازگردانده‌شده توسط action: "list" استفاده کنید. لغو به درخت نشست کنترل‌شده محدود است؛ یک زیرعامل برگ نمی‌تواند کاری را که متعلق به نشست دیگری است لغو کند.

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

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

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

یک کانال زمانی از نشست‌های پایدار زیرعامل متصل به رشته (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 هدف‌هایی را که بدون محیط ایزوله اجرا می‌شوند رد می‌کند.

کشف

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

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

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

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

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

خط‌مشی ابزار بر اساس عمق

• فرزند هنگام ایجاد، خط‌مشی مؤثر فرستندهٔ درخواست‌کننده را ثبت می‌کند. اجراهای فرزندِ بدون فرستنده و ازسرگیری‌های اپراتور احراز هویت‌شده، حتی اگر toolsBySender بعداً تغییر کند، آن تصویر لحظه‌ای را حفظ می‌کنند؛ محدودیت‌های سراسری، عامل، ارائه‌دهنده، sandbox و عامل فرعی همچنان اعمال می‌شوند. در عوض، یک نوبت کانال خارجی جدید که فرزند را هدف می‌گیرد، خط‌مشی کنونی فرستنده را دوباره محاسبه می‌کند.
• نقش و دامنهٔ کنترل هنگام ایجاد در فرادادهٔ نشست نوشته می‌شوند. این کار مانع می‌شود کلیدهای نشست تخت یا بازیابی‌شده به‌طور تصادفی دوباره امتیازهای هماهنگ‌کننده را به دست آورند.
• عمق 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 در صورت دسترس‌بودن به درخواست‌کنندهٔ آن نشست بازمی‌گردد.

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

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

زمینهٔ اعلان

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

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

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

وقتی فقط یک عامل باید به خودکارسازی مرورگر دسترسی داشته باشد، از agents.entries.*.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
• ارسال عامل
• وظایف پس‌زمینه
• ابزارهای سندباکس چندعاملی