---
read_when:
    - Вам потрібна фонова або паралельна робота через агента
    - Ви змінюєте sessions_spawn або політику інструмента субагента
    - Ви впроваджуєте або усуваєте неполадки сеансів субагентів, прив’язаних до потоку
sidebarTitle: Sub-agents
summary: Ініціюйте ізольовані фонові запуски агентів, які надсилають результати назад у чат ініціатора запиту.
title: Субагенти
x-i18n:
    generated_at: "2026-04-28T11:28:32Z"
    model: gpt-5.5
    provider: openai
    source_hash: 84386ea706873cf9f2ea03261f916c8fb01304999f2d9fa86e037e734a62bf7e
    source_path: tools/subagents.md
    workflow: 16
---

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

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

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

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

## Слеш-команда

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

```text
/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>]
```

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

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

Ці команди працюють у каналах, які підтримують сталі привʼязки до потоків.
Див. [Канали з підтримкою потоків](#thread-supporting-channels) нижче.

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

### Поведінка створення

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

<AccordionGroup>
  <Accordion title="Неблокувальне завершення на основі push">
    - Команда створення є неблокувальною; вона одразу повертає id запуску.
    - Після завершення субагент оголошує повідомлення з підсумком/результатом назад у канал чату запитувача.
    - Завершення працює на основі push. Після створення **не** опитуйте `/subagents list`, `sessions_list` або `sessions_history` у циклі лише для очікування завершення; переглядайте статус лише за потреби для налагодження або втручання.
    - Після завершення OpenClaw у режимі найкращих зусиль закриває відстежувані вкладки браузера/процеси, відкриті цим сеансом субагента, перш ніж потік очищення оголошення продовжиться.

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

  </Accordion>
  <Accordion title="Метадані передавання завершення">
    Передавання завершення до сеансу запитувача — це внутрішній контекст, згенерований середовищем виконання
    (а не текст, написаний користувачем), і він містить:

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

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

  </Accordion>
</AccordionGroup>

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

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

| Режим      | Коли його використовувати                                                                                                             | Поведінка                                                                         |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `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` (без тайм-ауту).

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

<ParamField path="task" type="string" required>
  Опис завдання для субагента.
</ParamField>
<ParamField path="label" type="string">
  Необовʼязкова зручна для людини мітка.
</ParamField>
<ParamField path="agentId" type="string">
  Створити під іншим id агента, коли це дозволено `subagents.allowAgents`.
</ParamField>
<ParamField path="runtime" type='"subagent" | "acp"' default="subagent">
  `acp` призначено лише для зовнішніх обвʼязок ACP (`claude`, `droid`, `gemini`, `opencode` або явно запитаний Codex ACP/acpx) і для записів `agents.list[]`, у яких `runtime.type` дорівнює `acp`.
</ParamField>
<ParamField path="resumeSessionId" type="string">
  Лише ACP. Відновлює наявний сеанс обвʼязки ACP, коли `runtime: "acp"`; ігнорується для нативних створень субагентів.
</ParamField>
<ParamField path="streamTo" type='"parent"'>
  Лише ACP. Транслює вивід запуску ACP до батьківського сеансу, коли `runtime: "acp"`; пропустіть для нативних створень субагентів.
</ParamField>
<ParamField path="model" type="string">
  Перевизначає модель субагента. Недійсні значення пропускаються, і субагент запускається на типовій моделі з попередженням у результаті інструмента.
</ParamField>
<ParamField path="thinking" type="string">
  Перевизначає рівень мислення для запуску субагента.
</ParamField>
<ParamField path="runTimeoutSeconds" type="number">
  Типово дорівнює `agents.defaults.subagents.runTimeoutSeconds`, коли задано, інакше `0`. Коли задано, запуск субагента переривається після N секунд.
</ParamField>
<ParamField path="thread" type="boolean" default="false">
  Коли `true`, запитує привʼязку потоку каналу для цього сеансу субагента.
</ParamField>
<ParamField path="mode" type='"run" | "session"' default="run">
  Якщо `thread: true` і `mode` пропущено, типовим стає `session`. `mode: "session"` потребує `thread: true`.
</ParamField>
<ParamField path="cleanup" type='"delete" | "keep"' default="keep">
  `"delete"` архівує негайно після оголошення (усе одно зберігає транскрипт через перейменування).
</ParamField>
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
  `require` відхиляє створення, якщо цільове дочірнє середовище виконання не перебуває в пісочниці.
</ParamField>
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
  `fork` розгалужує поточний транскрипт запитувача в дочірній сеанс. Лише нативні субагенти. Використовуйте `fork` лише коли дочірньому сеансу потрібен поточний транскрипт.
</ParamField>

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

## Сеанси, привʼязані до потоку

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

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

**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.spawnSubagentSessions`.

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

<Steps>
  <Step title="Створення">
    `sessions_spawn` з `thread: true` (і необовʼязково `mode: "session"`).
  </Step>
  <Step title="Привʼязка">
    OpenClaw створює або привʼязує потік до цієї цілі сеансу в активному каналі.
  </Step>
  <Step title="Маршрутизація наступних повідомлень">
    Відповіді та наступні повідомлення в цьому потоці маршрутизуються до привʼязаного сеансу.
  </Step>
  <Step title="Перегляд тайм-аутів">
    Використовуйте `/session idle`, щоб переглянути/оновити автоматичне скасування фокуса через неактивність, і
    `/session max-age`, щоб керувати жорстким обмеженням.
  </Step>
  <Step title="Відʼєднання">
    Використовуйте `/unfocus`, щоб відʼєднати вручну.
  </Step>
</Steps>

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

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

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

- **Глобальне значення за замовчуванням:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`.
- **Перевизначення каналу та ключі автоматичної прив’язки під час створення** залежать від адаптера. Див. [Канали з підтримкою гілок](#thread-supporting-channels) вище.

Див. [Довідник конфігурації](/uk/gateway/configuration-reference) і
[Slash-команди](/uk/tools/slash-commands), щоб переглянути поточні деталі адаптера.

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

<ParamField path="agents.list[].subagents.allowAgents" type="string[]">
  Список ідентифікаторів агентів, на які можна націлюватися через явний `agentId` (`["*"]` дозволяє будь-який). За замовчуванням: лише агент-запитувач. Якщо ви задаєте список і все одно хочете, щоб запитувач міг створювати себе з `agentId`, додайте ідентифікатор запитувача до списку.
</ParamField>
<ParamField path="agents.defaults.subagents.allowAgents" type="string[]">
  Стандартний список дозволених цільових агентів, який використовується, коли агент-запитувач не задає власний `subagents.allowAgents`.
</ParamField>
<ParamField path="agents.defaults.subagents.requireAgentId" type="boolean" default="false">
  Блокувати виклики `sessions_spawn`, які пропускають `agentId` (примушує до явного вибору профілю). Перевизначення для окремого агента: `agents.list[].subagents.requireAgentId`.
</ParamField>

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

### Виявлення

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

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

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

## Вкладені субагенти

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

```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)
      },
    },
  },
}
```

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

| Глибина | Форма ключа сеансу                           | Роль                                             | Може створювати?            |
| ------- | -------------------------------------------- | ------------------------------------------------ | --------------------------- |
| 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. Основний агент отримує оголошення та доставляє його користувачу.

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

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

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

- Роль і область керування записуються в метадані сеансу під час створення. Це не дає плоским або відновленим ключам сеансу випадково знову отримати привілеї оркестратора.
- **Глибина 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`) — **не** виводиться з тексту моделі |
| Вміст результату | Останній видимий текст помічника, інакше очищений останній текст інструмента/результату інструмента               |
| Подальша дія    | Інструкція, що описує, коли відповідати, а коли залишатися тихим                                                    |

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

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

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

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

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

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

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

- Спочатку нормалізується пригадування помічника: теги мислення вилучаються; каркаси `<relevant-memories>` / `<relevant_memories>` вилучаються; текстові XML-блоки корисного навантаження викликів інструментів (`<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`, щоб керувати своїми дочірніми елементами.

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

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

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

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

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

Субагенти використовують окрему лінію внутрішньопроцесної черги:

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

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

OpenClaw не вважає відсутність `endedAt` постійним доказом того, що
субагент досі активний. Незавершені запуски, старші за вікно застарілого запуску,
перестають враховуватися як активні/очікувані в `/subagents list`, підсумках стану,
блокуванні до завершення нащадків і перевірках паралельності для окремої сесії.

Після перезапуску Gateway застарілі незавершені відновлені запуски відсікаються, якщо
їхня дочірня сесія не позначена `abortedLastRun: true`. Такі
перервані перезапуском дочірні сесії залишаються відновлюваними через потік
відновлення осиротілого субагента, який надсилає синтетичне повідомлення відновлення перед
очищенням маркера переривання.

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

## Зупинка

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

## Обмеження

- Оголошення субагента виконується **за можливості**. Якщо 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](/uk/tools/acp-agents)
- [Надсилання агенту](/uk/tools/agent-send)
- [Фонові завдання](/uk/automation/tasks)
- [Інструменти пісочниці для кількох агентів](/uk/tools/multi-agent-sandbox-tools)
