> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Субагенты

Субагенты — это фоновые запуски агентов, порождённые из существующего запуска агента.
Каждый из них выполняется в собственном сеансе (`agent:<agentId>:subagent:<uuid>`) и
после завершения **объявляет** свой результат обратно в канал чата запрашивающей стороны.
Каждый запуск субагента отслеживается как [фоновая задача](https://docs2.openclaw.ai/ru/automation/tasks.md).

Цели:

* Распараллеливать исследования, длительные задачи и медленную работу с инструментами, не блокируя основной запуск.
* По умолчанию изолировать субагентов (раздельные сеансы, необязательная песочница).
* Не допускать неправильного использования набора инструментов: по умолчанию субагенты **не** получают инструменты сеансов или сообщений.
* Поддерживать настраиваемую глубину вложенности для шаблонов оркестрации.

> [!NOTE]
>
> **Примечание о стоимости:** по умолчанию каждый субагент имеет собственный контекст и
> расход токенов. Для ресурсоёмких или повторяющихся задач задайте для субагентов
> более дешёвую модель, а для основного агента оставьте более качественную модель с помощью
> `agents.defaults.subagents.model` или переопределений для отдельных агентов. Когда дочернему агенту
> действительно нужна текущая расшифровка диалога запрашивающей стороны, породите его с
> `context: "fork"`. Для сеансов субагентов, привязанных к ветке обсуждения, по умолчанию используется
> `context: "fork"`, поскольку они ответвляют текущий разговор в
> последующую ветку обсуждения.

## Команда с косой чертой

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

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
/subagents list
/subagents log <id|#> [limit] [tools]
/subagents info <id|#>
```

`/subagents info` показывает метаданные запуска (состояние, временные метки, идентификатор сеанса,
путь к расшифровке, очистку). `/subagents log` выводит последние реплики чата для
запуска; добавьте токен `tools`, чтобы включить сообщения вызовов инструментов и их результатов (по
умолчанию они опущены). Используйте `sessions_history` для ограниченного и отфильтрованного с учётом безопасности просмотра
контекста из хода агента либо откройте путь к расшифровке на диске, чтобы
просмотреть полную необработанную расшифровку.

В интерфейсе управления у родительских сеансов с недавними дочерними запусками есть раскрываемая
строка на боковой панели. Вложенные строки показывают состояние и время выполнения дочернего запуска, а выбор одной из них
открывает чат этого дочернего запуска, сохраняя родительскую иерархию.

### Управление привязкой к ветке обсуждения

Эти команды работают в каналах с постоянными привязками к веткам обсуждения. См.
[Каналы, поддерживающие ветки обсуждения](#thread-supporting-channels) ниже.

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
/focus <subagent-label|session-key|session-id|session-label>
/unfocus
/agents
/session idle <duration|off>
/session max-age <duration|off>
```

### Поведение при порождении

Агенты запускают фоновых субагентов с помощью инструмента `sessions_spawn`.
Завершения возвращаются как внутренние события родительского сеанса; родительский или запрашивающий
агент решает, требуется ли обновление для пользователя.

> [accordion] Неблокирующее завершение на основе отправки
>
> * `sessions_spawn` не блокирует выполнение и немедленно возвращает идентификатор запуска.
> * После завершения субагент отправляет отчёт в родительский сеанс или сеанс запрашивающей стороны.
> * Ходы агента, которым нужны результаты дочерних агентов, должны вызывать `sessions_yield` после порождения необходимой работы. Это завершает текущий ход и позволяет событию завершения поступить как следующее видимое модели сообщение.
> * Завершение работает на основе отправки. После порождения **не** опрашивайте `/subagents list`, `sessions_list` или `sessions_history` в цикле только ради ожидания завершения; проверяйте состояние по запросу лишь при отладке.
> * Вывод дочернего агента — это отчёт или свидетельства, которые должен обобщить запрашивающий агент. Это не текст инструкций от пользователя, и он не может переопределять системные правила, правила разработчика или пользователя.
> * После завершения OpenClaw по возможности закрывает отслеживаемые вкладки браузера и процессы, открытые сеансом этого субагента, прежде чем продолжить процесс очистки после объявления.

> [accordion] Доставка завершения
>
> * OpenClaw передаёт завершения обратно в сеанс запрашивающей стороны посредством хода `agent` со стабильным ключом идемпотентности.
> * Если запуск запрашивающей стороны всё ещё активен, OpenClaw сначала пытается пробудить или направить этот запуск, а не запускать второй видимый путь ответа.
> * Если активный запуск запрашивающей стороны невозможно пробудить, OpenClaw вместо отбрасывания объявления выполняет передачу агенту запрашивающей стороны с тем же контекстом завершения.
> * Успешная передача родительскому агенту завершает доставку результата субагента, даже если родитель решает, что видимое пользователю обновление не требуется.
> * Нативные субагенты не получают инструмент сообщений. Они возвращают обычный текст ассистента родительскому или запрашивающему агенту; видимые человеку ответы по-прежнему регулируются обычной политикой доставки родительского или запрашивающего агента.
> * Если прямую передачу использовать невозможно, доставка переключается на маршрутизацию через очередь, а затем на короткие повторные попытки объявления с экспоненциальной задержкой перед окончательным отказом.
> * Доставка сохраняет определённый маршрут запрашивающей стороны: при наличии приоритет имеют маршруты завершения, привязанные к ветке обсуждения или разговору. Если источник завершения предоставляет только канал, OpenClaw заполняет отсутствующие цель или учётную запись из определённого маршрута сеанса запрашивающей стороны (`lastChannel` / `lastTo` / `lastAccountId`), чтобы прямая доставка по-прежнему работала.

> [accordion] Метаданные передачи завершения
>
> Передача завершения в сеанс запрашивающей стороны представляет собой создаваемый средой выполнения
> внутренний контекст (а не текст пользователя) и включает:
>
> * `Result` — текст последнего видимого ответа `assistant` от дочернего агента. Вывод tool/toolResult не включается в результаты дочернего агента. Окончательно завершившиеся с ошибкой запуски не используют повторно сохранённый текст ответа.
> * `Status` — `completed; ready for parent review` / `failed` / `timed out` / `unknown`.
> * Краткую статистику среды выполнения и токенов.
> * Инструкцию по проверке, предписывающую запрашивающему агенту проверить результат, прежде чем решать, выполнена ли исходная задача.
> * Указание по дальнейшим действиям, предписывающее запрашивающему агенту продолжить задачу или зафиксировать последующую задачу, если результат дочернего агента требует дополнительных действий.
> * Инструкцию по окончательному обновлению для случая, когда дополнительных действий не требуется, сформулированную обычным голосом ассистента без передачи необработанных внутренних метаданных.

> [accordion] Режимы и среда выполнения ACP
>
> * `--model` и `--thinking` переопределяют значения по умолчанию для конкретного запуска.
> * Используйте `info`/`log`, чтобы после завершения просмотреть сведения и вывод.
> * Для постоянных сеансов, привязанных к ветке обсуждения, используйте `sessions_spawn` с `thread: true` и `mode: "session"`.
> * Если канал запрашивающей стороны не поддерживает привязку к веткам обсуждения, используйте `mode: "run"` вместо повторной попытки с заведомо невозможной комбинацией привязки к ветке.
> * Для сеансов среды ACP (Claude Code, Gemini CLI, OpenCode или явного Codex ACP/acpx) используйте `sessions_spawn` с `runtime: "acp"`, когда инструмент объявляет о поддержке этой среды выполнения. При отладке завершений или циклов взаимодействия между агентами см. [Модель доставки ACP](https://docs2.openclaw.ai/ru/tools/acp-agents.md#delivery-model). Когда включён плагин `codex`, для управления чатом и ветками Codex следует предпочитать `/codex ...` вместо ACP, если пользователь явно не запросил ACP/acpx.
> * OpenClaw скрывает `runtime: "acp"`, пока ACP не включён, запрашивающая сторона не работает в песочнице и не загружен серверный плагин, такой как `acpx`. `runtime: "acp"` ожидает идентификатор внешней среды ACP либо запись `agents.list[]` с `runtime.type="acp"`; для обычных агентов конфигурации OpenClaw из `agents_list` используйте среду выполнения субагентов по умолчанию.

## Режимы контекста

Нативные субагенты запускаются изолированно, если вызывающая сторона явно не запрашивает ответвление
текущей расшифровки диалога.

| Режим | Когда использовать | Поведение |
| - | - | - |
| `isolated` | Новое исследование, независимая реализация, медленная работа с инструментами или любая задача, которую можно кратко описать в тексте задания | Создаёт чистую расшифровку дочернего сеанса. Это режим по умолчанию, снижающий расход токенов. |
| `fork` | Работа, зависящая от текущего разговора, предыдущих результатов инструментов или уже присутствующих в расшифровке запрашивающей стороны подробных инструкций | Ответвляет расшифровку запрашивающей стороны в дочерний сеанс до запуска дочернего агента. |

Используйте `fork` умеренно. Он предназначен для делегирования, зависящего от контекста, а не
для замены чёткой формулировки задания.

## Инструмент: `sessions_spawn`

Запускает субагента с `deliver: false` в глобальной очереди `subagent`,
затем выполняет этап объявления и публикует ответ с объявлением в канал
чата запрашивающей стороны.

Доступность зависит от действующей политики инструментов вызывающей стороны. Встроенный
профиль `coding` включает `sessions_spawn`; `messaging` и `minimal`
не включают его. `full` разрешает все инструменты. Добавьте `tools.alsoAllow: ["sessions_spawn",
"sessions_yield", "subagents"]` либо используйте `tools.profile: "coding"` для
агентов с более узким профилем, которым всё же нужно делегировать работу.
Политики разрешений и запретов для канала или группы, провайдера, песочницы и отдельных агентов
по-прежнему могут удалить инструмент после этапа профиля. Используйте `/tools` из того же
сеанса, чтобы проверить действующий список инструментов.

**Значения по умолчанию:**

* **Модель:** нативные субагенты наследуют модель вызывающей стороны, если не задано `agents.defaults.subagents.model` (или `agents.list[].subagents.model` для отдельного агента). Запуски среды ACP используют ту же настроенную модель субагента при её наличии; иначе среда ACP сохраняет собственную модель по умолчанию. Явное значение `sessions_spawn.model` всё равно имеет приоритет.
* **Рассуждение:** нативные субагенты наследуют настройку вызывающей стороны, если не задано `agents.defaults.subagents.thinking` (или `agents.list[].subagents.thinking` для отдельного агента). Запуски среды ACP также применяют `agents.defaults.models["provider/model"].params.thinking` для выбранной модели. Явное значение `sessions_spawn.thinking` всё равно имеет приоритет.
* **Тайм-аут запуска:** OpenClaw использует `agents.defaults.subagents.runTimeoutSeconds`, если он задан; иначе применяется `0` (без тайм-аута). `sessions_spawn` не принимает переопределения тайм-аута для отдельных вызовов.
* **Доставка задачи:** нативные субагенты получают делегированную задачу в своём первом видимом сообщении `[Subagent Task]`. Системный промпт субагента содержит правила среды выполнения и контекст маршрутизации, а не скрытую копию задачи.

Результат инструмента для принятых запусков нативных субагентов содержит метаданные
определённой дочерней модели: `resolvedModel` содержит применённую ссылку на модель, а
`resolvedProvider` — префикс провайдера, если он присутствует в ссылке.

### Режим промпта делегирования

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

* `suggest` (по умолчанию): сохранять стандартную подсказку промпта об использовании субагентов для более крупных или медленных задач.
* `prefer`: предписывать основному агенту сохранять отзывчивость и делегировать через `sessions_spawn` всё, что сложнее прямого ответа.

Переопределение для отдельного агента: `agents.list[].subagents.delegationMode`.

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      subagents: {
        delegationMode: "prefer",
        maxConcurrent: 4,
      },
    },
    list: [
      {
        id: "coordinator",
        subagents: { delegationMode: "prefer" },
      },
    ],
  },
}
```

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

**task** `string` *required*

Описание задачи для субагента.

**taskName** `string`

Необязательный стабильный идентификатор для распознавания конкретного дочернего агента в последующем выводе состояния. Должен соответствовать `[a-z][a-z0-9_-]{0,63}` и не может быть зарезервированной целью, такой как `last` или `all`.

**label** `string`

Необязательная удобочитаемая метка.

**agentId** `string`

Запускает процесс под другим настроенным идентификатором агента, если это разрешено параметром `subagents.allowAgents`.

**cwd** `string`

Необязательный рабочий каталог задачи для дочернего запуска. Нативные субагенты по-прежнему загружают файлы начальной настройки из рабочего пространства целевого агента; `cwd` изменяет только место, где инструменты среды выполнения и CLI-обвязки выполняют делегированную работу.

**runtime** `"subagent" | "acp"` (default: subagent)

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

**resumeSessionId** `string`

Только для ACP. Возобновляет существующий сеанс обвязки ACP, когда `runtime: "acp"`; игнорируется при запуске нативных субагентов.

**streamTo** `"parent"`

Только для ACP. Передаёт потоковый вывод запуска ACP родительскому сеансу, когда `runtime: "acp"`; не указывайте при запуске нативных субагентов.

**model** `string`

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

**thinking** `string`

Переопределяет уровень рассуждений для запуска субагента.

**thread** `boolean` (default: false)

Когда `true`, запрашивает привязку к ветке канала для этого сеанса субагента.

**mode** `"run" | "session"` (default: run)

Если `thread: true` и `mode` не указан, значением по умолчанию становится `session`. `mode: "session"` требует `thread: true`.
Если привязка к ветке недоступна для канала запрашивающей стороны, используйте вместо неё `mode: "run"`.

**cleanup** `"delete" | "keep"` (default: keep)

`"delete"` архивирует сеанс сразу после объявления (расшифровка всё равно сохраняется посредством переименования).

**sandbox** `"inherit" | "require"` (default: inherit)

`require` отклоняет запуск, если целевая среда выполнения дочернего агента не изолирована в песочнице.

**context** `"isolated" | "fork"` (default: isolated)

`fork` ответвляет текущую расшифровку запрашивающей стороны в дочерний сеанс. Только для нативных субагентов. Для запусков с привязкой к ветке по умолчанию используется `fork`; для запусков без привязки — `isolated`.

> [!WARNING]
>
> `sessions_spawn` **не** принимает параметры доставки в канал (`target`,
> `channel`, `to`, `threadId`, `replyTo`, `transport`). Нативные субагенты передают
> свой последний ответ ассистента обратно запрашивающей стороне; внешняя доставка остаётся задачей
> родительского/запрашивающего агента.

### Имена задач и выбор цели

`taskName` — это доступный модели идентификатор для оркестрации, а не ключ сеанса.
Используйте его для стабильных имён дочерних агентов, таких как `review_subagents`,
`linux_validation` или `docs_update`, когда координатору может потребоваться позднее проверить
этого дочернего агента.

При разрешении цели принимаются точные совпадения `taskName` и однозначные
префиксы. Поиск совпадений ограничен тем же окном активных/недавних целей, которое используется
для нумерованных целей `/subagents`, поэтому устаревший завершённый дочерний агент не делает
повторно использованный идентификатор неоднозначным. Если два активных или недавних дочерних агента имеют одинаковый
`taskName`, цель неоднозначна; используйте вместо него индекс списка, ключ сеанса или
идентификатор запуска.

Зарезервированные цели `last` и `all` недопустимы как значения `taskName`,
поскольку у них уже есть управляющие значения.

## Инструмент: `sessions_yield`

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

`sessions_yield` — примитив ожидания. Не заменяйте его циклами опроса
`subagents`, `sessions_list`, `sessions_history`, оболочки
`sleep` или процессов только для обнаружения завершения дочернего агента.

Используйте `sessions_yield` только тогда, когда он входит в эффективный список инструментов сеанса.
Некоторые минимальные или пользовательские профили инструментов могут предоставлять `sessions_spawn` и
`subagents`, не предоставляя `sessions_yield`; в таком случае не создавайте
цикл опроса только для ожидания завершения.

Когда существуют активные дочерние агенты, OpenClaw внедряет компактный сформированный средой выполнения
блок подсказки `Active Subagents` в обычные ходы, чтобы запрашивающая сторона могла видеть
текущие дочерние сеансы, идентификаторы запусков, состояния, метки, задачи и
псевдонимы `taskName` без опроса. Поля задачи и метки в этом
блоке заключаются в кавычки как данные, а не как инструкции, поскольку они могут происходить
из предоставленных пользователем или моделью аргументов запуска.

## Инструмент: `subagents`

Выводит список запусков субагентов, принадлежащих запрашивающему сеансу. Область действия
ограничена текущей запрашивающей стороной; дочерний агент может видеть только собственных управляемых дочерних агентов.

Используйте `subagents` для проверки состояния и отладки по запросу. Используйте `sessions_yield` для
ожидания событий завершения.

## Сеансы с привязкой к ветке

Когда для канала включены привязки к веткам, субагент может оставаться привязанным
к ветке, чтобы последующие сообщения пользователя в этой ветке продолжали направляться в тот же
сеанс субагента.

### Каналы, поддерживающие ветки

Канал поддерживает постоянные сеансы субагентов с привязкой к ветке
(`sessions_spawn` с `thread: true`), когда он регистрирует адаптер
привязки беседы. Встроенные каналы с такой поддержкой: **Discord**,
**iMessage**, **Matrix** и **Telegram**. Discord и Matrix по умолчанию
создают дочернюю ветку; Telegram и iMessage по умолчанию привязывают
текущую беседу. Используйте ключи конфигурации `threadBindings` для каждого канала, чтобы
настроить включение, тайм-ауты и `spawnSessions`.

### Краткая последовательность

**1. Запуск**

`sessions_spawn` с `thread: true` (и при необходимости `mode: "session"`).

**2. Привязка**

OpenClaw создаёт или привязывает ветку к цели этого сеанса в активном канале.

**3. Маршрутизация последующих сообщений**

Ответы и последующие сообщения в этой ветке направляются в привязанный сеанс.

**4. Проверка тайм-аутов**

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

**5. Отсоединение**

Используйте `/unfocus`, чтобы отсоединить вручную.

### Ручное управление

| Команда | Результат |
| - | - |
| `/focus <target>` | Привязать текущую ветку (или создать её) к цели субагента/сеанса |
| `/unfocus` | Удалить привязку для текущей привязанной ветки |
| `/agents` | Вывести активные запуски и состояние привязки (`binding:<id>`, `unbound` или `bindings unavailable`) |
| `/session idle` | Проверить или изменить автоматическое снятие фокуса при бездействии (только для привязанных веток в фокусе) |
| `/session max-age` | Проверить или изменить жёсткое ограничение (только для привязанных веток в фокусе) |

### Параметры конфигурации

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

Актуальные сведения об адаптерах см. в разделах [Справочник по конфигурации](https://docs2.openclaw.ai/ru/gateway/configuration-reference.md) и
[Команды с косой чертой](https://docs2.openclaw.ai/ru/tools/slash-commands.md).

### Список разрешённых агентов

**agents.list\[].subagents.allowAgents** `string[]`

Список идентификаторов настроенных агентов, которые можно выбрать через явно заданный `agentId` (`["*"]` разрешает любую настроенную цель). По умолчанию: только запрашивающий агент. Если задан список и запрашивающему агенту всё ещё требуется запускать самого себя с помощью `agentId`, включите идентификатор запрашивающего агента в список.

**agents.defaults.subagents.allowAgents** `string[]`

Список разрешённых целевых настроенных агентов по умолчанию, используемый, когда запрашивающий агент не задаёт собственный `subagents.allowAgents`.

**agents.defaults.subagents.requireAgentId** `boolean` (default: false)

Блокирует вызовы `sessions_spawn`, в которых не указан `agentId` (требует явного выбора профиля). Переопределение для отдельного агента: `agents.list[].subagents.requireAgentId`.

**agents.defaults.subagents.announceTimeoutMs** `number` (default: 120000)

Тайм-аут отдельного вызова для попыток доставки объявления Gateway через `agent`. Значения задаются положительным целым числом миллисекунд и ограничиваются максимальным безопасным для платформы значением таймера. Из-за повторных попыток при временных сбоях общее ожидание объявления может длиться дольше одного настроенного тайм-аута.

Если запрашивающий сеанс изолирован в песочнице, `sessions_spawn` отклоняет цели,
которые выполнялись бы вне песочницы.

### Обнаружение

Используйте `agents_list`, чтобы увидеть, какие идентификаторы агентов в данный момент разрешены для
`sessions_spawn`. Ответ содержит эффективную модель каждого указанного агента и встроенные
метаданные среды выполнения, чтобы вызывающие стороны могли различать OpenClaw, сервер приложения Codex
и другие настроенные нативные среды выполнения.

Записи `allowAgents` должны указывать на идентификаторы настроенных агентов в `agents.list[]`.
`["*"]` означает любого настроенного целевого агента, а также запрашивающего агента. Если конфигурация агента
удалена, но его идентификатор остаётся в `allowAgents`, `sessions_spawn` отклоняет этот идентификатор,
а `agents_list` не включает его в вывод. Запустите `openclaw doctor --fix`, чтобы удалить устаревшие
записи списка разрешённых агентов, или добавьте минимальную запись `agents.list[]`, если цель должна
оставаться доступной для запуска с наследованием значений по умолчанию.

### Автоматическое архивирование

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

## Вложенные субагенты

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // разрешить субагентам запускать дочерних агентов (по умолчанию: 1, диапазон 1–5)
        maxChildrenPerAgent: 5, // максимальное число активных дочерних агентов на сеанс агента (по умолчанию: 5, диапазон 1–20)
        maxConcurrent: 8, // глобальное ограничение параллелизма (по умолчанию: 8)
        runTimeoutSeconds: 900, // тайм-аут по умолчанию для sessions_spawn (0 = без тайм-аута)
        announceTimeoutMs: 120000, // тайм-аут отдельного вызова для объявления через gateway
      },
    },
  },
}
```

