---
read_when:
    - Вам нужна фоновая или параллельная работа через агента
    - Вы меняете `sessions_spawn` или политику инструмента субагентов
    - Вы реализуете или устраняете неполадки сеансов подагентов, привязанных к потоку
sidebarTitle: Sub-agents
summary: Создавайте изолированные фоновые запуски агента, которые сообщают результаты обратно в чат инициатора запроса
title: Субагенты
x-i18n:
    generated_at: "2026-06-28T23:55:33Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 144af6e020c86d171fe6c5734efaad229adaea35f8d1c1b07e37c549805c88ff
    source_path: tools/subagents.md
    workflow: 16
---

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

Основные цели:

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

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

## Slash-команда

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

```text
/subagents list
/subagents log <id|#> [limit] [tools]
/subagents info <id|#>
```

`/subagents info` показывает метаданные запуска (статус, временные метки, идентификатор сеанса,
путь к расшифровке, очистку). Используйте `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>
```

### Поведение запуска

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

<AccordionGroup>
  <Accordion title="Non-blocking, push-based completion">
    - `sessions_spawn` не блокирует выполнение; она сразу возвращает идентификатор запуска.
    - При завершении субагент сообщает результат родительскому сеансу или сеансу инициатора.
    - Ходы агента, которым нужны результаты дочерних агентов, должны вызывать `sessions_yield` после запуска требуемой работы. Это завершает текущий ход и позволяет событиям завершения прийти как следующее сообщение, видимое модели.
    - Завершение работает по push-модели. После запуска **не** опрашивайте `/subagents list`, `sessions_list` или `sessions_history` в цикле только для ожидания завершения; проверяйте статус только по требованию для отладочной видимости.
    - Вывод дочернего агента — это отчет или доказательства для агента-инициатора, который должен их синтезировать. Это не пользовательские инструкции и он не может переопределять системную, разработческую или пользовательскую политику.
    - При завершении OpenClaw по возможности закрывает отслеживаемые вкладки браузера и процессы, открытые этим сеансом субагента, до продолжения потока очистки объявления.

  </Accordion>
  <Accordion title="Completion delivery">
    - OpenClaw передает завершения обратно в сеанс инициатора через ход `agent` со стабильным ключом идемпотентности.
    - Если запуск инициатора все еще активен, OpenClaw сначала пытается разбудить или направить этот запуск вместо создания второго видимого пути ответа.
    - Если активного инициатора нельзя разбудить, OpenClaw переключается на передачу агенту-инициатору с тем же контекстом завершения вместо того, чтобы отбросить объявление.
    - Успешная передача родителю завершает доставку субагента, даже если родитель решает, что видимое пользователю обновление не нужно.
    - Нативные субагенты не получают инструмент сообщений. Они возвращают обычный текст ассистента родительскому агенту или агенту-инициатору; ответы, видимые человеку, принадлежат обычной политике доставки родительского агента или агента-инициатора.
    - Если прямую передачу использовать нельзя, выполняется откат к маршрутизации через очередь.
    - Если маршрутизация через очередь все еще недоступна, объявление повторяется с коротким экспоненциальным backoff до окончательного отказа.
    - Доставка завершения сохраняет разрешенный маршрут инициатора: маршруты завершения, привязанные к треду или разговору, имеют приоритет, когда доступны; если источник завершения предоставляет только канал, OpenClaw заполняет отсутствующую цель/учетную запись из разрешенного маршрута сеанса инициатора (`lastChannel` / `lastTo` / `lastAccountId`), чтобы прямая доставка продолжала работать.

  </Accordion>
  <Accordion title="Completion handoff metadata">
    Передача завершения в сеанс инициатора — это сгенерированный средой выполнения
    внутренний контекст (не пользовательский текст), который включает:

    - `Result` — последний видимый текст ответа `assistant` от дочернего агента. Вывод tool/toolResult не продвигается в результаты дочернего агента. Терминально неудачные запуски не переиспользуют захваченный текст ответа.
    - `Status` — `completed; ready for parent review` / `failed` / `timed out` / `unknown`.
    - Компактную статистику среды выполнения/токенов.
    - Инструкцию проверки, которая говорит агенту-инициатору проверить результат перед решением, выполнена ли исходная задача.
    - Последующие указания, которые говорят агенту-инициатору продолжить задачу или записать последующее действие, когда результат дочернего агента оставляет необходимость дополнительных действий.
    - Инструкцию финального обновления для пути без дальнейших действий, написанную обычным голосом ассистента без пересылки необработанных внутренних метаданных.

  </Accordion>
  <Accordion title="Modes and ACP runtime">
    - `--model` и `--thinking` переопределяют значения по умолчанию для этого конкретного запуска.
    - Используйте `info`/`log`, чтобы просмотреть подробности и вывод после завершения.
    - Для постоянных сеансов, привязанных к треду, используйте `sessions_spawn` с `thread: true` и `mode: "session"`.
    - Если канал инициатора не поддерживает привязки тредов, используйте `mode: "run"` вместо повторных попыток невозможных комбинаций с привязкой к треду.
    - Для сеансов ACP-harness (Claude Code, Gemini CLI, OpenCode или явные Codex ACP/acpx) используйте `sessions_spawn` с `runtime: "acp"`, когда инструмент объявляет такую среду выполнения. См. [модель доставки ACP](/ru/tools/acp-agents#delivery-model) при отладке завершений или циклов агент-агент. Когда Plugin `codex` включен, управление чатом/тредом Codex должно предпочитать `/codex ...` вместо ACP, если пользователь явно не просит ACP/acpx.
    - OpenClaw скрывает `runtime: "acp"`, пока ACP не включен, инициатор не находится в песочнице и загружен backend-Plugin, например `acpx`. `runtime: "acp"` ожидает внешний идентификатор ACP-harness или запись `agents.list[]` с `runtime.type="acp"`; используйте стандартную среду выполнения субагента для обычных агентов конфигурации 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"` для агентов, которые должны делегировать
работу. Политики канала/группы, провайдера, песочницы и allow/deny для отдельного агента
все еще могут удалить инструмент после этапа профиля. Используйте `/tools` из того же
сеанса, чтобы подтвердить эффективный список инструментов.

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

- **Модель:** нативные субагенты наследуют вызывающую сторону, если вы не задали `agents.defaults.subagents.model` (или `agents.list[].subagents.model` для отдельного агента). Запуски среды выполнения ACP используют ту же настроенную модель субагента, когда она есть; иначе ACP-harness сохраняет собственное значение по умолчанию. Явное `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]`. Системный prompt субагента содержит правила среды выполнения и контекст маршрутизации, а не скрытый дубликат задачи.

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

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

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

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

Переопределения для отдельных агентов используют `agents.list[].subagents.delegationMode`.

```json5
{
  agents: {
    defaults: {
      subagents: {
        delegationMode: "prefer",
        maxConcurrent: 4,
      },
    },
    list: [
      {
        id: "coordinator",
        subagents: { delegationMode: "prefer" },
      },
    ],
  },
}
```

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

<ParamField path="task" type="string" required>
  Описание задачи для субагента.
</ParamField>
<ParamField path="taskName" type="string">
  Необязательный стабильный идентификатор для распознавания конкретного дочернего агента в последующем выводе статуса. Должен соответствовать `[a-z][a-z0-9_-]{0,63}` и не может быть зарезервированной целью, такой как `last` или `all`.
</ParamField>
<ParamField path="label" type="string">
  Необязательная человекочитаемая метка.
</ParamField>
<ParamField path="agentId" type="string">
  Запуск под другим настроенным идентификатором агента, когда это разрешено `subagents.allowAgents`.
</ParamField>
<ParamField path="cwd" type="string">
  Необязательный рабочий каталог задачи для дочернего запуска. Нативные субагенты по-прежнему загружают bootstrap-файлы из рабочей области целевого агента; `cwd` меняет только место, где runtime-инструменты и CLI-обвязки выполняют делегированную работу.
</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">
  Переопределяет уровень reasoning для запуска субагента.
</ParamField>
<ParamField path="thread" type="boolean" default="false">
  Когда `true`, запрашивает привязку к thread канала для этой сессии субагента.
</ParamField>
<ParamField path="mode" type='"run" | "session"' default="run">
  Если `thread: true` и `mode` опущен, значением по умолчанию становится `session`. `mode: "session"` требует `thread: true`.
  Если привязка к thread недоступна для канала запрашивающей стороны, вместо этого используйте `mode: "run"`.
</ParamField>
<ParamField path="cleanup" type='"delete" | "keep"' default="keep">
  `"delete"` архивирует сразу после объявления (при этом транскрипт сохраняется через переименование).
</ParamField>
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
  `require` отклоняет запуск, если целевой дочерний runtime не изолирован в sandbox.
</ParamField>
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
  `fork` ответвляет текущий транскрипт запрашивающей стороны в дочернюю сессию. Только нативные субагенты. Запуски с привязкой к thread по умолчанию используют `fork`; запуски без thread по умолчанию используют `isolated`.
</ParamField>

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

### Имена задач и адресация целей

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

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

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

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

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

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

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

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

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

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

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

## Сессии с привязкой к thread

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

### Каналы с поддержкой thread

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

### Быстрый поток

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

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

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

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

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

См. [Справочник по конфигурации](/ru/gateway/configuration-reference) и
[Slash-команды](/ru/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>
<ParamField path="agents.defaults.subagents.announceTimeoutMs" type="number" default="120000">
  Тайм-аут на один вызов для попыток доставки объявления gateway `agent`. Значения — положительные целые миллисекунды и ограничиваются безопасным для платформы максимумом таймера. Временные повторные попытки могут сделать общее ожидание объявления длиннее одного настроенного тайм-аута.
</ParamField>

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

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

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

Записи `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
{
  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 (0 = no timeout)
        announceTimeoutMs: 120000, // per-call gateway announce timeout
      },
    },
  },
}
```

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

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

### Цепочка объявлений

Результаты передаются обратно вверх по цепочке:

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

Каждый уровень видит только уведомления от своих непосредственных дочерних элементов.

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

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

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

### Лимит spawn на агента

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

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

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

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

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

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

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

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

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

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

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

Доставка зависит от глубины запрашивающего:

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

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

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

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

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

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

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

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

Payload уведомлений включает строку статистики в конце (даже при переносе):

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

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

### Почему предпочитать `sessions_history`

`sessions_history` — более безопасный путь оркестрации:

- Воспоминания assistant сначала нормализуются: thinking-теги удаляются; scaffolding `<relevant-memories>` / `<relevant_memories>` удаляется; plain-text XML-блоки payload вызовов инструментов (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`) удаляются, включая усеченные payload, которые никогда корректно не закрываются; пониженный scaffolding вызовов/результатов инструментов и маркеры historical-context удаляются; просочившиеся управляющие токены модели (`<|assistant|>`, другие ASCII `<|...|>`, полноширинные `<｜...｜>`) удаляются; malformed MiniMax tool-call XML удаляется.
- Текст, похожий на учетные данные/токены, редактируется.
- Длинные блоки могут быть усечены.
- Очень большие истории могут отбрасывать старые строки или заменять чрезмерно большую строку на `[sessions_history omitted: message too large]`.
- Используйте `nextOffset`, когда он присутствует, чтобы перелистывать назад более старые окна transcript.
- Проверка raw transcript на диске — fallback, когда нужен полный transcript byte-for-byte.

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

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

Без ограничивающего `tools.profile` субагенты получают **все инструменты, кроме
инструмента сообщений, инструментов сессий и системных инструментов**:

- `sessions_list`
- `sessions_history`
- `sessions_send`
- `sessions_spawn`
- `message`

`sessions_history` и здесь остается ограниченным, санитизированным представлением recall —
это не raw dump transcript.

Когда `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"]` на уровне агента, когда только один
агент должен получать автоматизацию браузера.

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

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

- **Имя lane:** `subagent`
- **Конкурентность:** `agents.defaults.subagents.maxConcurrent` (по умолчанию `8`)

## Живучесть и восстановление

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

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

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

<Note>
Если spawn субагента завершается с ошибкой Gateway `PAIRING_REQUIRED` /
`scope-upgrade`, проверьте вызывающего RPC перед редактированием состояния pairing.
Внутренняя координация `sessions_spawn` dispatch выполняется внутри процесса, когда
вызывающий уже работает в контексте gateway request, поэтому она не
открывает loopback WebSocket и не зависит от baseline paired-device scope
в CLI. Вызывающие вне процесса gateway все еще используют WebSocket
fallback как `client.id: "gateway-client"` с `client.mode: "backend"`
через direct loopback shared-token/password auth. Удаленные вызывающие, явные
`deviceIdentity`, явные пути device-token и browser/node клиенты
все еще требуют обычного одобрения устройства для scope upgrades.
</Note>

## Остановка

- Отправка `/stop` в чате запрашивающего прерывает сессию запрашивающего и останавливает все активные запуски субагентов, порожденные из нее, с каскадом на вложенные дочерние элементы.

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

- Уведомление субагента выполняется по принципу **best-effort**. Если gateway перезапускается, ожидающая работа "announce back" теряется.
- Субагенты все еще разделяют ресурсы того же процесса gateway; рассматривайте `maxConcurrent` как предохранительный клапан.
- `sessions_spawn` всегда неблокирующий: он немедленно возвращает `{ status: "accepted", runId, childSessionKey }`.
- Контекст субагента инжектирует только `AGENTS.md` и `TOOLS.md` (без `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md`, `HEARTBEAT.md` или `BOOTSTRAP.md`). Codex-native subagents следуют той же границе: `TOOLS.md` остается в унаследованных инструкциях Codex thread, а файлы persona, identity и user только родителя инжектируются как turn-scoped collaboration instructions, чтобы дочерние элементы их не клонировали.
- Максимальная глубина вложенности — 5 (диапазон `maxSpawnDepth`: 1–5). Глубина 2 рекомендуется для большинства вариантов использования.
- `maxChildrenPerAgent` ограничивает активные дочерние элементы на сессию (по умолчанию `5`, диапазон `1–20`).

## Связанные материалы

- [Агенты ACP](/ru/tools/acp-agents)
- [Отправка агенту](/ru/tools/agent-send)
- [Фоновые задачи](/ru/automation/tasks)
- [Инструменты multi-agent sandbox](/ru/tools/multi-agent-sandbox-tools)