Субагенти

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

Основні цілі:

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

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. Завершення субагентів повертаються як внутрішні події батьківського сеансу; батьківський агент або агент-запитувач вирішує, чи потрібне видиме для користувача оновлення.

Режими контексту

Нативні субагенти стартують ізольовано, якщо викликач явно не просить відгалузити поточний транскрипт.

Використовуйте 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, коли це значення задане; інакше fallback до 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, shell sleep або опитування процесів лише для виявлення завершення дочірнього елемента.

Використовуйте sessions_yield лише тоді, коли ефективний список інструментів сесії містить його. Деякі мінімальні або користувацькі профілі інструментів можуть відкривати sessions_spawn і subagents без відкриття sessions_yield; у такому разі не вигадуйте цикл опитування лише для очікування завершення.

Коли існують активні дочірні елементи, OpenClaw вставляє компактний згенерований середовищем виконання блок підказки Active Subagents у звичайні ходи, щоб запитувач міг бачити поточні дочірні сесії, ідентифікатори запусків, стани, мітки, завдання та псевдоніми taskName без опитування. Поля завдання та мітки в цьому блоці взято в лапки як дані, а не інструкції, оскільки вони можуть походити з наданих користувачем/моделлю аргументів створення.

Інструмент: subagents

Перелічує створені запуски під-агентів, власником яких є сесія запитувача. Область дії обмежена поточним запитувачем; дочірній елемент може бачити лише власні керовані дочірні елементи.

Використовуйте subagents для стану на вимогу та налагодження. Використовуйте sessions_yield, щоб чекати на події завершення.

Сесії з прив’язкою до потоку

Коли для каналу ввімкнено прив’язки до потоків, під-агент може лишатися прив’язаним до потоку, щоб наступні повідомлення користувача в цьому потоці продовжували маршрутизуватися до тієї самої сесії під-агента.

Канали з підтримкою потоків

Будь-який канал з адаптером прив’язки сесій може підтримувати постійні сесії під-агентів із прив’язкою до потоку (sessions_spawn з thread: true). Пакетні адаптери наразі включають потоки Discord, потоки Matrix, теми форумів Telegram і прив’язки поточної розмови для Feishu. Використовуйте конфігураційні ключі threadBindings для кожного каналу для ввімкнення, таймаутів і spawnSessions.

Швидкий потік

Ручне керування

Перемикачі конфігурації

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

Див. Довідник конфігурації і Slash-команди, щоб отримати поточні відомості про адаптери.

Список дозволених

Якщо сесія запитувача ізольована, sessions_spawn відхиляє цілі, які запускалися б без ізоляції.

Виявлення

Використовуйте agents_list, щоб побачити, які ідентифікатори агентів зараз дозволені для sessions_spawn. Відповідь містить ефективну модель кожного переліченого агента та вбудовані метадані середовища виконання, щоб виклики могли розрізняти OpenClaw, Codex app-server та інші налаштовані нативні середовища виконання.

Записи 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      },    },  },}

Рівні глибини

Ланцюг оголошення

Результати передаються назад угору ланцюгом:

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 повертається до запитувача цього сеансу, коли він доступний.

Для сеансів запитувача верхнього рівня пряма доставка в режимі завершення спочатку визначає будь-який прив’язаний маршрут розмови/потоку й перевизначення hook, а потім заповнює відсутні поля цілі каналу зі збереженого маршруту сеансу запитувача. Це утримує завершення в правильному чаті/темі, навіть коли джерело завершення ідентифікує лише канал.

Агрегація завершень дочірніх процесів обмежується поточним запуском запитувача під час побудови вкладених висновків завершення, запобігаючи витоку застарілих виводів дочірніх процесів із попередніх запусків у поточне оголошення. Відповіді оголошень зберігають маршрутизацію потоку/теми, коли вона доступна в адаптерах каналів.

Контекст оголошення

Контекст оголошення нормалізується до стабільного внутрішнього блоку події:

Термінальні невдалі запуски повідомляють стан помилки без повторного відтворення захопленого тексту відповіді. Вивід tool/toolResult не просувається в текст результату дочірнього процесу.

Рядок статистики

Payload оголошення містить рядок статистики наприкінці (навіть коли його перенесено):

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

Внутрішні метадані призначені лише для оркестрації; відповіді, видимі користувачу, слід переписувати звичайним голосом асистента.

