Координация агентов

Суб-агенты

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

Слеш-команда

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

  • /subagents list
  • /subagents kill <id|#|all>
  • /subagents log <id|#> [limit] [tools]
  • /subagents info <id|#>
  • /subagents send <id|#> <message>
  • /subagents steer <id|#> <message>
  • /subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]

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

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

/subagents info показывает метаданные запуска (статус, временные метки, идентификатор сессии, путь к транскрипту, очистка).

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

/subagents spawn запускает фонового суб-агента как пользовательскую команду, а не как внутреннюю ретрансляцию, и отправляет одно финальное обновление о завершении обратно в чат инициатора, когда запуск завершается.

  • Команда spawn неблокирующая; она немедленно возвращает идентификатор запуска.
  • По завершении суб-агент объявляет сводное сообщение/результат обратно в канал чата инициатора.
  • Для ручных запусков доставка устойчива:
    • OpenClaw сначала пытается выполнить прямую доставку agent со стабильным ключом идемпотентности.
    • Если прямая доставка не удается, происходит откат на маршрутизацию через очередь.
    • Если маршрутизация через очередь также недоступна, объявление повторяется с короткой экспоненциальной задержкой перед окончательным отказом.
  • Передача завершения в сессию инициатора — это сгенерированный во время выполнения внутренний контекст (не текст, написанный пользователем) и включает:
    • Result (текст ответа assistant или последний toolResult, если ответ помощника пуст)
    • Status (completed successfully / failed / timed out / unknown)
    • компактную статистику времени выполнения/токенов
    • инструкцию по доставке, предписывающую агенту-инициатору переписать результат обычным голосом помощника (а не пересылать сырые внутренние метаданные)
  • --model и --thinking переопределяют значения по умолчанию для этого конкретного запуска.
  • Используйте info/log для проверки деталей и вывода после завершения.
  • /subagents spawn — это одноразовый режим (mode: "run"). Для постоянных сессий, привязанных к тредам, используйте sessions_spawn с thread: true и mode: "session".
  • Для сессий ACP harness (Codex, Claude Code, Gemini CLI) используйте sessions_spawn с runtime: "acp" и см. ACP Agents.

Основные цели:

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

Примечание по стоимости: каждый суб-агент имеет свой собственный контекст и использование токенов. Для тяжелых или повторяющихся задач установите более дешевую модель для суб-агентов, а основного агента оставьте на более качественной модели. Это можно настроить через agents.defaults.subagents.model или переопределения для каждого агента.

Инструмент

Используйте sessions_spawn:

  • Запускает запуск суб-агента (deliver: false, глобальная очередь: subagent)
  • Затем выполняет шаг объявления и публикует ответ с объявлением в канал чата инициатора
  • Модель по умолчанию: наследует от вызывающей стороны, если вы не установите agents.defaults.subagents.model (или agents.list[].subagents.model для каждого агента); явный sessions_spawn.model все равно имеет приоритет.
  • Уровень мышления по умолчанию: наследует от вызывающей стороны, если вы не установите agents.defaults.subagents.thinking (или agents.list[].subagents.thinking для каждого агента); явный sessions_spawn.thinking все равно имеет приоритет.
  • Таймаут запуска по умолчанию: если sessions_spawn.runTimeoutSeconds опущен, OpenClaw использует agents.defaults.subagents.runTimeoutSeconds, когда он установлен; в противном случае происходит откат к 0 (без таймаута).

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

  • task (обязательный)
  • label? (опционально)
  • agentId? (опционально; породить под другим идентификатором агента, если разрешено)
  • model? (опционально; переопределяет модель суб-агента; недопустимые значения пропускаются, и суб-агент запускается на модели по умолчанию с предупреждением в результате инструмента)
  • thinking? (опционально; переопределяет уровень мышления для запуска суб-агента)
  • runTimeoutSeconds? (по умолчанию agents.defaults.subagents.runTimeoutSeconds, когда установлен, иначе 0; когда установлен, запуск суб-агента прерывается через N секунд)
  • thread? (по умолчанию false; когда true, запрашивает привязку треда канала для этой сессии суб-агента)
  • mode? (run|session)
    • по умолчанию run
    • если thread: true и mode опущен, по умолчанию становится session
    • mode: "session" требует thread: true
  • cleanup? (delete|keep, по умолчанию keep)
  • sandbox? (inherit|require, по умолчанию inherit; require отклоняет порождение, если целевая дочерняя среда выполнения не изолирована)
  • sessions_spawn не принимает параметры доставки в канал (target, channel, to, threadId, replyTo, transport). Для доставки используйте message/sessions_send из порожденного запуска.

