---
read_when:
    - Вам потрібна фонова/паралельна робота через агента
    - Ви змінюєте політику sessions_spawn або інструментів субагентів
    - Ви реалізуєте або усуваєте проблеми із сесіями субагентів, прив’язаними до тредів
summary: 'Субагенти: запуск ізольованих агентних виконань, які повідомляють про результати назад у чат запитувача'
title: Субагенти
x-i18n:
    generated_at: "2026-04-05T18:21:59Z"
    model: gpt-5.4
    provider: openai
    source_hash: 9df7cc35a3069ce4eb9c92a95df3ce5365a00a3fae92ff73def75461b58fec3f
    source_path: tools/subagents.md
    workflow: 15
---

# Субагенти

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

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

Використовуйте `/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>]`

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

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

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

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

### Поведінка spawn

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

- Команда spawn є неблокувальною; вона одразу повертає id виконання.
- Після завершення субагент повідомляє зведення/результат назад у чат-канал запитувача.
- Доставка після завершення є push-орієнтованою. Після запуску не потрібно опитувати `/subagents list`,
  `sessions_list` або `sessions_history` у циклі лише для очікування
  завершення; перевіряйте статус тільки за потреби для налагодження або втручання.
- Після завершення OpenClaw за принципом best-effort закриває відстежувані вкладки/процеси браузера, відкриті цією сесією субагента, до продовження потоку очищення повідомлення.
- Для ручних запусків доставка є стійкою:
  - OpenClaw спочатку намагається виконати пряму доставку `agent` зі стабільним ключем ідемпотентності.
  - Якщо пряма доставка не вдається, він повертається до маршрутизації через чергу.
  - Якщо маршрутизація через чергу все ще недоступна, спроба повідомлення повторюється з короткою експоненційною затримкою перед остаточною відмовою.
- Доставка після завершення зберігає визначений маршрут запитувача:
  - маршрути завершення, прив’язані до треда або розмови, мають пріоритет, коли доступні
  - якщо джерело завершення надає лише канал, OpenClaw заповнює відсутні target/account із визначеного маршруту сесії запитувача (`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-сесій (Codex, Claude Code, Gemini CLI) використовуйте `sessions_spawn` із `runtime: "acp"` і див. [ACP-агенти](/tools/acp-agents).

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

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

Примітка щодо вартості: кожен субагент має **власний** контекст і власне використання токенів. Для важких або повторюваних
завдань установіть для субагентів дешевшу модель, а основного агента залиште на якіснішій моделі.
Це можна налаштувати через `agents.defaults.subagents.model` або через перевизначення для окремих агентів.

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

Використовуйте `sessions_spawn`:

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

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

- `task` (обов’язково)
- `label?` (необов’язково)
- `agentId?` (необов’язково; запуск під іншим id агента, якщо дозволено)
- `model?` (необов’язково; перевизначає модель субагента; невалідні значення пропускаються, і субагент працює на типовій моделі з попередженням у результаті інструмента)
- `thinking?` (необов’язково; перевизначає рівень thinking для виконання субагента)
- `runTimeoutSeconds?` (типово береться з `agents.defaults.subagents.runTimeoutSeconds`, якщо задано, інакше `0`; якщо встановлено, виконання субагента переривається після N секунд)
- `thread?` (типово `false`; коли `true`, запитує прив’язку до треда каналу для цієї сесії субагента)
- `mode?` (`run|session`)
  - типове значення — `run`
  - якщо `thread: true` і `mode` не задано, типове значення стає `session`
  - `mode: "session"` вимагає `thread: true`
- `cleanup?` (`delete|keep`, типово `keep`)
- `sandbox?` (`inherit|require`, типово `inherit`; `require` відхиляє запуск, якщо цільовий дочірній runtime не ізольований)
- `sessions_spawn` **не** приймає параметри доставки каналу (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Для доставки використовуйте `message`/`sessions_send` із запущеного виконання.

## Сесії, прив’язані до тредів

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

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

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

Швидкий сценарій:

1. Запустіть через `sessions_spawn` із `thread: true` (і за потреби `mode: "session"`).
2. OpenClaw створює тред або прив’язує його до цільової сесії в активному каналі.
3. Відповіді та подальші повідомлення в цьому треді маршрутизуються до прив’язаної сесії.
4. Використовуйте `/session idle`, щоб переглядати/оновлювати автоматичне розфокусування за неактивністю, і `/session max-age`, щоб керувати жорстким лімітом.
5. Використовуйте `/unfocus`, щоб відв’язати вручну.

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

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

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

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

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

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

- `agents.list[].subagents.allowAgents`: список id агентів, на які можна націлюватися через `agentId` (`["*"]` дозволяє будь-який). Типово: лише агент запитувача.
- `agents.defaults.subagents.allowAgents`: типовий список дозволених цільових агентів, який використовується, коли агент запитувача не задає власний `subagents.allowAgents`.
- Захист успадкування ізоляції: якщо сесія запитувача ізольована, `sessions_spawn` відхиляє цілі, які працювали б без ізоляції.
- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: коли true, блокують виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю). Типове значення: false.

Виявлення:

- Використовуйте `agents_list`, щоб побачити, які id агентів зараз дозволені для `sessions_spawn`.

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

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

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

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

### Як увімкнути

```json5
{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // дозволити субагентам запускати дочірні агенти (типово: 1)
        maxChildrenPerAgent: 5, // максимальна кількість активних дочірніх агентів на одну сесію агента (типово: 5)
        maxConcurrent: 8, // глобальне обмеження concurrency для lane (типово: 8)
        runTimeoutSeconds: 900, // типовий timeout для sessions_spawn, коли його пропущено (0 = без timeout)
      },
    },
  },
}
```

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

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

### Ланцюжок повідомлень

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

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

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

Операційні рекомендації:

- Запускайте дочірню роботу один раз і чекайте подій завершення замість побудови циклів опитування
  навколо `sessions_list`, `sessions_history`, `/subagents list` або
  `exec`-команд зі sleep.
- Якщо подія завершення дочірнього елемента надходить після того, як ви вже надіслали фінальну відповідь,
  правильною подальшою дією є точний тихий токен `NO_REPLY` / `no_reply`.

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

- Роль і область керування записуються в метадані сесії під час spawn. Це не дає плоским або відновленим ключам сесії випадково знову отримати привілеї оркестратора.
- **Глибина 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>` зупиняє конкретного субагента і каскадно зупиняє його дочірніх елементів.
- `/subagents kill all` зупиняє всіх субагентів для запитувача і виконує каскадну зупинку.

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

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

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

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

