Субагенти

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

Про модель безпеки делегування див. Межі багатоагентної взаємодії та субагентів. Субагенти корисні як одиниці ізоляції та робочого процесу, але вони не є ворожою багатоорендною межею авторизації всередині одного спільного Gateway.

Основні цілі:

• Паралелізувати роботу типу "дослідження / довге завдання / повільний інструмент", не блокуючи основний запуск.
• Типово ізолювати субагентів (розділення сеансів + необов'язкова пісочниця).
• Зробити поверхню інструментів складною для неправильного використання: субагенти типово не отримують інструменти сеансу.
• Підтримувати налаштовувану глибину вкладеності для оркестраторних шаблонів.

# Slash-команда

Використовуйте /subagents, щоб переглядати або керувати запусками субагентів для поточного сеансу:

/subagents list
/subagents kill <id|#|all>
/subagents log <id|#> [limit] [tools]
/subagents info <id|#>
/subagents send <id|#> <message>
/subagents steer <id|#> <message>
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]

Використовуйте верхньорівневу /steer <message>, щоб спрямовувати активний запуск поточного сеансу запитувача. Використовуйте /subagents steer <id|#> <message>, коли ціль — дочірній запуск.

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

# Елементи керування прив'язкою до гілки

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

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

# Поведінка породження

/subagents spawn запускає фонового субагента як користувацьку команду (не як внутрішню ретрансляцію) і надсилає одне фінальне оновлення про завершення назад у чат запитувача, коли запуск завершується.

# Режими контексту

Нативні субагенти запускаються ізольовано, якщо викликач явно не просить відгалузити поточний транскрипт.

Режим	Коли використовувати	Поведінка
isolated	Нове дослідження, незалежна реалізація, робота з повільними інструментами або будь-що, що можна коротко описати в тексті завдання	Створює чистий дочірній транскрипт. Це типове значення, яке зменшує використання токенів.
fork	Робота, що залежить від поточної розмови, попередніх результатів інструментів або нюансованих інструкцій, уже наявних у транскрипті запитувача	Відгалужує транскрипт запитувача в дочірній сеанс перед стартом дочірнього агента.

Використовуйте fork економно. Він призначений для делегування, чутливого до контексту, а не як заміна написанню чіткого промпту завдання.

# Інструмент: sessions_spawn

Запускає субагента з deliver: false у глобальній лінії subagent, потім виконує крок оголошення і публікує відповідь оголошення в канал чату запитувача.

Доступність залежить від ефективної політики інструментів викликача. Профілі coding і full типово надають sessions_spawn. Профіль messaging не надає; додайте tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"] або використайте tools.profile: "coding" для агентів, які мають делегувати роботу. Політики дозволу/заборони для каналу/групи, провайдера, пісочниці та окремого агента можуть усе ще прибрати інструмент після етапу профілю. Використовуйте /tools з того самого сеансу, щоб підтвердити ефективний список інструментів.

Типові значення:

• Модель: успадковує викликача, якщо ви не задасте agents.defaults.subagents.model (або agents.list[].subagents.model для окремого агента); явне sessions_spawn.model все одно має пріоритет.
• Міркування: успадковує викликача, якщо ви не задасте agents.defaults.subagents.thinking (або agents.list[].subagents.thinking для окремого агента); явне sessions_spawn.thinking все одно має пріоритет.
• Тайм-аут запуску: якщо sessions_spawn.runTimeoutSeconds пропущено, OpenClaw використовує agents.defaults.subagents.runTimeoutSeconds, коли його задано; інакше повертається до 0 (без тайм-ауту).

# Параметри інструмента

taskstringrequired

Опис завдання для субагента.

labelstring

Необов'язкова зручна для людини мітка.

agentIdstring

Породити під іншим id агента, коли це дозволено subagents.allowAgents.

runtime"subagent" | "acp"

acp призначено лише для зовнішніх ACP harness (claude, droid, gemini, opencode або явно запитаного Codex ACP/acpx) і для записів agents.list[], у яких runtime.type дорівнює acp.

resumeSessionIdstring

Лише для ACP. Відновлює наявний сеанс ACP harness, коли runtime: "acp"; ігнорується для нативних породжень субагентів.

streamTo"parent"

Лише для ACP. Потоково передає вивід запуску ACP до батьківського сеансу, коли runtime: "acp"; пропустіть для нативних породжень субагентів.

modelstring

Перевизначає модель субагента. Недійсні значення пропускаються, і субагент запускається на типовій моделі з попередженням у результаті інструмента.

thinkingstring

Перевизначає рівень міркування для запуску субагента.

runTimeoutSecondsnumber

Типово дорівнює agents.defaults.subagents.runTimeoutSeconds, коли задано, інакше 0. Коли задано, запуск субагента переривається після N секунд.

threadboolean

Коли true, запитує прив'язку до гілки каналу для цього сеансу субагента.

