> ## Documentation Index > Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt > Use this file to discover all available pages before exploring further. # Субагенты # Субагенты Субагенты — это фоновые запуски агента, создаваемые из уже существующего запуска. Они работают в собственной сессии (`agent::subagent:`) и по завершении **объявляют** свой результат обратно в чат запрашивающей стороны. ## Слеш-команда Используйте `/subagents`, чтобы просматривать и управлять запусками субагентов в **текущей сессии**: * `/subagents list` * `/subagents kill ` * `/subagents log [limit] [tools]` * `/subagents info ` * `/subagents send ` `/subagents info` показывает метаданные запуска (статус, временные метки, id сессии, путь к транскрипту, очистка). Основные цели: * Параллелить «исследование / длительные задачи / медленные инструменты», не блокируя основной запуск. * Держать субагентов изолированными по умолчанию (разделение сессий + опциональная песочница). * Минимизировать риск неправильного использования инструментов: субагенты **не** получают session-инструменты по умолчанию. * Поддерживать настраиваемую глубину вложенности для оркестраторных паттернов. Примечание о стоимости: каждый субагент имеет **собственный** контекст и расход токенов. Для тяжёлых или повторяющихся задач задавайте более дешёвую модель для субагентов, а основной агент оставляйте на более качественной модели. Это настраивается через `agents.defaults.subagents.model` или переопределения на уровне агента. ## Инструмент Используйте `sessions_spawn`: * Запускает субагента (`deliver: false`, глобальная очередь: `subagent`) * Затем выполняет шаг announce и публикует announce-ответ в чат запрашивающей стороны * Модель по умолчанию: наследуется от вызывающего агента, если не задано `agents.defaults.subagents.model` (или `agents.list[].subagents.model`); явный `sessions_spawn.model` имеет приоритет. * Thinking по умолчанию: наследуется от вызывающего агента, если не задано `agents.defaults.subagents.thinking` (или `agents.list[].subagents.thinking`); явный `sessions_spawn.thinking` имеет приоритет. Параметры инструмента: * `task` (обязательно) * `label?` (необязательно) * `agentId?` (необязательно; запустить под другим agent id, если разрешено) * `model?` (необязательно; переопределяет модель субагента; недопустимые значения игнорируются, и субагент запускается на модели по умолчанию с предупреждением в результате инструмента) * `thinking?` (необязательно; переопределяет уровень thinking для запуска субагента) * `runTimeoutSeconds?` (по умолчанию `0`; если задано, запуск субагента будет прерван через N секунд) * `cleanup?` (`delete|keep`, по умолчанию `keep`) Список разрешённых агентов: * `agents.list[].subagents.allowAgents`: список agent id, которые можно указывать через `agentId` (`["*"]` — разрешить любые). По умолчанию: только агент-инициатор. Обнаружение: * Используйте `agents_list`, чтобы увидеть, какие agent id сейчас разрешены для `sessions_spawn`. Автоархивация: * Сессии субагентов автоматически архивируются через `agents.defaults.subagents.archiveAfterMinutes` (по умолчанию: 60). * Архивация использует `sessions.delete` и переименовывает транскрипт в `*.deleted.` (в той же папке). * `cleanup: "delete"` архивирует сразу после announce (транскрипт сохраняется через переименование). * Автоархивация выполняется по принципу best-effort; ожидающие таймеры теряются при перезапуске gateway. * `runTimeoutSeconds` **не** архивирует автоматически; он только останавливает запуск. Сессия остаётся до автоархивации. * Автоархивация одинаково применяется к сессиям глубины 1 и глубины 2. ## Вложенные субагенты По умолчанию субагенты не могут создавать собственных субагентов (`maxSpawnDepth: 1`). Вы можете разрешить один уровень вложенности, установив `maxSpawnDepth: 2`, что позволяет использовать **паттерн оркестратора**: основной → субагент-оркестратор → суб-субагенты-воркеры. ### Как включить ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { defaults: { subagents: { maxSpawnDepth: 2, // разрешить субагентам создавать дочерние (по умолчанию: 1) maxChildrenPerAgent: 5, // макс. активных дочерних на сессию агента (по умолчанию: 5) maxConcurrent: 8, // глобальный лимит конкурентности очереди (по умолчанию: 8) }, }, }, } ``` ### Уровни глубины | Depth | Session key shape | Role | Can spawn? | | ----- | -------------------------------------------- | ---------------------------------- | -------------------------------- | | 0 | `agent::main` | Основной агент | Всегда | | 1 | `agent::subagent:` | Субагент (оркестратор при depth 2) | Только если `maxSpawnDepth >= 2` | | 2 | `agent::subagent::subagent:` | Суб-субагент (воркер) | Никогда | ### Цепочка announce Результаты поднимаются вверх по цепочке: 1. Воркер глубины 2 завершает работу → объявляет родителю (оркестратору глубины 1) 2. Оркестратор глубины 1 получает announce, синтезирует результаты, завершает работу → объявляет основному агенту 3. Основной агент получает announce и доставляет результат пользователю Каждый уровень видит announce только от своих прямых дочерних сессий. ### Политика инструментов по глубине * **Depth 1 (оркестратор, когда `maxSpawnDepth >= 2`)**: получает `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, чтобы управлять дочерними. Остальные session/system-инструменты остаются запрещены. * **Depth 1 (лист, когда `maxSpawnDepth == 1`)**: без session-инструментов (текущее поведение по умолчанию). * **Depth 2 (воркер)**: без session-инструментов — `sessions_spawn` всегда запрещён на глубине 2. Не может создавать дальнейших дочерних. ### Лимит дочерних на агента Каждая сессия агента (на любой глубине) может иметь не более `maxChildrenPerAgent` (по умолчанию: 5) активных дочерних одновременно. Это предотвращает неконтролируемый fan-out от одного оркестратора. ### Каскадная остановка Остановка оркестратора глубины 1 автоматически останавливает всех его дочерних глубины 2: * `/stop` в основном чате останавливает всех агентов глубины 1 и каскадно их дочерних глубины 2. * `/subagents kill ` останавливает конкретного субагента и каскадно его дочерних. * `/subagents kill all` останавливает всех субагентов инициатора и каскадирует остановку. ## Аутентификация Аутентификация субагента определяется по **id агента**, а не по типу сессии: * Ключ сессии субагента — `agent::subagent:`. * Хранилище auth загружается из `agentDir` соответствующего агента. * Профили auth основного агента добавляются как **fallback**; профили агента имеют приоритет при конфликте. Примечание: объединение аддитивное, поэтому профили основного агента всегда доступны как fallback. Полная изоляция auth на уровне агента пока не поддерживается. ## Announce Субагенты отчитываются через шаг announce: * Шаг announce выполняется внутри сессии субагента (не в сессии инициатора). * Если субагент отвечает ровно `ANNOUNCE_SKIP`, ничего не публикуется. * В противном случае announce-ответ публикуется в чат инициатора через follow-up вызов `agent` (`deliver=true`). * Announce-ответы сохраняют маршрутизацию тредов/тем, где это поддерживается (Slack threads, Telegram topics, Matrix threads). * Announce-сообщения нормализуются к стабильному шаблону: * `Status:` определяется по результату выполнения (`success`, `error`, `timeout` или `unknown`). * `Result:` краткое содержание из шага announce (или `(not available)`, если отсутствует). * `Notes:` детали ошибок и полезный контекст. * `Status` не выводится из ответа модели; он определяется сигналами выполнения. Announce-пейлоады включают строку статистики в конце (даже если сообщение обёрнуто): * Время выполнения (например, `runtime 5m12s`) * Расход токенов (input/output/total) * Оценочная стоимость, если настроены цены моделей (`models.providers.*.models[].cost`) * `sessionKey`, `sessionId` и путь к транскрипту (чтобы основной агент мог получить историю через `sessions_history` или открыть файл на диске) ## Политика инструментов (инструменты субагента) По умолчанию субагенты получают **все инструменты, кроме session-инструментов** и системных инструментов: * `sessions_list` * `sessions_history` * `sessions_send` * `sessions_spawn` Когда `maxSpawnDepth >= 2`, субагенты-оркестраторы глубины 1 дополнительно получают `sessions_spawn`, `subagents`, `sessions_list` и `sessions_history`, чтобы управлять своими дочерними. Переопределение через конфигурацию: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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"] }, }, }, } ``` ## Конкурентность Субагенты используют выделенную очередь внутри процесса: * Имя очереди: `subagent` * Конкурентность: `agents.defaults.subagents.maxConcurrent` (по умолчанию `8`) ## Остановка * Отправка `/stop` в чат инициатора прерывает его сессию и останавливает все активные запуски субагентов, созданные из неё, включая вложенных дочерних. * `/subagents kill ` останавливает конкретного субагента и каскадно его дочерних. ## Ограничения * Announce субагента выполняется по принципу **best-effort**. При перезапуске gateway ожидающие announce-задачи теряются. * Субагенты используют те же ресурсы процесса gateway; рассматривайте `maxConcurrent` как предохранитель. * `sessions_spawn` всегда неблокирующий: он немедленно возвращает `{ status: "accepted", runId, childSessionKey }`. * Контекст субагента включает только `AGENTS.md` + `TOOLS.md` (без `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` или `BOOTSTRAP.md`). * Максимальная глубина вложенности — 5 (`maxSpawnDepth` диапазон: 1–5). Для большинства случаев рекомендуется глубина 2. * `maxChildrenPerAgent` ограничивает число активных дочерних на сессию (по умолчанию: 5, диапазон: 1–20).