### Уровни глубины

| Глубина | Формат ключа сессии | Роль | Может порождать? |
| - | - | - | - |
| 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`.

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

* Роль и область управления записываются в метаданные сессии при порождении. Это не позволяет плоским или восстановленным ключам сессий случайно вернуть привилегии оркестратора.
* **Глубина 1 (оркестратор, когда `maxSpawnDepth >= 2`):** получает `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, чтобы порождать дочерние агенты и проверять их состояние. Остальные инструменты сессии и системные инструменты остаются запрещёнными.
* **Глубина 1 (конечный исполнитель, когда `maxSpawnDepth == 1`):** инструменты сессии отсутствуют (текущее поведение по умолчанию).
* **Глубина 2 (конечный исполнитель):** инструменты сессии отсутствуют — `sessions_spawn` всегда запрещён на глубине 2. Порождать последующие дочерние агенты нельзя.

### Ограничение порождения на агента

У каждой сессии агента (на любой глубине) одновременно может быть не более
`maxChildrenPerAgent` (по умолчанию `5`) активных дочерних агентов.
Это предотвращает неконтролируемое разветвление от одного оркестратора.

### Каскадная остановка

Остановка оркестратора глубины 1 автоматически останавливает все его дочерние
агенты глубины 2:

* `/stop` в основном чате останавливает всех агентов глубины 1 и каскадно останавливает их дочерние агенты глубины 2.