Чому варто віддавати перевагу sessions_history

sessions_history — безпечніший шлях оркестрації:

• Спогад асистента спочатку нормалізується: теги міркувань видаляються; каркас <relevant-memories> / <relevant_memories> видаляється; plain-text блоки XML payload викликів інструментів (<tool_call>, <function_call>, <tool_calls>, <function_calls>) видаляються, включно з обрізаними payload, які ніколи не закриваються коректно; знижений каркас викликів/результатів інструментів і маркери історичного контексту видаляються; витеклі керівні токени моделі (<|assistant|>, інші ASCII <|...|>, повноширинні <｜...｜>) видаляються; некоректний XML викликів інструментів MiniMax видаляється.
• Текст, схожий на облікові дані/токени, редагується.
• Довгі блоки можуть обрізатися.
• Дуже великі історії можуть відкидати старіші рядки або замінювати надмірно великий рядок на [sessions_history omitted: message too large].
• Використовуйте nextOffset, коли він присутній, щоб гортати назад старіші вікна транскрипту.
• Безпосередня перевірка транскрипту на диску є резервним варіантом, коли потрібен повний транскрипт байт у байт.

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

Субагенти спочатку використовують той самий профіль і конвеєр політики інструментів, що й батьківський або цільовий агент. Після цього OpenClaw застосовує шар обмежень субагента.

Без обмежувального tools.profile субагенти отримують усі інструменти, крім інструмента повідомлень, сеансових інструментів і системних інструментів:

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn
• message

sessions_history і тут залишається обмеженим, санітизованим поданням спогадів — це не сирий дамп транскрипту.

Коли 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-profile використовувати автоматизацію браузера, додайте browser на етапі профілю:

{  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

Використовуйте agents.list[].tools.alsoAllow: ["browser"] для кожного агента, коли лише один агент має отримати автоматизацію браузера.

Паралельність

Субагенти використовують окрему внутрішньопроцесну чергу:

• Назва черги: subagent
• Паралельність: agents.defaults.subagents.maxConcurrent (за замовчуванням 8)

Живучість і відновлення

OpenClaw не трактує відсутність endedAt як постійний доказ того, що субагент досі живий. Незавершені запуски, старші за вікно застарілого запуску, припиняють рахуватися як активні/очікувані в /subagents list, підсумках стану, блокуванні завершення нащадків і перевірках паралельності для кожного сеансу.

Після перезапуску Gateway застарілі незавершені відновлені запуски відсікаються, якщо їхній дочірній сеанс не позначено abortedLastRun: true. Такі перервані під час перезапуску дочірні сеанси залишаються відновлюваними через потік відновлення осиротілих субагентів, який надсилає синтетичне повідомлення відновлення перед очищенням маркера переривання.

Автоматичне відновлення після перезапуску обмежується для кожного дочірнього сеансу. Якщо той самий дочірній субагент неодноразово приймається для відновлення сироти в межах швидкого вікна повторного застрягання, OpenClaw зберігає tombstone відновлення в цьому сеансі й припиняє автоматично відновлювати його під час подальших перезапусків. Запустіть openclaw tasks maintenance --apply, щоб узгодити запис завдання, або openclaw doctor --fix, щоб очистити застарілі прапорці перерваного відновлення в сеансах із tombstone.

Зупинка

• Надсилання /stop у чаті запитувача перериває сеанс запитувача й зупиняє всі активні запуски субагентів, створені з нього, каскадно переходячи до вкладених дочірніх процесів.

Обмеження

• Оголошення субагента виконується на основі найкращого зусилля. Якщо 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 дотримуються тієї самої межі: TOOLS.md залишається в успадкованих інструкціях потоку Codex, тоді як persona, identity і user файли, призначені лише для батьківського процесу, ін’єктуються як інструкції співпраці з областю дії на один хід, щоб дочірні процеси не клонували їх.
• Максимальна глибина вкладення — 5 (діапазон maxSpawnDepth: 1–5). Для більшості випадків використання рекомендовано рівень 2.
• maxChildrenPerAgent обмежує активні дочірні процеси на сеанс (за замовчуванням 5, діапазон 1–20).

Пов’язане

• Агенти ACP
• Надсилання агенту
• Фонові завдання
• Інструменти пісочниці для кількох агентів