Субагенти

Субагенти — це фонові запуски агентів, створені з наявного запуску агента. Кожен із них працює у власному сеансі (agent:<agentId>:subagent:<uuid>) і після завершення повідомляє свій результат назад у канал чату запитувача. Кожен запуск субагента відстежується як фонове завдання.

Цілі:

• Розпаралелювати дослідження, тривалі завдання та повільну роботу з інструментами, не блокуючи основний запуск.
• За замовчуванням ізолювати субагентів (окремі сеанси, необов’язкова ізоляція в пісочниці).
• Ускладнити неналежне використання набору інструментів: за замовчуванням субагенти не отримують інструментів для роботи із сеансами чи повідомленнями.
• Підтримувати налаштовувану глибину вкладеності для шаблонів оркестратора.

Команда з косою рискою

/subagents перевіряє запуски субагентів для поточного сеансу:

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

/subagents info показує метадані запуску (стан, часові позначки, ідентифікатор сеансу, шлях до транскрипту, очищення). /subagents log виводить останні репліки чату для запуску; додайте токен tools, щоб включити повідомлення викликів інструментів і їхніх результатів (за замовчуванням пропущені). Використовуйте sessions_history для обмеженого, відфільтрованого з міркувань безпеки перегляду зсередини ходу агента або перегляньте шлях до транскрипту на диску, щоб отримати необроблений повний транскрипт.

У Control UI батьківські сеанси з нещодавніми дочірніми запусками мають розгортний рядок на бічній панелі. Вкладені рядки показують стан і тривалість роботи дочірнього агента, а вибір одного з них відкриває чат цього дочірнього агента зі збереженням батьківської ієрархії.

Керування прив’язкою до гілки

Ці команди працюють у каналах із постійними прив’язками до гілок. Див. Канали з підтримкою гілок нижче.

/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 відхиляє цілі, які виконувалися б без ізоляції.

Виявлення

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

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

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

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

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

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

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

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

• Час виконання (наприклад, 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: ["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
• Надсилання агентом
• Фонові завдання
• Інструменти пісочниці для кількох агентів