--- read_when: - Вам нужна фоновая или параллельная работа через агента - Вы изменяете политику инструмента sessions_spawn или субагента - Вы реализуете или устраняете неполадки в сеансах субагентов, привязанных к веткам обсуждения sidebarTitle: Sub-agents summary: Запускайте изолированные фоновые сеансы агентов, которые сообщают результаты в чат инициатора запроса title: Субагенты x-i18n: generated_at: "2026-07-16T16:55:05Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: 8c670d5c7f92d5be8ebce7b1140d9bfd7956b10f38144d275ec84c6af98ae04b source_path: tools/subagents.md workflow: 16 --- Субагенты — это фоновые запуски агентов, порождённые из существующего запуска агента. Каждый из них выполняется в собственном сеансе (`agent::subagent:`) и после завершения **объявляет** свой результат обратно в канал чата запрашивающей стороны. Каждый запуск субагента отслеживается как [фоновая задача](/ru/automation/tasks). Цели: - Распараллеливать исследования, длительные задачи и медленную работу с инструментами, не блокируя основной запуск. - По умолчанию изолировать субагентов (раздельные сеансы, необязательная песочница). - Не допускать неправильного использования набора инструментов: по умолчанию субагенты **не** получают инструменты сеансов или сообщений. - Поддерживать настраиваемую глубину вложенности для шаблонов оркестрации. **Примечание о стоимости:** по умолчанию каждый субагент имеет собственный контекст и расход токенов. Для ресурсоёмких или повторяющихся задач задайте для субагентов более дешёвую модель, а для основного агента оставьте более качественную модель с помощью `agents.defaults.subagents.model` или переопределений для отдельных агентов. Когда дочернему агенту действительно нужна текущая расшифровка диалога запрашивающей стороны, породите его с `context: "fork"`. Для сеансов субагентов, привязанных к ветке обсуждения, по умолчанию используется `context: "fork"`, поскольку они ответвляют текущий разговор в последующую ветку обсуждения. ## Команда с косой чертой `/subagents` позволяет просматривать запуски субагентов для **текущего сеанса**: ```text /subagents list /subagents log [limit] [tools] /subagents info ``` `/subagents info` показывает метаданные запуска (состояние, временные метки, идентификатор сеанса, путь к расшифровке, очистку). `/subagents log` выводит последние реплики чата для запуска; добавьте токен `tools`, чтобы включить сообщения вызовов инструментов и их результатов (по умолчанию они опущены). Используйте `sessions_history` для ограниченного и отфильтрованного с учётом безопасности просмотра контекста из хода агента либо откройте путь к расшифровке на диске, чтобы просмотреть полную необработанную расшифровку. В интерфейсе управления у родительских сеансов с недавними дочерними запусками есть раскрываемая строка на боковой панели. Вложенные строки показывают состояние и время выполнения дочернего запуска, а выбор одной из них открывает чат этого дочернего запуска, сохраняя родительскую иерархию. ### Управление привязкой к ветке обсуждения Эти команды работают в каналах с постоянными привязками к веткам обсуждения. См. [Каналы, поддерживающие ветки обсуждения](#thread-supporting-channels) ниже. ```text /focus /unfocus /agents /session idle /session max-age ``` ### Поведение при порождении Агенты запускают фоновых субагентов с помощью инструмента `sessions_spawn`. Завершения возвращаются как внутренние события родительского сеанса; родительский или запрашивающий агент решает, требуется ли обновление для пользователя. - `sessions_spawn` не блокирует выполнение и немедленно возвращает идентификатор запуска. - После завершения субагент отправляет отчёт в родительский сеанс или сеанс запрашивающей стороны. - Ходы агента, которым нужны результаты дочерних агентов, должны вызывать `sessions_yield` после порождения необходимой работы. Это завершает текущий ход и позволяет событию завершения поступить как следующее видимое модели сообщение. - Завершение работает на основе отправки. После порождения **не** опрашивайте `/subagents list`, `sessions_list` или `sessions_history` в цикле только ради ожидания завершения; проверяйте состояние по запросу лишь при отладке. - Вывод дочернего агента — это отчёт или свидетельства, которые должен обобщить запрашивающий агент. Это не текст инструкций от пользователя, и он не может переопределять системные правила, правила разработчика или пользователя. - После завершения OpenClaw по возможности закрывает отслеживаемые вкладки браузера и процессы, открытые сеансом этого субагента, прежде чем продолжить процесс очистки после объявления. - OpenClaw передаёт завершения обратно в сеанс запрашивающей стороны посредством хода `agent` со стабильным ключом идемпотентности. - Если запуск запрашивающей стороны всё ещё активен, OpenClaw сначала пытается пробудить или направить этот запуск, а не запускать второй видимый путь ответа. - Если активный запуск запрашивающей стороны невозможно пробудить, OpenClaw вместо отбрасывания объявления выполняет передачу агенту запрашивающей стороны с тем же контекстом завершения. - Успешная передача родительскому агенту завершает доставку результата субагента, даже если родитель решает, что видимое пользователю обновление не требуется. - Нативные субагенты не получают инструмент сообщений. Они возвращают обычный текст ассистента родительскому или запрашивающему агенту; видимые человеку ответы по-прежнему регулируются обычной политикой доставки родительского или запрашивающего агента. - Если прямую передачу использовать невозможно, доставка переключается на маршрутизацию через очередь, а затем на короткие повторные попытки объявления с экспоненциальной задержкой перед окончательным отказом. - Доставка сохраняет определённый маршрут запрашивающей стороны: при наличии приоритет имеют маршруты завершения, привязанные к ветке обсуждения или разговору. Если источник завершения предоставляет только канал, OpenClaw заполняет отсутствующие цель или учётную запись из определённого маршрута сеанса запрашивающей стороны (`lastChannel` / `lastTo` / `lastAccountId`), чтобы прямая доставка по-прежнему работала. Передача завершения в сеанс запрашивающей стороны представляет собой создаваемый средой выполнения внутренний контекст (а не текст пользователя) и включает: - `Result` — текст последнего видимого ответа `assistant` от дочернего агента. Вывод tool/toolResult не включается в результаты дочернего агента. Окончательно завершившиеся с ошибкой запуски не используют повторно сохранённый текст ответа. - `Status` — `completed; ready for parent review` / `failed` / `timed out` / `unknown`. - Краткую статистику среды выполнения и токенов. - Инструкцию по проверке, предписывающую запрашивающему агенту проверить результат, прежде чем решать, выполнена ли исходная задача. - Указание по дальнейшим действиям, предписывающее запрашивающему агенту продолжить задачу или зафиксировать последующую задачу, если результат дочернего агента требует дополнительных действий. - Инструкцию по окончательному обновлению для случая, когда дополнительных действий не требуется, сформулированную обычным голосом ассистента без передачи необработанных внутренних метаданных. - `--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](/ru/tools/acp-agents#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 { agents: { defaults: { subagents: { delegationMode: "prefer", maxConcurrent: 4, }, }, list: [ { id: "coordinator", subagents: { delegationMode: "prefer" }, }, ], }, } ``` ### Параметры инструмента Описание задачи для субагента. Необязательный стабильный идентификатор для распознавания конкретного дочернего агента в последующем выводе состояния. Должен соответствовать `[a-z][a-z0-9_-]{0,63}` и не может быть зарезервированной целью, такой как `last` или `all`. Необязательная удобочитаемая метка. Запускает процесс под другим настроенным идентификатором агента, если это разрешено параметром `subagents.allowAgents`. Необязательный рабочий каталог задачи для дочернего запуска. Нативные субагенты по-прежнему загружают файлы начальной настройки из рабочего пространства целевого агента; `cwd` изменяет только место, где инструменты среды выполнения и CLI-обвязки выполняют делегированную работу. `acp` предназначен только для внешних обвязок ACP (`claude`, `droid`, `gemini`, `opencode` или явно запрошенных Codex ACP/acpx), а также для записей `agents.list[]`, у которых `runtime.type` имеет значение `acp`. Только для ACP. Возобновляет существующий сеанс обвязки ACP, когда `runtime: "acp"`; игнорируется при запуске нативных субагентов. Только для ACP. Передаёт потоковый вывод запуска ACP родительскому сеансу, когда `runtime: "acp"`; не указывайте при запуске нативных субагентов. Переопределяет модель субагента. Недопустимые значения пропускаются, а субагент запускается на модели по умолчанию с предупреждением в результате инструмента. Переопределяет уровень рассуждений для запуска субагента. Когда `true`, запрашивает привязку к ветке канала для этого сеанса субагента. Если `thread: true` и `mode` не указан, значением по умолчанию становится `session`. `mode: "session"` требует `thread: true`. Если привязка к ветке недоступна для канала запрашивающей стороны, используйте вместо неё `mode: "run"`. `"delete"` архивирует сеанс сразу после объявления (расшифровка всё равно сохраняется посредством переименования). `require` отклоняет запуск, если целевая среда выполнения дочернего агента не изолирована в песочнице. `fork` ответвляет текущую расшифровку запрашивающей стороны в дочерний сеанс. Только для нативных субагентов. Для запусков с привязкой к ветке по умолчанию используется `fork`; для запусков без привязки — `isolated`. `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`. ### Краткая последовательность `sessions_spawn` с `thread: true` (и при необходимости `mode: "session"`). OpenClaw создаёт или привязывает ветку к цели этого сеанса в активном канале. Ответы и последующие сообщения в этой ветке направляются в привязанный сеанс. Используйте `/session idle`, чтобы проверить или изменить автоматическое снятие фокуса при бездействии, и `/session max-age`, чтобы управлять жёстким ограничением. Используйте `/unfocus`, чтобы отсоединить вручную. ### Ручное управление | Команда | Результат | | ------------------ | ----------------------------------------------------------------------------------------- | | `/focus ` | Привязать текущую ветку (или создать её) к цели субагента/сеанса | | `/unfocus` | Удалить привязку для текущей привязанной ветки | | `/agents` | Вывести активные запуски и состояние привязки (`binding:`, `unbound` или `bindings unavailable`) | | `/session idle` | Проверить или изменить автоматическое снятие фокуса при бездействии (только для привязанных веток в фокусе) | | `/session max-age` | Проверить или изменить жёсткое ограничение (только для привязанных веток в фокусе) | ### Параметры конфигурации - **Глобальные значения по умолчанию:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - **Ключи переопределения для канала и автоматической привязки при запуске** зависят от адаптера. См. раздел [Каналы, поддерживающие ветки](#thread-supporting-channels) выше. Актуальные сведения об адаптерах см. в разделах [Справочник по конфигурации](/ru/gateway/configuration-reference) и [Команды с косой чертой](/ru/tools/slash-commands). ### Список разрешённых агентов Список идентификаторов настроенных агентов, которые можно выбрать через явно заданный `agentId` (`["*"]` разрешает любую настроенную цель). По умолчанию: только запрашивающий агент. Если задан список и запрашивающему агенту всё ещё требуется запускать самого себя с помощью `agentId`, включите идентификатор запрашивающего агента в список. Список разрешённых целевых настроенных агентов по умолчанию, используемый, когда запрашивающий агент не задаёт собственный `subagents.allowAgents`. Блокирует вызовы `sessions_spawn`, в которых не указан `agentId` (требует явного выбора профиля). Переопределение для отдельного агента: `agents.list[].subagents.requireAgentId`. Тайм-аут отдельного вызова для попыток доставки объявления 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.` (в той же папке). - `cleanup: "delete"` архивирует сеанс сразу после объявления (расшифровка всё равно сохраняется посредством переименования). - Автоматическое архивирование выполняется по возможности; ожидающие таймеры теряются при перезапуске Gateway. - Настроенные тайм-ауты запуска **не** выполняют автоматическое архивирование; они только останавливают запуск. Сеанс сохраняется до автоматического архивирования. - Автоматическое архивирование одинаково применяется к сеансам глубины 1 и глубины 2. - Очистка браузера выполняется отдельно от очистки архива: отслеживаемые вкладки и процессы браузера по возможности закрываются после завершения запуска, даже если расшифровка или запись сеанса сохраняется. ## Вложенные субагенты По умолчанию субагенты не могут запускать собственных субагентов (`maxSpawnDepth: 1`). Установите `maxSpawnDepth: 2`, чтобы разрешить один уровень вложенности — **шаблон оркестратора**: основной агент → субагент-оркестратор → рабочие субсубагенты. ```json5 { 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::main` | Главный агент | Всегда | | 1 | `agent::subagent:` | Субагент (оркестратор, если разрешена глубина 2) | Только если `maxSpawnDepth >= 2` | | 2 | `agent::subagent::subagent:` | Суб-субагент (конечный исполнитель) | Никогда | ### Цепочка уведомлений Результаты передаются вверх по цепочке: 1. Исполнитель глубины 2 завершает работу → уведомляет своего родителя (оркестратора глубины 1). 2. Оркестратор глубины 1 получает уведомление, обобщает результаты, завершает работу → уведомляет главного агента. 3. Главный агент получает уведомление и передаёт результат пользователю. Каждый уровень видит только уведомления от своих непосредственных дочерних агентов. **Рекомендации по эксплуатации:** запускайте дочернюю задачу один раз и ожидайте событий завершения, вместо того чтобы строить циклы опроса вокруг `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::subagent:`. - Хранилище данных аутентификации загружается из `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` **не** удаляет теги рассуждений, служебную структуру `` или 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 { 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 { 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`, чтобы удалить устаревшие отметки прерванного восстановления в помеченных сессиях. Если запуск подагента завершается ошибкой 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`). ## См. также - [Инструменты сеанса и изменения состояния](/ru/concepts/session-tool) - [Агенты ACP](/ru/tools/acp-agents) - [Отправка агенту](/ru/tools/agent-send) - [Фоновые задачи](/ru/automation/tasks) - [Инструменты песочницы для нескольких агентов](/ru/tools/multi-agent-sandbox-tools)