## Аутентификация

Данные аутентификации субагента определяются по **идентификатору агента**, а не по типу сессии:

* Ключ сессии субагента — `agent:<agentId>:subagent:<uuid>`.
* Хранилище данных аутентификации загружается из `agentDir` этого агента.
* Профили аутентификации главного агента объединяются как **резервные**; при конфликтах профили агента имеют приоритет над профилями главного агента.

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

## Уведомление

Субагенты сообщают о результатах через этап уведомления:

* Этап уведомления выполняется внутри сессии субагента (а не в сессии инициатора запроса).
* Если субагент отвечает точной строкой `ANNOUNCE_SKIP`, ничего не публикуется.
* Если последний текст ассистента является точным беззвучным токеном `NO_REPLY` / `no_reply`, вывод уведомления подавляется, даже если ранее отображался видимый прогресс.

Способ доставки зависит от глубины инициатора запроса:

* Для сессий инициатора верхнего уровня используется последующий вызов `agent` с внешней доставкой (`deliver=true`).
* Вложенные сессии субагентов-инициаторов получают внутреннюю последующую вставку (`deliver=false`), чтобы оркестратор мог обобщить результаты дочерних агентов внутри сессии.
* Если вложенная сессия субагента-инициатора уже отсутствует, OpenClaw по возможности возвращается к инициатору этой сессии.