Сессии, привязанные к тредам

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

Каналы, поддерживающие треды

  • Discord (в настоящее время единственный поддерживаемый канал): поддерживает постоянные сессии суб-агентов, привязанные к тредам (sessions_spawn с thread: true), ручное управление тредами (/focus, /unfocus, /agents, /session idle, /session max-age), а также ключи адаптера channels.discord.threadBindings.enabled, channels.discord.threadBindings.idleHours, channels.discord.threadBindings.maxAgeHours и channels.discord.threadBindings.spawnSubagentSessions.

Быстрый процесс:

  1. Породите с помощью sessions_spawn, используя thread: true (и опционально mode: "session").
  2. OpenClaw создает или привязывает тред к этой целевой сессии в активном канале.
  3. Ответы и последующие сообщения в этом треде маршрутизируются в привязанную сессию.
  4. Используйте /session idle для проверки/обновления автоматической отвязки при бездействии и /session max-age для контроля жесткого ограничения по времени.
  5. Используйте /unfocus для ручной отвязки.

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

  • /focus <target> привязывает текущий тред (или создает его) к цели суб-агента/сессии.
  • /unfocus удаляет привязку для текущего привязанного треда.
  • /agents выводит список активных запусков и состояние привязки (thread:<id> или unbound).
  • /session idle и /session max-age работают только для сфокусированных привязанных тредов.

Конфигурационные переключатели:

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

См. Справочник по конфигурации и Слеш-команды для получения актуальных деталей по адаптерам. Белый список:

  • agents.list[].subagents.allowAgents: список идентификаторов агентов, которые могут быть указаны в agentId (["*"] для разрешения любых). По умолчанию: только агент-инициатор.
  • Защита наследования песочницы: если сессия инициатора изолирована, sessions_spawn отклоняет цели, которые будут выполняться вне песочницы.

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

  • Используйте agents_list, чтобы увидеть, какие идентификаторы агентов в настоящее время разрешены для sessions_spawn.

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

  • Сессии суб-агентов автоматически архивируются после agents.defaults.subagents.archiveAfterMinutes (по умолчанию: 60).
  • Архивация использует sessions.delete и переименовывает транскрипт в *.deleted.<timestamp> (та же папка).
  • cleanup: "delete" архивирует сразу после объявления (все равно сохраняет транскрипт через переименование).
  • Автоархивация выполняется по принципу best-effort; ожидающие таймеры теряются при перезапуске шлюза.
  • runTimeoutSeconds не выполняет автоархивацию; он только останавливает запуск. Сессия остается до автоархивации.
  • Автоархивация применяется одинаково к сессиям глубины 1 и глубины 2.

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

По умолчанию суб-агенты не могут порождать своих собственных суб-агентов (maxSpawnDepth: 1). Вы можете включить один уровень вложенности, установив maxSpawnDepth: 2, что позволяет использовать паттерн оркестратора: основной → суб-агент оркестратор → суб-суб-агенты рабочие.

Как включить

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

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

ГлубинаФормат ключа сессииРольМожет порождать?
0agent:<id>:mainОсновной агентВсегда
1agent:<id>:subagent:<uuid>Суб-агент (оркестратор, когда разрешена глубина 2)Только если maxSpawnDepth >= 2
2agent:<id>:subagent:<uuid>:subagent:<uuid>Суб-суб-агент (конечный рабочий)Никогда

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

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

  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.
  • /subagents kill <id> останавливает конкретного суб-агента и каскадно распространяется на его дочерних элементов.
  • /subagents kill all останавливает всех суб-агентов для инициатора и каскадно распространяется.

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

