Субагенти

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

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

Примітка щодо вартості: кожен субагент типово має власний контекст і використання токенів. Для важких або повторюваних задач задайте дешевшу модель для субагентів і залиште основного агента на моделі вищої якості. Налаштовуйте через agents.defaults.subagents.model або перевизначення для окремого агента. Коли дочірньому агенту справді потрібен поточний транскрипт запитувача, агент може запросити context: "fork" для цього одного породження. Сеанси субагентів, прив’язані до потоку, типово використовують context: "fork", бо вони відгалужують поточну розмову в подальший потік.

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

Елементи керування прив’язкою до потоку

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

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

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

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

Неблокувальне завершення на основі push

Команда породження неблокувальна; вона одразу повертає ідентифікатор запуску.
Після завершення субагент оголошує повідомлення з підсумком/результатом назад у канал чату запитувача.
Ходи агента, яким потрібні результати дочірніх агентів, мають викликати sessions_yield після породження потрібної роботи. Це завершує поточний хід і дає подіям завершення надійти як наступному повідомленню, видимому моделі.
Завершення працює на основі push. Після породження не опитуйте /subagents list, sessions_list або sessions_history у циклі лише для очікування завершення; перевіряйте статус лише на вимогу для налагодження або втручання.
Вивід дочірнього агента — це звіт/докази для синтезу агентом-запитувачем. Це не текст інструкцій, написаний користувачем, і він не може перевизначати політики system, developer або user.
Після завершення OpenClaw за принципом найкращого зусилля закриває відстежувані вкладки браузера/процеси, відкриті цим сеансом субагента, перш ніж потік очищення оголошення продовжиться.

Стійкість доставки ручного породження

OpenClaw передає завершення назад у сеанс запитувача через хід agent зі стабільним ключем ідемпотентності.
Якщо запуск запитувача ще активний, OpenClaw спершу намагається розбудити/спрямувати цей запуск замість запуску другого видимого шляху відповіді.
Якщо передача завершення агенту-запитувачу не вдається або не створює видимого виводу, OpenClaw вважає доставку невдалою і повертається до маршрутизації через чергу/повторної спроби. Він не надсилає необроблений результат дочірнього агента безпосередньо в зовнішній чат.
Якщо пряму передачу не можна використати, він повертається до маршрутизації через чергу.
Якщо маршрутизація через чергу все ще недоступна, оголошення повторюється з короткою експоненційною затримкою перед остаточною відмовою.
Доставка завершення зберігає вирішений маршрут запитувача: маршрути завершення, прив’язані до потоку або розмови, мають пріоритет, коли доступні; якщо джерело завершення надає лише канал, OpenClaw заповнює відсутню ціль/обліковий запис із вирішеного маршруту сеансу запитувача (lastChannel / lastTo / lastAccountId), щоб пряма доставка все одно працювала.

Метадані передачі завершення

Передача завершення до сеансу запитувача — це згенерований runtime внутрішній контекст (не текст, написаний користувачем) і містить:

Result — найновіший видимий текст відповіді assistant, інакше очищений найновіший текст tool/toolResult. Термінально невдалі запуски не використовують повторно захоплений текст відповіді.
Status — completed successfully / failed / timed out / unknown.
Компактну статистику runtime/токенів.
Інструкцію доставки, яка каже агенту-запитувачу переписати в нормальному голосі асистента (а не пересилати необроблені внутрішні метадані).

Режими та ACP runtime

--model і --thinking перевизначають типові значення для цього конкретного запуску.
Використовуйте info/log, щоб переглянути подробиці та вивід після завершення.
/subagents spawn — це одноразовий режим (mode: "run"). Для постійних сеансів, прив’язаних до потоку, використовуйте sessions_spawn з thread: true і mode: "session".
Для сеансів ACP harness (Claude Code, Gemini CLI, OpenCode або явний Codex ACP/acpx) використовуйте sessions_spawn з runtime: "acp", коли інструмент оголошує цей runtime. Див. Модель доставки ACP під час налагодження завершень або циклів агент-агент. Коли Plugin codex увімкнено, керування чатом/потоком Codex має надавати перевагу /codex ... перед ACP, якщо користувач явно не просить ACP/acpx.
OpenClaw приховує runtime: "acp", доки ACP не ввімкнено, запитувач не перебуває в пісочниці, і завантажено backend Plugin, такий як acpx. runtime: "acp" очікує зовнішній ідентифікатор ACP harness або запис agents.list[] з runtime.type="acp"; використовуйте типовий runtime субагента для звичайних агентів конфігурації OpenClaw з agents_list.

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

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