## Повідомлення

Субагенти звітують назад через крок повідомлення:

- Крок повідомлення виконується всередині сесії субагента (а не сесії запитувача).
- Якщо субагент відповідає точно `ANNOUNCE_SKIP`, нічого не публікується.
- Якщо останній текст помічника — це точний тихий токен `NO_REPLY` / `no_reply`,
  вивід повідомлення пригнічується, навіть якщо раніше був видимий прогрес.
- Інакше доставка залежить від глибини запитувача:
  - сесії запитувача верхнього рівня використовують подальший виклик `agent` із зовнішньою доставкою (`deliver=true`)
  - вкладені сесії субагентів-запитувачів отримують внутрішню ін’єкцію подальшої дії (`deliver=false`), щоб оркестратор міг синтезувати результати дочірніх елементів у межах сесії
  - якщо вкладена сесія субагента-запитувача зникла, OpenClaw повертається до запитувача цієї сесії, коли це можливо
- Для сесій запитувача верхнього рівня пряма доставка в режимі завершення спочатку визначає будь-який маршрут прив’язаної розмови/треда та перевизначення hook, а потім заповнює відсутні поля channel-target із збереженого маршруту сесії запитувача. Це зберігає доставки завершення в правильному чаті/темі, навіть коли джерело завершення ідентифікує лише канал.
- Агрегація завершень дочірніх елементів обмежується поточним виконанням запитувача під час побудови вкладених результатів завершення, що запобігає витоку застарілих виводів дочірніх елементів із попередніх запусків у поточне повідомлення.
- Відповіді-повідомлення зберігають маршрутизацію треда/теми, коли вона доступна в адаптерах каналів.
- Контекст повідомлення нормалізується до стабільного внутрішнього блоку подій:
  - джерело (`subagent` або `cron`)
  - ключ/id дочірньої сесії
  - тип повідомлення + мітка завдання
  - рядок статусу, похідний від результату runtime (`success`, `error`, `timeout` або `unknown`)
  - вміст результату, вибраний з останнього видимого тексту помічника, інакше санітизований останній текст tool/toolResult
  - інструкція подальшої дії, яка описує, коли слід відповідати, а коли мовчати
- `Status` не виводиться з виводу моделі; він походить із сигналів результату runtime.
- У разі timeout, якщо дочірній елемент встиг лише до викликів інструментів, повідомлення може згорнути цю історію в коротке зведення часткового прогресу замість відтворення сирого виводу інструментів.

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

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

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

- згадування відповідей помічника спочатку нормалізується:
  - thinking-теги видаляються
  - блоки каркаса `<relevant-memories>` / `<relevant_memories>` видаляються
  - блоки XML-корисного навантаження викликів інструментів у звичайному тексті, як-от `<tool_call>...</tool_call>`,
    `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>` і
    `<function_calls>...</function_calls>`, видаляються, включно з обрізаними
    payload, які так і не закриваються коректно
  - понижений каркас викликів/результатів інструментів та маркери історичного контексту видаляються
  - витоки керівних токенів моделі, таких як `<|assistant|>`, інші ASCII
    токени `<|...|>` і повноширинні варіанти `<｜...｜>`, видаляються
  - некоректний XML викликів інструментів MiniMax видаляється
- текст, схожий на облікові дані/токени, редагується
- довгі блоки можуть бути обрізані
- у дуже великих історіях старіші рядки можуть бути відкинуті або надто великий рядок може бути замінений на
  `[sessions_history omitted: message too large]`
- перевірка сирого транскрипту на диску є fallback, коли вам потрібен повний побайтний транскрипт

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

Типово субагенти отримують **усі інструменти, крім інструментів сесій** і системних інструментів:

- `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 має пріоритет
        deny: ["gateway", "cron"],
        // якщо встановлено allow, політика стає лише allow-only (deny усе одно має пріоритет)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}
```

## Конкурентність

Субагенти використовують окрему lane черги в межах процесу:

- Назва lane: `subagent`
- Конкурентність: `agents.defaults.subagents.maxConcurrent` (типове значення `8`)

## Зупинка

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

## Обмеження

- Повідомлення субагента працює за принципом **best-effort**. Якщо gateway перезапуститься, незавершена робота «повідомити назад» буде втрачена.
- Субагенти все ще спільно використовують ресурси того самого процесу 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).