mode"run" | "session"

Якщо thread: true і mode пропущено, типовим стає session. mode: "session" вимагає thread: true.

cleanup"delete" | "keep"

"delete" архівує одразу після оголошення (транскрипт усе одно зберігається через перейменування).

sandbox"inherit" | "require"

require відхиляє породження, якщо цільове дочірнє середовище виконання не перебуває в пісочниці.

context"isolated" | "fork"

fork відгалужує поточний транскрипт запитувача в дочірній сеанс. Лише нативні субагенти. Породження, прив'язані до гілки, типово використовують fork; породження без гілки типово використовують isolated.

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

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

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

Discord наразі є єдиним підтримуваним каналом. Він підтримує постійні сеанси субагентів, прив'язані до гілки (sessions_spawn з thread: true), ручні елементи керування гілками (/focus, /unfocus, /agents, /session idle, /session max-age) і ключі адаптера channels.discord.threadBindings.enabled, channels.discord.threadBindings.idleHours, channels.discord.threadBindings.maxAgeHours та channels.discord.threadBindings.spawnSessions.

# Швидкий потік

# Ручні елементи керування

Команда	Ефект
/focus <target>	Прив’язати поточний потік (або створити його) до цілі під-агента/сеансу
/unfocus	Видалити прив’язку для поточного прив’язаного потоку
/agents	Показати активні запуски та стан прив’язки (thread:<id> або unbound)
/session idle	Переглянути/оновити автоматичне зняття фокуса через простоювання (лише сфокусовані прив’язані потоки)
/session max-age	Переглянути/оновити жорстке обмеження (лише сфокусовані прив’язані потоки)

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

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

Див. Довідник із конфігурації і Slash-команди, щоб отримати актуальні деталі адаптера.

# Список дозволених

agents.list[].subagents.allowAgentsstring[]

Список ідентифікаторів агентів, на які можна націлюватися через явний agentId (["*"] дозволяє будь-який). За замовчуванням: лише агент-запитувач. Якщо ви задаєте список і все ще хочете, щоб запитувач міг створювати себе з agentId, додайте ідентифікатор запитувача до списку.

agents.defaults.subagents.allowAgentsstring[]

Список дозволених цільових агентів за замовчуванням, який використовується, коли агент-запитувач не задає власний subagents.allowAgents.

agents.defaults.subagents.requireAgentIdboolean

Блокувати виклики sessions_spawn, які опускають agentId (примушує явний вибір профілю). Перевизначення для окремого агента: agents.list[].subagents.requireAgentId.

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

# Виявлення

Використовуйте agents_list, щоб побачити, які ідентифікатори агентів наразі дозволені для sessions_spawn. Відповідь містить ефективну модель кожного переліченого агента та вбудовані метадані середовища виконання, щоб виклики могли відрізняти PI, сервер застосунку Codex та інші налаштовані нативні середовища виконання.

# Автоархівація

• Сеанси під-агентів автоматично архівуються після agents.defaults.subagents.archiveAfterMinutes (за замовчуванням 60).
• Архівування використовує sessions.delete і перейменовує транскрипт на *.deleted.<timestamp> (у тій самій папці).
• cleanup: "delete" архівує одразу після оголошення (транскрипт усе одно зберігається через перейменування).
• Автоархівація виконується за принципом найкращих зусиль; очікувані таймери втрачаються, якщо gateway перезапускається.
• runTimeoutSeconds не виконує автоархівацію; він лише зупиняє запуск. Сеанс залишається до автоархівації.
• Автоархівація однаково застосовується до сеансів глибини 1 і глибини 2.
• Очищення браузера відокремлене від архівного очищення: відстежувані вкладки/процеси браузера закриваються за принципом найкращих зусиль після завершення запуску, навіть якщо запис транскрипту/сеансу збережено.

# Вкладені під-агенти

За замовчуванням під-агенти не можуть створювати власних під-агентів (maxSpawnDepth: 1). Встановіть maxSpawnDepth: 2, щоб увімкнути один рівень вкладеності — шаблон оркестратора: головний → під-агент-оркестратор → робочі під-під-агенти.

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)
        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)
        maxConcurrent: 8, // global concurrency lane cap (default: 8)
        runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout)
      },
    },
  },
}

# Рівні глибини

Глибина	Форма ключа сеансу	Роль	Може створювати?
0	agent:<id>:main	Головний агент	Завжди
1	agent:<id>:subagent:<uuid>	Під-агент (оркестратор, коли дозволено глибину 2)	Лише якщо maxSpawnDepth >= 2
2	agent:<id>:subagent:<uuid>:subagent:<uuid>	Під-під-агент (кінцевий виконавець)	Ніколи

# Ланцюжок оголошень

Результати передаються назад угору ланцюжком:

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.
• /subagents kill <id> зупиняє конкретного під-агента та каскадно зупиняє його дочірні елементи.
• /subagents kill all зупиняє всіх під-агентів для запитувача та виконує каскадну зупинку.

