Субагенты

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

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

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

Slash-команда

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

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

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

Элементы управления привязкой тредов

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

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

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

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

Non-blocking, push-based completion

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

Completion delivery

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

Completion handoff metadata

Передача завершения в сеанс инициатора — это сгенерированный средой выполнения внутренний контекст (не пользовательский текст), который включает:

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

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 при отладке завершений или циклов агент-агент. Когда 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.

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

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

Режим	Когда его использовать	Поведение
`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.

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

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

task

string

обязательно

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

taskName

string

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

label

string

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

agentId

string

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

cwd

string

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

runtime

"subagent" | "acp"

по умолчанию:"subagent"

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

resumeSessionId

string

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

streamTo

"parent"

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

model

string

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

thinking

string

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

thread

boolean

по умолчанию:"false"

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

mode

"run" | "session"

по умолчанию:"run"

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

cleanup

"delete" | "keep"

по умолчанию:"keep"

"delete" архивирует сразу после объявления (при этом транскрипт сохраняется через переименование).

sandbox

"inherit" | "require"

по умолчанию:"inherit"

require отклоняет запуск, если целевой дочерний runtime не изолирован в sandbox.

context

"isolated" | "fork"

по умолчанию:"isolated"

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

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

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

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.

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

Запуск

sessions_spawn с thread: true (и необязательно mode: "session").

Привязка

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

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

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

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

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

Отсоединение

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

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

Команда	Эффект
`/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 выше.

См. Справочник по конфигурации и Slash-команды для текущих сведений об адаптерах.

Список разрешений

agents.list[].subagents.allowAgents

string[]

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

agents.defaults.subagents.allowAgents

string[]

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

agents.defaults.subagents.requireAgentId

boolean

по умолчанию:"false"

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

agents.defaults.subagents.announceTimeoutMs

number

по умолчанию:"120000"

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

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

{
  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)	Никогда

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

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

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

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

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

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

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

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

{
  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 на этапе профиля:

{
  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-сессиях.

Если 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.

Остановка

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

​Slash-команда

​Элементы управления привязкой тредов

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

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

​Инструмент: sessions_spawn

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

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

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

​Инструмент: sessions_yield

​Инструмент: subagents

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

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

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

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

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

​Список разрешений

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

​Автоархивация

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

​Остановка

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

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

Slash-команда

Элементы управления привязкой тредов

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

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

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

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

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

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

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

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

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

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

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

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

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

Список разрешений

Обнаружение

Автоархивация

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

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

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

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

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

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

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

Уведомление

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

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

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

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

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

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

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

Остановка

Ограничения

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