Для сессий инициатора верхнего уровня прямая доставка в режиме завершения сначала
определяет привязанный маршрут разговора/ветки и переопределение перехватчика, а затем
заполняет отсутствующие поля канала и получателя из сохранённого маршрута сессии инициатора.
Благодаря этому результаты завершения поступают в правильный чат/тему, даже если источник
завершения определяет только канал.

При формировании результатов вложенного завершения агрегация завершений дочерних агентов
ограничивается текущим запуском инициатора, что предотвращает попадание устаревших результатов
дочерних агентов из предыдущих запусков в текущее уведомление. Ответы-уведомления сохраняют
маршрутизацию ветки/темы, если она доступна в адаптерах каналов.

### Контекст уведомления

Контекст уведомления нормализуется в стабильный внутренний блок событий:

| Поле | Источник |
| - | - |
| Источник | `subagent` или `cron` |
| Идентификаторы сессии | Ключ/идентификатор дочерней сессии |
| Тип | Тип уведомления + метка задачи |
| Состояние | Определяется по результату выполнения (`ok`, `error`, `timeout` или `unknown`) — **не** выводится из текста модели |
| Содержимое результата | Последний видимый текст ассистента от дочернего агента |
| Последующее действие | Инструкция о том, когда отвечать, а когда сохранять молчание |

