Субагенты

Субагенты — это фоновые запуски агентов, порождённые из существующего запуска агента. Каждый из них выполняется в собственном сеансе (agent:<agentId>:subagent:<uuid>) и после завершения объявляет свой результат обратно в канал чата запрашивающей стороны. Каждый запуск субагента отслеживается как фоновая задача.

Цели:

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

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

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

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

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

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

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

Эти команды работают в каналах с постоянными привязками к веткам обсуждения. См. Каналы, поддерживающие ветки обсуждения ниже.

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

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

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

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

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

Используйте 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.

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

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

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

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.

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

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

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

• Глобальные значения по умолчанию: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Ключи переопределения для канала и автоматической привязки при запуске зависят от адаптера. См. раздел Каналы, поддерживающие ветки выше.

Актуальные сведения об адаптерах см. в разделах Справочник по конфигурации и Команды с косой чертой.

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

Если запрашивающий сеанс изолирован в песочнице, 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, чтобы разрешить один уровень вложенности — шаблон оркестратора: основной агент → субагент-оркестратор → рабочие субсубагенты.

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

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

Цепочка уведомлений

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

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

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

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

• Роль и область управления записываются в метаданные сессии при порождении. Это не позволяет плоским или восстановленным ключам сессий случайно вернуть привилегии оркестратора.
• Глубина 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 по возможности возвращается к инициатору этой сессии.

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

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

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

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

Завершившиеся с ошибкой запуски сообщают состояние ошибки без повторного воспроизведения захваченного текста ответа. Вывод 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, чтобы управлять своими дочерними агентами.

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

{  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. Чтобы разрешить субагентам с профилем программирования использовать автоматизацию браузера, добавьте браузер на этапе профиля:

{  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, чтобы удалить устаревшие отметки прерванного восстановления в помеченных сессиях.

Остановка

• Отправка /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).

См. также

• Инструменты сеанса и изменения состояния
• Агенты ACP
• Отправка агенту
• Фоновые задачи
• Инструменты песочницы для нескольких агентов