--- read_when: - Вам потрібна фонова або паралельна робота через агента - Ви змінюєте sessions_spawn або політику інструмента субагента - Ви реалізуєте або усуваєте неполадки сеансів субагентів, прив’язаних до потоку sidebarTitle: Sub-agents summary: Запускайте ізольовані фонові запуски агентів, які повідомляють результати назад у чат ініціатора запиту title: Субагенти x-i18n: generated_at: "2026-05-11T21:02:47Z" model: gpt-5.5 provider: openai source_hash: 02b03bdfd5cddf5618fddf0804f017400c36751095166dac18fa35fa3bfd4c6e source_path: tools/subagents.md workflow: 16 --- Субагенти — це фонові запуски агентів, породжені з наявного запуску агента. Вони працюють у власному сеансі (`agent::subagent:`) і, після завершення, **оголошують** свій результат назад у канал чату запитувача. Кожен запуск субагента відстежується як [фонова задача](/uk/automation/tasks). Основні цілі: - Паралелізувати роботу типу «дослідження / довга задача / повільний інструмент» без блокування основного запуску. - Типово ізолювати субагенти (розділення сеансів + необов’язкова пісочниця). - Зробити поверхню інструментів складною для неправильного використання: субагенти типово **не** отримують інструменти сеансу. - Підтримувати налаштовувану глибину вкладення для шаблонів оркестратора. **Примітка щодо вартості:** кожен субагент типово має власний контекст і використання токенів. Для важких або повторюваних задач задайте дешевшу модель для субагентів і залиште основного агента на моделі вищої якості. Налаштовуйте через `agents.defaults.subagents.model` або перевизначення для окремого агента. Коли дочірньому агенту справді потрібен поточний транскрипт запитувача, агент може запросити `context: "fork"` для цього одного породження. Сеанси субагентів, прив’язані до потоку, типово використовують `context: "fork"`, бо вони відгалужують поточну розмову в подальший потік. ## Slash-команда Використовуйте `/subagents`, щоб переглядати або керувати запусками субагентів для **поточного сеансу**: ```text /subagents list /subagents kill /subagents log [limit] [tools] /subagents info /subagents send /subagents steer /subagents spawn [--model ] [--thinking ] ``` Використовуйте верхньорівневу [`/steer `](/uk/tools/steer), щоб спрямувати активний запуск поточного сеансу запитувача. Використовуйте `/subagents steer `, коли ціль — дочірній запуск. `/subagents info` показує метадані запуску (статус, часові позначки, ідентифікатор сеансу, шлях до транскрипту, очищення). Використовуйте `sessions_history` для обмеженого, відфільтрованого з міркувань безпеки подання пригадування; перевіряйте шлях до транскрипту на диску, коли вам потрібен повний необроблений транскрипт. ### Елементи керування прив’язкою до потоку Ці команди працюють у каналах, що підтримують постійні прив’язки до потоків. Див. [Канали з підтримкою потоків](#thread-supporting-channels) нижче. ```text /focus /unfocus /agents /session idle /session max-age ``` ### Поведінка породження `/subagents spawn` запускає фонового субагента як команду користувача (а не внутрішню ретрансляцію) і надсилає одне фінальне оновлення про завершення назад у чат запитувача, коли запуск завершується. - Команда породження неблокувальна; вона одразу повертає ідентифікатор запуску. - Після завершення субагент оголошує повідомлення з підсумком/результатом назад у канал чату запитувача. - Ходи агента, яким потрібні результати дочірніх агентів, мають викликати `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/токенів. - Інструкцію доставки, яка каже агенту-запитувачу переписати в нормальному голосі асистента (а не пересилати необроблені внутрішні метадані). - `--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](/uk/tools/acp-agents#delivery-model) під час налагодження завершень або циклів агент-агент. Коли 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`. ```json5 { agents: { defaults: { subagents: { delegationMode: "prefer", maxConcurrent: 4, }, }, list: [ { id: "coordinator", subagents: { delegationMode: "prefer" }, }, ], }, } ``` ### Параметри інструмента Опис завдання для під-агента. Необов'язковий стабільний ідентифікатор для подальшого націлювання через `subagents`. Має відповідати `[a-z][a-z0-9_]{0,63}` і не може бути зарезервованими цілями, як-от `last` або `all`. Надавайте йому перевагу, коли координатору може знадобитися спрямувати, зупинити або ідентифікувати конкретний дочірній процес після створення кількох дочірніх процесів. Необов'язкова людиночитна мітка. Створює під іншим id агента, коли це дозволено `subagents.allowAgents`. `acp` призначений лише для зовнішніх ACP-обгорток (`claude`, `droid`, `gemini`, `opencode` або явно запитаного Codex ACP/acpx) і для записів `agents.list[]`, у яких `runtime.type` має значення `acp`. Лише ACP. Відновлює наявний сеанс ACP-обгортки, коли `runtime: "acp"`; ігнорується для створення нативних під-агентів. Лише ACP. Транслює вивід запуску ACP до батьківського сеансу, коли `runtime: "acp"`; не вказуйте для створення нативних під-агентів. Перевизначає модель під-агента. Недійсні значення пропускаються, і під-агент запускається на стандартній моделі з попередженням у результаті інструмента. Перевизначає рівень мислення для запуску під-агента. За замовчуванням використовує `agents.defaults.subagents.runTimeoutSeconds`, якщо задано, інакше `0`. Якщо задано, запуск під-агента переривається через N секунд. Коли `true`, запитує прив'язку гілки каналу для цього сеансу під-агента. Якщо `thread: true` і `mode` не вказано, стандартним значенням стає `session`. `mode: "session"` потребує `thread: true`. `"delete"` архівує негайно після оголошення (транскрипт усе одно зберігається через перейменування). `require` відхиляє створення, якщо цільове дочірнє середовище виконання не ізольоване. `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 ` | Прив'язати поточну гілку (або створити її) до цілі під-агента/сеансу | | `/unfocus` | Видалити прив'язку для поточної прив'язаної гілки | | `/agents` | Перелічити активні запуски та стан прив'язки (`thread:` або `unbound`) | | `/session idle` | Переглянути/оновити автоматичне зняття фокуса через бездіяльність (лише сфокусовані прив'язані гілки) | | `/session max-age` | Переглянути/оновити жорстку межу (лише сфокусовані прив'язані гілки) | ### Перемикачі конфігурації - **Глобальне значення за замовчуванням:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - **Перевизначення каналу та ключі автоматичної прив'язки під час створення** є специфічними для адаптера. Див. [Канали з підтримкою гілок](#thread-supporting-channels) вище. Див. [Довідник конфігурації](/uk/gateway/configuration-reference) і [Слеш-команди](/uk/tools/slash-commands) для актуальних деталей адаптера. ### Список дозволених Список id агентів, на які можна націлюватися через явний `agentId` (`["*"]` дозволяє будь-який). За замовчуванням: лише агент-запитувач. Якщо ви задаєте список і все ще хочете, щоб запитувач міг створювати себе з `agentId`, включіть id запитувача до списку. Стандартний список дозволених цільових агентів, який використовується, коли агент-запитувач не задає власний `subagents.allowAgents`. Блокує виклики `sessions_spawn`, які пропускають `agentId` (примушує явно вибирати профіль). Перевизначення для окремого агента: `agents.list[].subagents.requireAgentId`. Тайм-аут для кожного виклику спроб доставки оголошення `agent` через gateway. Значення є додатними цілими мілісекундами та обмежуються платформно безпечним максимумом таймера. Тимчасові повторні спроби можуть зробити загальне очікування оголошення довшим за один налаштований тайм-аут. Якщо сеанс запитувача ізольований, `sessions_spawn` відхиляє цілі, які запускалися б без ізоляції. ### Виявлення Використовуйте `agents_list`, щоб побачити, які id агентів наразі дозволені для `sessions_spawn`. Відповідь містить ефективну модель кожного переліченого агента та вбудовані метадані середовища виконання, щоб викликачі могли відрізняти PI, сервер застосунку Codex та інші налаштовані нативні середовища виконання. ### Автоархівація - Сеанси під-агентів автоматично архівуються після `agents.defaults.subagents.archiveAfterMinutes` (за замовчуванням `60`). - Архівація використовує `sessions.delete` і перейменовує транскрипт на `*.deleted.` (та сама папка). - `cleanup: "delete"` архівує негайно після оголошення (транскрипт усе одно зберігається через перейменування). - Автоархівація виконується за принципом найкращої спроби; очікувані таймери втрачаються, якщо gateway перезапускається. - `runTimeoutSeconds` **не** автоархівує; він лише зупиняє запуск. Сеанс залишається до автоархівації. - Автоархівація однаково застосовується до сеансів глибини 1 і глибини 2. - Очищення браузера відокремлене від очищення архіву: відстежувані вкладки/процеси браузера закриваються за принципом найкращої спроби після завершення запуску, навіть якщо транскрипт/запис сеансу зберігається. ## Вкладені під-агенти За замовчуванням під-агенти не можуть створювати власних під-агентів (`maxSpawnDepth: 1`). Задайте `maxSpawnDepth: 2`, щоб увімкнути один рівень вкладеності — **патерн оркестратора**: main → під-агент-оркестратор → робочі під-під-агенти. ```json5 { 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::main` | Основний агент | Завжди | | 1 | `agent::subagent:` | Під-агент (оркестратор, коли дозволено глибину 2) | Лише якщо `maxSpawnDepth >= 2` | | 2 | `agent::subagent::subagent:` | Під-під-агент (кінцевий робочий процес) | Ніколи | ### Ланцюг оголошень Результати передаються назад угору ланцюгом: 1. Робочий процес глибини 2 завершується → оголошує своєму батьківському процесу (оркестратору глибини 1). 2. Оркестратор глибини 1 отримує оголошення, синтезує результати, завершується → оголошує основному процесу. 3. Основний агент отримує оголошення та доставляє його користувачу. Кожен рівень бачить лише оголошення від своїх безпосередніх дочірніх процесів. **Операційні настанови:** запускайте дочірню роботу один раз і чекайте на події завершення, замість того щоб будувати цикли опитування навколо `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 ` зупиняє конкретного підагентa і каскадно зупиняє його дочірні сесії. - `/subagents kill all` зупиняє всі підагенти для запитувача і запускає каскадну зупинку. ## Автентифікація Автентифікація підагентів визначається за **ідентифікатором агента**, а не за типом сесії: - Ключ сесії підагента має вигляд `agent::subagent:`. - Сховище автентифікації завантажується з `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` — безпечніший шлях оркестрації: - Спочатку нормалізується пригадування асистента: теги мислення вилучаються; каркас `` / `` вилучається; блоки XML-навантаження викликів інструментів у plain text (``, ``, ``, ``) вилучаються, включно з урізаними навантаженнями, які ніколи коректно не закриваються; понижений каркас викликів/результатів інструментів і маркери історичного контексту вилучаються; витеклі керівні токени моделі (`<|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`, щоб керувати своїми дочірніми сесіями. ### Перевизначення через конфігурацію ```json5 { 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 на етапі профілю: ```json5 { 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 ` зупиняє конкретного підагента і каскадно зупиняє його дочірні сесії. ## Обмеження - Оголошення підагентів виконується на основі **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`). ## Пов’язане - [Агенти ACP](/uk/tools/acp-agents) - [Надсилання агенту](/uk/tools/agent-send) - [Фонові завдання](/uk/automation/tasks) - [Інструменти пісочниці для багатьох агентів](/uk/tools/multi-agent-sandbox-tools)