Завершившиеся с ошибкой запуски сообщают состояние ошибки без повторного воспроизведения
захваченного текста ответа. Вывод tool/toolResult не преобразуется в текст результата
дочернего агента.

### Строка статистики

В конце полезной нагрузки уведомлений добавляется строка статистики (даже при переносе):

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

Внутренние метаданные предназначены только для оркестрации; ответы пользователю
следует переформулировать обычным языком ассистента.

### Почему предпочтителен `sessions_history`

`sessions_history` — более безопасный способ оркестрации для чтения расшифровки
дочернего агента во время хода агента:

* Скрывает текст, похожий на учётные данные или токены, даже если общее скрытие конфиденциальных данных в журналах отключено.
* Обрезает длинные текстовые блоки (4000 символов на блок) и удаляет сигнатуры размышлений, полезную нагрузку повторного воспроизведения рассуждений и встроенные данные изображений.
* Ограничивает размер ответа до 80 КБ; строки превышенного размера заменяются на `[sessions_history omitted: message too large]`.
* Используйте `nextOffset`, если он присутствует, чтобы постранично переходить назад к более старым окнам расшифровки.
* `sessions_history` **не** удаляет теги рассуждений, служебную структуру `<relevant-memories>` или XML вызовов инструментов из текста сообщения — он возвращает структурированные блоки содержимого, близкие к исходному формату расшифровки, но со скрытыми конфиденциальными данными и ограниченным размером. `/subagents log` применяет более строгую очистку прозы (удаляет теги рассуждений, служебную структуру памяти и XML вызовов инструментов), поскольку отображает обычные строки чата вместо структурированных блоков.
* Просмотр необработанной расшифровки на диске служит резервным способом, когда требуется полная побайтовая расшифровка.

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