# Автентифікація

Автентифікація під-агента визначається за ідентифікатором агента, а не за типом сеансу:

• Ключ сеансу під-агента має вигляд agent:<agentId>:subagent:<uuid>.
• Сховище автентифікації завантажується з agentDir цього агента.
• Профілі автентифікації головного агента об’єднуються як резервний варіант; профілі агента перевизначають головні профілі у разі конфліктів.

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

# Оголошення

Під-агенти звітують назад через крок оголошення:

• Крок оголошення виконується всередині сеансу під-агента (не в сеансі запитувача).
• Якщо під-агент відповідає точно ANNOUNCE_SKIP, нічого не публікується.
• Якщо останній текст асистента є точним тихим токеном NO_REPLY / no_reply, вивід оголошення пригнічується, навіть якщо раніше існував видимий прогрес.

Доставка залежить від глибини запитувача:

• Сеанси запитувача верхнього рівня використовують подальший виклик agent із зовнішньою доставкою (deliver=true).
• Вкладені сеанси під-агента-запитувача отримують внутрішнє подальше впорскування (deliver=false), щоб оркестратор міг синтезувати дочірні результати в сеансі.
• Якщо вкладений сеанс під-агента-запитувача зник, OpenClaw повертається до запитувача цього сеансу, коли він доступний.

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

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

# Контекст оголошення

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

Поле	Джерело
Джерело	subagent або cron
Ідентифікатори сеансу	Ключ/ідентифікатор дочірнього сеансу
Тип	Тип оголошення + мітка завдання
Статус	Виводиться з результату середовища виконання (success, error, timeout або unknown) — не визначається з тексту моделі
Вміст результату	Останній видимий текст асистента, інакше очищений останній текст інструмента/toolResult
Подальша дія	Інструкція, що описує, коли відповідати, а коли залишатися тихо

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

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

Корисні навантаження оголошень містять рядок статистики в кінці (навіть коли він перенесений):

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

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

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

sessions_history є безпечнішим шляхом оркестрації:

• Відтворення асистента спершу нормалізується: теги мислення вилучаються; каркаси <relevant-memories> / <relevant_memories> вилучаються; XML-блоки корисного навантаження викликів інструментів у plain-text (<tool_call>, <function_call>, <tool_calls>, <function_calls>) вилучаються, включно з обрізаними корисними навантаженнями, які ніколи не закрилися коректно; понижені каркаси викликів/результатів інструментів і маркери історичного контексту вилучаються; витоки керівних токенів моделі (<|assistant|>, інші ASCII <|...|>, повноширинні <｜...｜>) вилучаються; некоректний XML викликів інструментів MiniMax вилучається.
• Текст, схожий на облікові дані/токени, редагується.
• Довгі блоки можуть обрізатися.
• Дуже великі історії можуть відкидати старіші рядки або замінювати надмірно великий рядок на [sessions_history omitted: message too large].
• Перегляд сирого транскрипту на диску є резервним варіантом, коли потрібен повний побайтово точний транскрипт.

# Політика інструментів

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

Без обмежувального tools.profile субагенти отримують усі інструменти, крім інструментів сеансу та системних інструментів:

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

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. Щоб дозволити субагентам із профілем coding використовувати автоматизацію браузера, додайте 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 зберігає tombstone відновлення в цьому сеансі й припиняє автоматично відновлювати його під час наступних перезапусків. Запустіть openclaw tasks maintenance --apply, щоб узгодити запис завдання, або openclaw doctor --fix, щоб очистити застарілі прапорці перерваного відновлення в сеансах із tombstone.

# Зупинка

• Надсилання /stop у чаті запитувача перериває сеанс запитувача й зупиняє всі активні запуски субагентів, створені з нього, каскадно поширюючись на вкладених дочірніх агентів.
• /subagents kill <id> зупиняє конкретного субагента й каскадно поширюється на його дочірні агенти.

# Обмеження

• Оголошення субагента виконується за принципом best-effort. Якщо Gateway перезапускається, незавершена робота "announce back" втрачається.
• Субагенти все ще спільно використовують ресурси того самого процесу Gateway; розглядайте maxConcurrent як запобіжний клапан.
• sessions_spawn завжди неблокувальний: він негайно повертає { status: "accepted", runId, childSessionKey }.
• Контекст субагента інʼєктує лише AGENTS.md + TOOLS.md (без SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md або BOOTSTRAP.md).
• Максимальна глибина вкладення становить 5 (діапазон maxSpawnDepth: 1–5). Глибина 2 рекомендована для більшості сценаріїв використання.
• maxChildrenPerAgent обмежує кількість активних дочірніх агентів на сеанс (типово 5, діапазон 1–20).

# Пов’язане

• агенти ACP
• Надсилання агенту
• Фонові завдання
• Інструменти пісочниці для кількох агентів