Субагенты

Субагенты — это фоновые запуски агентов, созданные из существующего запуска агента. Каждый из них работает в собственном сеансе (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 по умолчанию привязывают текущий диалог. Для включения, настройки тайм-аутов и spawnSessions используйте ключи конфигурации threadBindings соответствующего канала.

Краткая схема

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

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

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

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

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

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

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

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

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

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

• Время выполнения (например, 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
• Отправка агенту
• Фоновые задачи
• Инструменты песочницы для нескольких агентов