Сначала к субагентам применяется тот же профиль и конвейер политики инструментов,
что и к родительскому или целевому агенту. После этого OpenClaw применяет слой
ограничений субагента.

Субагенты всегда лишаются `gateway`, `agents_list`, `session_status` и
`cron` независимо от глубины или роли (системные/интерактивные инструменты либо
инструменты, работу которых должен координировать главный агент). Конечные субагенты
(поведение по умолчанию на глубине 1 и всегда на глубине 2) дополнительно лишаются
`subagents`, `sessions_list`, `sessions_history` и `sessions_spawn`.
Субагенты никогда не получают инструмент `message` — он отключается при
порождении, а не фильтруется этим списком запретов, — а `sessions_send` остаётся
запрещённым, чтобы субагенты взаимодействовали только через цепочку уведомлений.

`sessions_history` и здесь остаётся ограниченным и очищенным представлением
извлечённых данных — это не необработанная выгрузка расшифровки.

Когда `maxSpawnDepth >= 2`, субагенты-оркестраторы глубины 1 дополнительно
получают `sessions_spawn`, `subagents`, `sessions_list` и
`sessions_history`, чтобы управлять своими дочерними агентами.

### Переопределение через конфигурацию

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // запрет имеет приоритет
        deny: ["gateway", "cron"],
        // если задан allow, он становится списком исключительно разрешённых инструментов (запрет по-прежнему имеет приоритет)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}