Режим	Коли його використовувати	Поведінка
`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 все одно має пріоритет.
Thinking: успадковує викликача, якщо ви не задасте agents.defaults.subagents.thinking (або agents.list[].subagents.thinking для окремого агента); явне sessions_spawn.thinking все одно має пріоритет.
Таймаут запуску: якщо sessions_spawn.runTimeoutSeconds пропущено, OpenClaw використовує agents.defaults.subagents.runTimeoutSeconds, коли його задано; інакше повертається до 0 (без таймауту).

Режим запиту делегування

agents.defaults.subagents.delegationMode керує лише підказками в запиті; він не змінює політику інструментів і не примушує делегування.

suggest (типово): залишити стандартну підказку використовувати субагенти для більшої або повільнішої роботи.
prefer: сказати основному агенту залишатися responsive і делегувати все складніше за пряму відповідь через sessions_spawn.

Перевизначення для окремого агента використовують agents.list[].subagents.delegationMode.

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

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

task

string

обов'язково

Опис завдання для під-агента.

taskName

string

Необов’язковий стабільний ідентифікатор для подальшого націлювання через subagents. Має відповідати [a-z][a-z0-9_]{0,63} і не може бути зарезервованими цілями, як-от last або all. Надавайте йому перевагу, коли координатору може знадобитися спрямувати, зупинити або ідентифікувати конкретний дочірній процес після створення кількох дочірніх процесів.

label

string

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

agentId

string

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

runtime

"subagent" | "acp"

за замовчуванням:"subagent"

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

resumeSessionId

string

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

streamTo

"parent"

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

model

string

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

thinking

string

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

runTimeoutSeconds

number

За замовчуванням використовує agents.defaults.subagents.runTimeoutSeconds, якщо задано, інакше 0. Якщо задано, запуск під-агента переривається через N секунд.

thread

boolean

за замовчуванням:"false"

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

mode

"run" | "session"

за замовчуванням:"run"

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

cleanup

"delete" | "keep"

за замовчуванням:"keep"

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

sandbox

"inherit" | "require"

за замовчуванням:"inherit"

require відхиляє створення, якщо цільове дочірнє середовище виконання не ізольоване.

context

"isolated" | "fork"

за замовчуванням:"isolated"

fork відгалужує поточний транскрипт запитувача в дочірній сеанс. Лише нативні під-агенти. Створення з прив’язкою до гілки за замовчуванням використовує fork; створення без гілки за замовчуванням використовує isolated.

sessions_spawn не приймає параметри доставки в канал (target, channel, to, threadId, replyTo, transport). Для доставки використовуйте message/sessions_send зі створеного запуску.

Назви завдань і націлювання

taskName — це ідентифікатор для оркестрації, видимий моделі, а не ключ сеансу. Використовуйте його для стабільних імен дочірніх процесів, як-от review_subagents, linux_validation або docs_update, коли координатору може знадобитися пізніше спрямувати або зупинити цей дочірній процес. Розв’язання цілі приймає точні збіги taskName і однозначні префікси. Зіставлення обмежене тим самим активним/нещодавнім вікном цілей, яке використовується нумерованими цілями /subagents, тому застарілий завершений дочірній процес не робить повторно використаний ідентифікатор неоднозначним. Якщо два активні або нещодавні дочірні процеси мають однаковий taskName, ціль є неоднозначною; натомість використовуйте індекс списку, ключ сеансу або id запуску. Зарезервовані цілі last і all не є допустимими значеннями taskName, оскільки вони вже мають керувальні значення.

Інструмент: `sessions_yield`

Завершує поточний хід моделі й очікує, доки події середовища виконання, передусім події завершення під-агентів, надійдуть як наступне повідомлення. Використовуйте його після створення потрібної дочірньої роботи, коли запитувач не може надати остаточну відповідь, доки ці завершення не надійдуть. sessions_yield — це примітив очікування. Не замінюйте його циклами опитування через subagents, sessions_list, sessions_history, shell sleep або опитування процесів лише для виявлення завершення дочірнього процесу. Використовуйте sessions_yield лише тоді, коли ефективний список інструментів сеансу містить його. Деякі мінімальні або кастомні профілі інструментів можуть надавати sessions_spawn і subagents без sessions_yield; у такому разі не вигадуйте цикл опитування лише для очікування завершення. Коли існують активні дочірні процеси, OpenClaw вставляє компактний, згенерований середовищем виконання блок промпта Active Subagents у звичайні ходи, щоб запитувач міг бачити поточні дочірні сеанси, id запусків, статуси, мітки, завдання та псевдоніми taskName без опитування. Поля завдання й мітки в цьому блоці взято в лапки як дані, а не інструкції, оскільки вони можуть походити з наданих користувачем/моделлю аргументів створення.

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

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

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

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

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

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.

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

Створення

sessions_spawn з thread: true (і необов’язково mode: "session").

Прив'язка

OpenClaw створює або прив’язує гілку до цієї цілі сеансу в активному каналі.

Маршрутизація подальших повідомлень

Відповіді та подальші повідомлення в цій гілці маршрутизуються до прив’язаного сеансу.

Перевірка тайм-аутів

Використовуйте /session idle, щоб переглянути/оновити автоматичне зняття фокуса через бездіяльність, і /session max-age, щоб керувати жорсткою межею.

Від'єднання

Використовуйте /unfocus, щоб від’єднати вручну.

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

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

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

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

Див. Довідник конфігурації і Слеш-команди для актуальних деталей адаптера.

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

agents.list[].subagents.allowAgents

string[]

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

agents.defaults.subagents.allowAgents

string[]

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

agents.defaults.subagents.requireAgentId

boolean

за замовчуванням:"false"

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

agents.defaults.subagents.announceTimeoutMs

number

за замовчуванням:"120000"

Тайм-аут для кожного виклику спроб доставки оголошення agent через gateway. Значення є додатними цілими мілісекундами та обмежуються платформно безпечним максимумом таймера. Тимчасові повторні спроби можуть зробити загальне очікування оголошення довшим за один налаштований тайм-аут.

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

Виявлення

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

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

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

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

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

{
  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)
        announceTimeoutMs: 120000, // per-call gateway announce timeout
      },
    },
  },
}

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

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

Ланцюг оголошень

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

Робочий процес глибини 2 завершується → оголошує своєму батьківському процесу (оркестратору глибини 1).
Оркестратор глибини 1 отримує оголошення, синтезує результати, завершується → оголошує основному процесу.
Основний агент отримує оголошення та доставляє його користувачу.

Кожен рівень бачить лише оголошення від своїх безпосередніх дочірніх процесів.

Операційні настанови: запускайте дочірню роботу один раз і чекайте на події завершення, замість того щоб будувати цикли опитування навколо sessions_list, sessions_history, /subagents list або команд exec sleep. sessions_list і /subagents list утримують зв’язки дочірніх сесій зосередженими на активній роботі — активні дочірні сесії залишаються приєднаними, завершені дочірні сесії лишаються видимими протягом короткого недавнього вікна, а застарілі посилання лише зі сховища ігноруються після завершення їхнього вікна актуальності. Це запобігає тому, щоб старі метадані spawnedBy / parentSessionKey відновлювали примарні дочірні сесії після перезапуску. Якщо подія завершення дочірньої сесії надходить після того, як ви вже надіслали фінальну відповідь, правильна подальша дія — точний тихий токен NO_REPLY / no_reply.

Політика інструментів за глибиною

Роль і область керування записуються в метадані сесії під час створення. Це не дає плоским або відновленим ключам сесій випадково знову отримати права оркестратора.
Глибина 1 (оркестратор, коли maxSpawnDepth >= 2): отримує sessions_spawn, subagents, sessions_list, sessions_history, щоб керувати своїми дочірніми сесіями. Інші інструменти сесій/системи залишаються забороненими.
Глибина 1 (кінцевий виконавець, коли maxSpawnDepth == 1): без інструментів сесій (поточна поведінка за замовчуванням).
Глибина 2 (кінцевий worker): без інструментів сесій — sessions_spawn завжди заборонений на глибині 2. Не може створювати подальші дочірні сесії.

Ліміт створення на агента

Кожна агентська сесія (на будь-якій глибині) може мати щонайбільше maxChildrenPerAgent (за замовчуванням 5) активних дочірніх сесій одночасно. Це запобігає неконтрольованому розгалуженню від одного оркестратора.

Каскадна зупинка

Зупинка оркестратора глибини 1 автоматично зупиняє всі його дочірні сесії глибини 2:

/stop в основному чаті зупиняє всі агенти глибини 1 і каскадно зупиняє їхні дочірні сесії глибини 2.
/subagents kill <id> зупиняє конкретного підагентa і каскадно зупиняє його дочірні сесії.
/subagents kill all зупиняє всі підагенти для запитувача і запускає каскадну зупинку.

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

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

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

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

Оголошення

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

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

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

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

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

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

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

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

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

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

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

Час виконання (наприклад, 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].
Перегляд сирого транскрипту на диску є резервним варіантом, коли потрібен повний побайтово точний транскрипт.

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

Підагенти спочатку використовують той самий профіль і pipeline політики інструментів, що й батьківський або цільовий агент. Після цього 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 — це фінальний фільтр allow-only. Він може звузити вже визначений набір інструментів, але не може додати назад інструмент, вилучений tools.profile. Наприклад, tools.profile: "coding" містить web_search/web_fetch, але не інструмент browser. Щоб дозволити підагентам із coding-профілем використовувати автоматизацію браузера, додайте browser на етапі профілю:

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

Використовуйте agents.list[].tools.alsoAllow: ["browser"] для кожного агента, коли автоматизацію браузера має отримати лише один агент.

Паралельність

Підагенти використовують окрему lane черги в процесі:

Назва lane: subagent
Паралельність: agents.defaults.subagents.maxConcurrent (за замовчуванням 8)

Живучість і відновлення

OpenClaw не трактує відсутність endedAt як постійний доказ того, що підагент досі активний. Незавершені запуски, старші за вікно застарілого запуску, перестають рахуватися як активні/очікувані в /subagents list, підсумках статусу, gating завершення нащадків і перевірках паралельності для кожної сесії. Після перезапуску Gateway застарілі незавершені відновлені запуски відсікаються, якщо їхня дочірня сесія не позначена abortedLastRun: true. Ці дочірні сесії, перервані перезапуском, залишаються відновлюваними через потік відновлення осиротілих підагентів, який надсилає синтетичне повідомлення відновлення перед очищенням маркера переривання. Автоматичне відновлення після перезапуску обмежується для кожної дочірньої сесії. Якщо ту саму дочірню сесію підагента повторно приймають для відновлення осиротілих сесій у межах швидкого вікна повторного зависання, OpenClaw зберігає recovery tombstone для цієї сесії й перестає автоматично відновлювати її під час наступних перезапусків. Запустіть openclaw tasks maintenance --apply, щоб узгодити запис завдання, або openclaw doctor --fix, щоб очистити застарілі прапорці aborted recovery на tombstoned сесіях.

Якщо створення підагента завершується помилкою Gateway PAIRING_REQUIRED / scope-upgrade, перевірте викликача RPC перед редагуванням стану pairing. Внутрішня координація sessions_spawn має підключатися як client.id: "gateway-client" з client.mode: "backend" через пряму автентифікацію local loopback shared-token/password; цей шлях не залежить від базової області paired-device CLI. Віддалені викликачі, явні deviceIdentity, явні шляхи device-token і клієнти browser/node все ще потребують звичайного схвалення пристрою для scope upgrades.

Зупинка

Надсилання /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 (без MEMORY.md, HEARTBEAT.md або BOOTSTRAP.md).
Максимальна глибина вкладення — 5 (діапазон maxSpawnDepth: 1–5). Для більшості випадків використання рекомендовано глибину 2.
maxChildrenPerAgent обмежує кількість активних дочірніх сесій на сесію (за замовчуванням 5, діапазон 1–20).

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Documentation Index

​Slash-команда

​Елементи керування прив’язкою до потоку

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

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

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

​Режим запиту делегування

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

​Назви завдань і націлювання

​Інструмент: sessions_yield

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

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

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

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

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

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

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

​Виявлення

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

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

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

​Ланцюг оголошень

​Політика інструментів за глибиною

​Ліміт створення на агента

​Каскадна зупинка

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

​Оголошення

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

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

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

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

​Перевизначення через конфігурацію

​Паралельність

​Живучість і відновлення

​Зупинка

​Обмеження

​Пов’язане

Slash-команда

Елементи керування прив’язкою до потоку

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

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

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

Режим запиту делегування

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

Назви завдань і націлювання

Інструмент: `sessions_yield`

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

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

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

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

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

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

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

Виявлення

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

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

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

Ланцюг оголошень

Політика інструментів за глибиною

Ліміт створення на агента

Каскадна зупинка

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

Оголошення

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

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

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

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

Перевизначення через конфігурацію

Паралельність

Живучість і відновлення

Зупинка

Обмеження

Пов’язане