Аутентификация суб-агента определяется по идентификатору агента, а не по типу сессии:

  • Ключ сессии суб-агента: agent:<agentId>:subagent:<uuid>.
  • Хранилище аутентификации загружается из agentDir этого агента.
  • Профили аутентификации основного агента добавляются в качестве резервного варианта; профили агента переопределяют профили основного агента при конфликтах.

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

Объявление

Суб-агенты отчитываются через шаг объявления:

  • Шаг объявления выполняется внутри сессии суб-агента (а не сессии инициатора).
  • Если суб-агент отвечает точно ANNOUNCE_SKIP, ничего не публикуется.
  • В противном случае доставка зависит от глубины инициатора:
    • сессии инициатора верхнего уровня используют последующий вызов agent с внешней доставкой (deliver=true)
    • вложенные сессии суб-агента инициатора получают внутреннюю последующую инъекцию (deliver=false), чтобы оркестратор мог синтезировать результаты дочерних элементов внутри сессии
    • если вложенная сессия суб-агента инициатора отсутствует, OpenClaw возвращается к инициатору этой сессии, когда это возможно
  • Агрегация завершения дочерних элементов ограничена текущим запуском инициатора при построении вложенных результатов завершения, что предотвращает утечку устаревших выходных данных дочерних элементов из предыдущих запусков в текущее объявление.
  • Ответы с объявлением сохраняют маршрутизацию по треду/теме, когда она доступна в адаптерах каналов.
  • Контекст объявления нормализуется до стабильного внутреннего блока событий:
    • источник (subagent или cron)
    • ключ/идентификатор дочерней сессии
    • тип объявления + метка задачи
    • строка статуса, выведенная из результата выполнения (success, error, timeout или unknown)
    • содержимое результата из шага объявления (или (no output), если отсутствует)
    • последующая инструкция, описывающая, когда отвечать, а когда молчать
  • Status не выводится из вывода модели; он берется из сигналов результата выполнения.

Полезные нагрузки объявления включают строку статистики в конце (даже при обертке):

  • Время выполнения (например, runtime 5m12s)
  • Использование токенов (ввод/вывод/всего)
  • Расчетная стоимость, когда настроено ценообразование модели (models.providers.*.models[].cost)
  • sessionKey, sessionId и путь к транскрипту (чтобы основной агент мог получить историю через sessions_history или проверить файл на диске)
  • Внутренние метаданные предназначены только для оркестрации; ответы, обращенные к пользователю, должны быть переписаны обычным голосом помощника.

Политика инструментов (инструменты суб-агентов)

По умолчанию суб-агенты получают все инструменты, кроме инструментов сессии и системных инструментов:

  • sessions_list
  • sessions_history
  • sessions_send
  • sessions_spawn

Когда maxSpawnDepth >= 2, суб-агенты оркестраторы глубины 1 дополнительно получают sessions_spawn, subagents, sessions_list и sessions_history, чтобы они могли управлять своими дочерними элементами. Переопределите через конфигурацию:

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // deny имеет приоритет
        deny: ["gateway", "cron"],
        // если allow установлен, он становится исключительным (deny все равно имеет приоритет)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

Параллельное выполнение

Суб-агенты используют выделенную очередь внутри процесса:

  • Имя очереди: subagent
  • Параллельное выполнение: agents.defaults.subagents.maxConcurrent (по умолчанию 8)

Остановка

  • Отправка /stop в чате инициатора прерывает сессию инициатора и останавливает любые активные запуски суб-агентов, порожденные из нее, каскадно распространяясь на вложенные дочерние элементы.
  • /subagents kill <id> останавливает конкретного суб-агента и каскадно распространяется на его дочерние элементы.

Ограничения

  • Объявление суб-агента выполняется по принципу best-effort. Если шлюз перезапускается, ожидающая работа по «объявлению обратно» теряется.
  • Суб-агенты все еще используют общие ресурсы процесса шлюза; рассматривайте 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).

Agent SendACP Agents