```

`tools.subagents.tools.allow` — это окончательный фильтр исключительно разрешённых инструментов.
Он может сузить уже определённый набор инструментов, но не может **вернуть**
инструмент, удалённый через `tools.profile`. Например, `tools.profile: "coding"`
включает `web_search`/`web_fetch`, но не инструмент
`browser`. Чтобы разрешить субагентам с профилем программирования
использовать автоматизацию браузера, добавьте браузер на этапе профиля:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}
```

Используйте отдельный для агента `agents.list[].tools.alsoAllow: ["browser"]`, если автоматизацию
браузера должен получить только один агент.

## Параллелизм

Субагенты используют выделенную внутрипроцессную очередь:

* **Имя очереди:** `subagent`
* **Параллелизм:** `agents.defaults.subagents.maxConcurrent` (по умолчанию `8`)

## Работоспособность и восстановление

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

После перезапуска Gateway устаревшие восстановленные незавершённые запуски удаляются,
если их дочерняя сессия не помечена как `abortedLastRun: true`. Запуски, прерванные
перезапуском, остаются зарегистрированными для процесса восстановления потерянных
субагентов: устаревшие запуски завершаются без возобновления, а новые дочерние сессии
получают синтетическое сообщение о возобновлении до снятия отметки о прерывании.

