Вопрос

Субагенты в OpenClaw: запуск, вложенность, остановка

`sessions_spawn` создаёт субагента в отдельной сессии, глубина вложенности по умолчанию `5`, а гасить цепочку умеют `/stop`, `chat.abort` и `sessions.abort` с `runId`.

· 3 мин чтения

Коротко

  • Субагент — фоновый запуск агента в отдельной сессии agent:<id>:subagent:<uuid>, который по умолчанию сам сообщает результат родителю.
  • Глубина вложенности по умолчанию 5. На границе maxSpawnDepth субагент становится листом и больше не порождает детей, задайте свой предел, чтобы тормознуть цепочку раньше.
  • Остановить ветку можно каскадно: /stop в чате родителя, chat.abort или sessions.abort с runId. chat.abort без runId детей не гасит.
  • maxChildrenPerAgent и maxConcurrent это разные лимиты. Поднять параллельность ещё не значит поднять размер веера.

Сверено с документацией OpenClaw 2026.9.8, 4 октября 2026.

Субагент в OpenClaw это отдельный запуск агента в собственной сессии. По умолчанию он анонсирует результат обратно родителю. Запуск идёт через инструмент sessions_spawn. Дальше — как устроена цепочка, где у неё естественный тормоз и что поставить в конфиг.

Как запускается субагент

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

Глубина вложенности и набор инструментов зависят от уровня сессии. На глубине 0 сидит главный агент с сессией agent:<id>:main. С 1 субагент получает роль оркестратора и инструменты sessions_spawn, subagents, sessions_list, sessions_history. На самой границе maxSpawnDepth субагент становится листом: рекурсивные инструменты у него отбираются, и он уже не может порождать детей.

Параллельно работает maxChildrenPerAgent, отдельный лимит активных детей на одну сессию (по умолчанию 5). И maxConcurrent, лимит одновременно исполняемых запусков у непосредственного родителя (по умолчанию 8). Они не подменяют друг друга: поднять maxConcurrent и думать, что веер вырос, нельзя. В Swarm-режиме (collect: true) дети уходят в отдельную очередь subagent:swarm:<schedulerGroupKey> со своим tools.swarm.maxConcurrent (по умолчанию 32).

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // stop nesting after depth 2 (default: 5, range 1-5)
        maxChildrenPerAgent: 5, // max active children per agent session (default: 5, range 1-20)
        maxConcurrent: 8, // concurrent child runs per spawning session (default: 8)
        runTimeoutSeconds: 900, // default timeout for sessions_spawn (0 = no timeout)
        announceTimeoutMs: 120000, // gateway announce timeout, excluding accepted queue waits
      },
    },
  },
}

Как остановить субагента

Остановка по умолчанию каскадная. /stop в чате родителя гасит его активное дерево детей. Команда чистит очередь этой сессии и отменяет ожидающие завершения. У chat.abort с конкретным runId область действия та же, точная ветка этого запуска. sessions.abort с runId тоже целится в один запуск. Session-wide sessions.abort уже просит каскадной отмены потомков.

Чистый chat.abort без runId детей не трогает, имейте в виду, если пытаетесь остановить фоновую ветку. После перезапуска Gateway прерванные субагенты не перезапускаются автоматически. Родитель получает результаты, которые успели зафиксироваться, и сам решает, что переделать. Неполная отмена возвращается ошибкой, а не чистым успехом: /stop сообщает фактические счётчики остановленных и упавших детей.

Конфиг: что проверить у себя

Первое место, где легко оставить дыру, это tools.agentToAgent.allow. Пустой или пропущенный список считается «всем можно». После openclaw agents delete запись удаляется, и при пустом allow политика откатывается на allow-all. У tools.sessions.visibility дефолт all: сессионные инструменты видят все сессии на Gateway, включая чужих пользователей. Сузьте до tree или self, если это лишнее. Запросы между агентами дополнительно рулит tools.agentToAgent (включён по умолчанию).

{
  tools: {
    agentToAgent: {
      allow: ["home", "work"],
    },
    sessions: {
      // "self" | "tree" | "agent" | "all"
      visibility: "all",
    },
  },
}

Частые ошибки

  • Считать maxConcurrent и maxChildrenPerAgent одним лимитом. Они разные: поднять параллельность ещё не значит поднять размер веера.
  • Оставлять tools.agentToAgent.allow пустым и думать, что доступ закрыт. Пустой список равен пропущенному, то есть allow-all.
  • Полагаться на автоперезапуск прерванных субагентов после рестарта Gateway. Этого нет, родитель сам решает, что дособрать.
  • Гасить ветку через chat.abort без runId. Это не каскад. Для каскада нужен runId или /stop в чате родителя.
  • Ставить visibility: "all" и удивляться, что субагент видит сессии чужих пользователей. Сузьте до tree или self.