---
read_when:
    - Ви хочете фонову/паралельну роботу через агента
    - Ви змінюєте `sessions_spawn` або політику інструментів субагента
    - Ви реалізуєте або усуваєте несправності прив’язаних до тредів сесій субагента
summary: 'Субагенти: запуск ізольованих агентських процесів, які повідомляють результати назад у чат запитувача'
title: Субагенти
x-i18n:
    generated_at: "2026-04-23T23:08:51Z"
    model: gpt-5.4
    provider: openai
    source_hash: 23202b1761e372e547b02183cb68056043aed04b5620db8b222cbfc7e6cd97ab
    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` запускає фонового субагента як команду користувача, а не як внутрішню relay-операцію, і надсилає одне фінальне повідомлення про завершення назад у чат запитувача, коли запуск завершується.

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

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

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

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

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

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

- Запускає процес субагента (`deliver: false`, глобальна смуга: `subagent`)
- Потім виконує announce-крок і публікує announce-відповідь у чат-канал запитувача
- Модель за замовчуванням: успадковується від викликача, якщо ви не встановите `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` (без тайм-ауту).

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

- `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` відхиляє spawn, якщо цільовий дочірній runtime не ізольований у пісочниці)
- `context?` (`isolated|fork`, типово `isolated`; лише для нативних субагентів)
  - `isolated` створює чистий дочірній транскрипт і є значенням за замовчуванням.
  - `fork` відгалужує поточний транскрипт запитувача в дочірню сесію, тож дочірня сесія починає з того самого контексту розмови.
  - Використовуйте `fork` лише тоді, коли дочірньому агенту потрібен поточний транскрипт. Для локалізованої роботи не вказуйте `context`.
- `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`
- Перевизначення для каналу та ключі автоприв’язки spawn є специфічними для адаптера. Див. **Канали з підтримкою тредів** вище.

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

Allowlist:

- `agents.list[].subagents.allowAgents`: список id агентів, на які можна націлюватися через `agentId` (`["*"]` — дозволити будь-який). Типово: лише агент запитувача.
- `agents.defaults.subagents.allowAgents`: allowlist цільових агентів за замовчуванням, який використовується, коли агент запитувача не задає власний `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"` архівує одразу після announce (але все одно зберігає транскрипт через перейменування).
- Автоархівація працює в режимі best-effort; очікувані таймери втрачаються, якщо gateway перезапускається.
- `runTimeoutSeconds` **не** викликає автоархівацію; він лише зупиняє запуск. Сесія залишається, доки не спрацює автоархівація.
- Автоархівація однаково застосовується до сесій глибини 1 і глибини 2.
- Очищення браузера відокремлене від очищення архіву: відстежувані вкладки/процеси браузера закриваються в режимі best-effort після завершення запуску, навіть якщо запис транскрипту/сесії зберігається.

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

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

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

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

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

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

### Ланцюжок announce

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

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

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

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

- Запускайте дочірню роботу один раз і чекайте подій завершення замість побудови циклів
  опитування навколо `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. Не може запускати подальших дочірніх агентів.

### Ліміт spawn для окремого агента

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

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

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

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

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

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

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

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

## Announce

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

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

Payload announce містить рядок статистики наприкінці (навіть якщо він загорнутий):

- Runtime (наприклад, `runtime 5m12s`)
- Використання токенів (вхідні/вихідні/загалом)
- Оцінена вартість, коли налаштовано ціноутворення моделей (`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]`
- перевірка сирого транскрипту на диску — це резервний варіант, коли вам потрібен повний побайтний транскрипт

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

За замовчуванням субагенти отримують **усі інструменти, крім інструментів сесії** та системних інструментів:

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

## Одночасність

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

- Назва смуги: `subagent`
- Одночасність: `agents.defaults.subagents.maxConcurrent` (типово `8`)

## Зупинка

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

## Обмеження

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

## Пов’язане

- [ACP agents](/uk/tools/acp-agents)
- [Інструменти пісочниці мультиагентності](/uk/tools/multi-agent-sandbox-tools)
- [Надсилання агентом](/uk/tools/agent-send)