Автоматическое восстановление после перезапуска ограничивается для каждой дочерней
сессии. Если один и тот же дочерний субагент неоднократно принимается для восстановления
потерянной задачи в пределах окна быстрого повторного зависания, OpenClaw сохраняет
в этой сессии отметку восстановления и прекращает автоматически возобновлять её при
последующих перезапусках. Запустите `openclaw tasks maintenance --apply`, чтобы согласовать запись задачи,
или `openclaw doctor --fix`, чтобы удалить устаревшие отметки прерванного восстановления
в помеченных сессиях.

> [!NOTE]
>
> Если запуск подагента завершается ошибкой Gateway `PAIRING_REQUIRED` /
> `scope-upgrade`, проверьте вызывающую сторону RPC, прежде чем изменять состояние сопряжения.
> Внутренняя координация `sessions_spawn` выполняет диспетчеризацию внутри процесса, когда
> вызывающая сторона уже работает в контексте запроса Gateway, поэтому она
> не открывает локальный WebSocket и не зависит от базового набора областей доступа
> сопряжённого устройства CLI. Вызывающие стороны вне процесса Gateway по-прежнему используют
> резервный вариант с WebSocket как `client.id: "gateway-client"` с `client.mode: "backend"`
> через прямую локальную аутентификацию с общим токеном или паролем. Удалённым вызывающим сторонам, явным
> `deviceIdentity`, явным путям с токеном устройства и клиентам браузера/Node
> по-прежнему требуется обычное подтверждение устройства для расширения областей доступа.

## Остановка

* Отправка `/stop` в чате инициатора прерывает его сеанс и останавливает все активные запуски подагентов, созданные из него, с каскадной остановкой вложенных дочерних агентов.

## Ограничения

* Уведомление от подагента доставляется **по мере возможности**. Если Gateway перезапустится, ожидающая отправки информация «обратно инициатору» будет потеряна.
* Подагенты по-прежнему совместно используют ресурсы одного процесса Gateway; рассматривайте `maxConcurrent` как предохранительный механизм.
* `sessions_spawn` всегда выполняется без блокировки: он немедленно возвращает `{ status: "accepted", runId, childSessionKey }`.
* В контекст подагента внедряются только `AGENTS.md` и `TOOLS.md` (без `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md`, `HEARTBEAT.md` и `BOOTSTRAP.md`). Нативные подагенты Codex следуют той же границе: `TOOLS.md` сохраняется в унаследованных инструкциях потока Codex, а персона, идентификационные данные и пользовательские файлы, предназначенные только для родителя, внедряются как инструкции по совместной работе в рамках текущего хода, чтобы дочерние агенты не клонировали их.
* Максимальная глубина вложенности — 5 (диапазон `maxSpawnDepth`: 1-5). Для большинства сценариев рекомендуется глубина 2.
* `maxChildrenPerAgent` ограничивает количество активных дочерних агентов на сеанс (по умолчанию `5`, диапазон `1-20`).

## См. также

* [Инструменты сеанса и изменения состояния](https://docs2.openclaw.ai/ru/concepts/session-tool.md)
* [Агенты ACP](https://docs2.openclaw.ai/ru/tools/acp-agents.md)
* [Отправка агенту](https://docs2.openclaw.ai/ru/tools/agent-send.md)
* [Фоновые задачи](https://docs2.openclaw.ai/ru/automation/tasks.md)
* [Инструменты песочницы для нескольких агентов](https://docs2.openclaw.ai/ru/tools/multi-agent-sandbox-tools.md)