Субагенти

Підагентами називаються фонові запуски агентів, створені з наявного запуску агента. Кожен із них виконується у власному сеансі (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 додає компактний, згенерований середовищем виконання блок підказки Активні підлеглі агенти до звичайних ходів, щоб запитувач міг бачити поточні дочірні сеанси, ідентифікатори запусків, стани, мітки, завдання та псевдоніми taskName без опитування. Поля завдання та мітки в цьому блоці взято в лапки як дані, а не інструкції, оскільки вони можуть походити з наданих користувачем або моделлю аргументів запуску.

Інструмент: subagents

Перераховує запуски підлеглих агентів, що належать сеансу запитувача. Область дії обмежена поточним запитувачем; дочірній агент може бачити лише власних керованих дочірніх агентів.

Використовуйте subagents для перевірки стану на вимогу та налагодження. Використовуйте sessions_yield для очікування подій завершення.

Сеанси, прив’язані до гілок

Коли для каналу ввімкнено прив’язування до гілок, підлеглий агент може залишатися прив’язаним до гілки, щоб подальші повідомлення користувача в цій гілці й надалі спрямовувалися до того самого сеансу підлеглого агента.

Канали з підтримкою гілок

Канал підтримує постійні сеанси підлеглих агентів, прив’язані до гілок (sessions_spawn із thread: true), якщо він реєструє адаптер прив’язування розмови. Вбудовані канали з такою підтримкою: Discord, iMessage, Matrix і Telegram. Discord і Matrix за замовчуванням створюють дочірню гілку; Telegram та iMessage за замовчуванням прив’язують поточну розмову. Використовуйте ключі конфігурації threadBindings для кожного каналу, щоб керувати ввімкненням, часом очікування та spawnSessions.

Швидкий процес

Ручне керування

Перемикачі конфігурації

• Глобальні стандартні значення: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Ключі перевизначення для каналу й автоматичного прив’язування під час запуску залежать від адаптера. Див. розділ Канали з підтримкою гілок вище.

Актуальні відомості про адаптери див. у довіднику з конфігурації та командах із косою рискою.

Список дозволів

Якщо сеанс запитувача ізольований, sessions_spawn відхиляє цілі, які працювали б без ізоляції.

Виявлення

Використовуйте agents_list, щоб переглянути, які ідентифікатори агентів наразі дозволено для sessions_spawn. Відповідь містить ефективну модель кожного переліченого агента та вбудовані метадані середовища виконання, щоб виклики могли розрізняти 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, коли можливо, повертається до ініціатора цього сеансу.

Для сеансів ініціатора верхнього рівня пряме доставлення в режимі завершення спочатку визначає будь-який прив’язаний маршрут розмови/гілки та перевизначення перехоплювача, а потім заповнює відсутні поля каналу й цілі зі збереженого маршруту сеансу ініціатора. Завдяки цьому завершення потрапляють у правильний чат/тему, навіть коли джерело завершення визначає лише канал.

Під час формування вкладених результатів завершення агрегація завершень дочірніх агентів обмежується поточним запуском ініціатора, що запобігає потраплянню застарілих результатів дочірніх агентів із попередніх запусків у поточне сповіщення. Відповіді сповіщень зберігають маршрутизацію гілки/теми, коли вона доступна в адаптерах каналів.

Контекст сповіщення

Контекст сповіщення нормалізується до стабільного внутрішнього блоку події:

Завершені невдало запуски повідомляють про стан помилки без повторного відтворення захопленого тексту відповіді. Виведення інструменту/результату інструменту не перетворюється на текст результату дочірнього агента.

Рядок статистики

Корисне навантаження сповіщення містить наприкінці рядок статистики (навіть за наявності обгортки):

• Час виконання (наприклад, runtime 5m12s).
• Використання токенів (вхідні/вихідні/загалом).
• Орієнтовна вартість, коли налаштовано ціни моделей (models.providers.*.models[].cost).
• sessionKey, sessionId і шлях до стенограми, щоб головний агент міг отримати історію через sessions_history або перевірити файл на диску.

Внутрішні метадані призначені лише для оркестрації; відповіді для користувача слід переписувати звичайною мовою асистента.

Чому варто віддавати перевагу sessions_history

sessions_history — безпечніший шлях оркестрації для читання стенограми дочірнього агента під час ходу агента:

• Редагує текст, схожий на облікові дані/токени, навіть коли загальне редагування журналів вимкнено.
• Обрізає довгі текстові блоки (4000 символів на блок) і вилучає сигнатури мислення, корисне навантаження повторного відтворення міркувань і вбудовані дані зображень.
• Застосовує обмеження відповіді у 80 КБ; завеликі рядки замінюються на [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 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 остаточним доказом того, що субагент досі активний. Незавершені запуски, старші за вікно застарілого запуску (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
• Надсилання агенту
• Фонові завдання
• Інструменти пісочниці для кількох агентів