​

Підагенти

​

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

• /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>

​

Поведінка spawn

• Команда spawn є неблокувальною; вона одразу повертає id запуску.
• Після завершення підагент повідомляє зведене/результуюче повідомлення назад у чат-канал запитувача.
• Доставка завершення є push-орієнтованою. Після запуску не опитуйте /subagents list, sessions_list або sessions_history у циклі лише для того, щоб дочекатися завершення; перевіряйте статус лише за запитом для налагодження або втручання.
• Після завершення OpenClaw у межах best-effort закриває відстежувані вкладки браузера/процеси, відкриті цією сесією підагента, перш ніж продовжиться потік очищення після повідомлення.
• Для ручних запусків доставка є стійкою:
  • OpenClaw спочатку намагається виконати пряму доставку agent зі стабільним ключем ідемпотентності.
  • Якщо пряма доставка не вдається, він переходить до маршрутизації через чергу.
  • Якщо маршрутизація через чергу все ще недоступна, повідомлення повторно надсилається з коротким експоненційним backoff перед остаточною відмовою.
• Доставка завершення зберігає визначений маршрут запитувача:
  • маршрути завершення, прив’язані до потоку або розмови, мають пріоритет, коли доступні
  • якщо джерело завершення надає лише канал, OpenClaw заповнює відсутні target/account із визначеного маршруту сесії запитувача (lastChannel / lastTo / lastAccountId), щоб пряма доставка все одно працювала
• Передача завершення до сесії запитувача — це внутрішній контекст, згенерований під час виконання (а не написаний користувачем текст), і містить:
  • Result (останній видимий текст відповіді assistant, інакше санітований останній текст tool/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, особливо модель доставки ACP під час налагодження завершень або циклів агент-до-агента.

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

​

Інструмент

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

• task (обов’язковий)
• label? (необов’язковий)
• agentId? (необов’язковий; запустити під іншим id агента, якщо це дозволено)
• model? (необов’язковий; перевизначає модель підагента; недійсні значення пропускаються, і підагент запускається на моделі за замовчуванням із попередженням у результаті інструмента)
• thinking? (необов’язковий; перевизначає рівень 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: список id агентів, які можна вибрати через agentId (["*"] — дозволити будь-який). Типово: лише агент запитувача.
• agents.defaults.subagents.allowAgents: список дозволених цільових агентів за замовчуванням, який використовується, коли агент запитувача не задає власний subagents.allowAgents.
• Захист успадкування sandbox: якщо сесія запитувача ізольована, sessions_spawn відхиляє цілі, які працювали б без sandbox.
• agents.defaults.subagents.requireAgentId / agents.list[].subagents.requireAgentId: коли true, блокують виклики sessions_spawn, які не вказують agentId (примушує до явного вибору профілю). Типове значення: false.

• Використовуйте agents_list, щоб побачити, які id агентів наразі дозволені для sessions_spawn.

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

​

Вкладені підагенти

​

Як увімкнути

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

​

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

​

Ланцюг повідомлень

1. Працівник depth-2 завершується → повідомляє свого батьківського агента (оркестратор depth-1)
2. Оркестратор depth-1 отримує повідомлення, синтезує результати, завершується → повідомляє main
3. Main-агент отримує повідомлення й доставляє його користувачу

• Запускайте дочірню роботу один раз і чекайте на події завершення замість побудови циклів опитування навколо sessions_list, sessions_history, /subagents list або команд exec зі сном.
• Якщо подія завершення дочірнього агента надходить після того, як ви вже надіслали фінальну відповідь, правильна подальша дія — це точний мовчазний токен NO_REPLY / no_reply.

​

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

• Роль і область керування записуються в метадані сесії під час spawn. Це запобігає тому, щоб плоскі або відновлені ключі сесій випадково знову отримали привілеї оркестратора.
• Depth 1 (оркестратор, коли maxSpawnDepth >= 2): отримує sessions_spawn, subagents, sessions_list, sessions_history, щоб керувати своїми дочірніми агентами. Інші інструменти сесій/системи залишаються забороненими.
• Depth 1 (кінцевий виконавець, коли maxSpawnDepth == 1): без інструментів сесії (поточна поведінка за замовчуванням).
• Depth 2 (кінцевий працівник): без інструментів сесії — sessions_spawn на depth 2 завжди заборонено. Не може запускати подальших дочірніх агентів.

​

Ліміт spawn для агента

​

Каскадна зупинка

• /stop в основному чаті зупиняє всіх агентів depth-1 і каскадно зупиняє їхніх дочірніх агентів depth-2.
• /subagents kill <id> зупиняє конкретного підагента і каскадно зупиняє його дочірніх агентів.
• /subagents kill all зупиняє всіх підагентів для запитувача і виконує каскадну зупинку.

​

Автентифікація

• Ключ сесії підагента: agent:<agentId>:subagent:<uuid>.
• Сховище автентифікації завантажується з agentDir цього агента.
• Профілі автентифікації основного агента зливаються як резервний варіант; профілі агента мають пріоритет над профілями основного агента у разі конфліктів.

​

Повідомлення про завершення

• Крок повідомлення про завершення виконується всередині сесії підагента (а не сесії запитувача).
• Якщо підагент відповідає точно ANNOUNCE_SKIP, нічого не публікується.
• Якщо останній текст assistant є точним мовчазним токеном NO_REPLY / no_reply, вивід повідомлення про завершення пригнічується, навіть якщо раніше був видимий прогрес.
• Інакше доставка залежить від глибини запитувача:
  • для сесій запитувача верхнього рівня використовується подальший виклик agent із зовнішньою доставкою (deliver=true)
  • вкладені сесії підагента-запитувача отримують внутрішню ін’єкцію подальших дій (deliver=false), щоб оркестратор міг синтезувати результати дочірніх агентів у межах сесії
  • якщо вкладена сесія підагента-запитувача вже відсутня, OpenClaw за можливості повертається до запитувача цієї сесії
• Для сесій запитувача верхнього рівня пряма доставка в режимі завершення спочатку визначає будь-який прив’язаний маршрут розмови/потоку та перевизначення hook, а потім заповнює відсутні поля channel-target зі збереженого маршруту сесії запитувача. Це утримує завершення в правильному чаті/темі, навіть коли джерело завершення ідентифікує лише канал.
• Агрегація завершень дочірніх агентів обмежується поточним запуском запитувача під час побудови вкладених результатів завершення, що запобігає витоку застарілих виводів дочірніх агентів із попередніх запусків у поточне повідомлення.
• Відповіді повідомлення про завершення зберігають маршрутизацію потоку/теми, коли вона доступна в адаптерах каналів.
• Контекст повідомлення про завершення нормалізується до стабільного внутрішнього блоку подій:
  • джерело (subagent або cron)
  • ключ/id дочірньої сесії
  • тип повідомлення про завершення + мітка завдання
  • рядок статусу, виведений із результату виконання (success, error, timeout або unknown)
  • вміст результату, вибраний з останнього видимого тексту assistant, інакше — санітований останній текст tool/toolResult; запуски, що завершилися помилкою, повідомляють про статус помилки без повторного відтворення захопленого тексту відповіді
  • інструкція подальших дій, яка описує, коли потрібно відповідати, а коли — мовчати
• Status не виводиться з відповіді моделі; він надходить із сигналів результату виконання.
• У разі тайм-ауту, якщо дочірній агент встиг пройти лише через виклики інструментів, повідомлення про завершення може згорнути цю історію в коротке зведення часткового прогресу замість відтворення сирого виводу інструментів.

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

• history assistant спочатку нормалізується:
  • теги thinking видаляються
  • службові блоки <relevant-memories> / <relevant_memories> видаляються
  • прості текстові XML-блоки payload-ів викликів інструментів, такі як <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls> і <function_calls>...</function_calls>, видаляються, зокрема й усічені payload-и, які так і не закрилися коректно
  • службові структури викликів/результатів інструментів і маркери історичного контексту в downgraded-формі видаляються
  • витоки керувальних токенів моделі, як-от <|assistant|>, інші ASCII-токени <|...|> і full-width варіанти <｜...｜>, видаляються
  • некоректний XML викликів інструментів MiniMax видаляється
• текст, схожий на облікові дані/токени, редагується
• довгі блоки можуть бути обрізані
• у дуже великих історіях старіші рядки можуть відкидатися або надто великий рядок може бути замінений на [sessions_history omitted: message too large]
• перевірка сирого транскрипту на диску — це резервний варіант, коли вам потрібен повний побайтовий транскрипт

​

Політика інструментів (інструменти підагента)

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

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

​

Одночасність

• Назва смуги: subagent
• Одночасність: agents.defaults.subagents.maxConcurrent (типово 8)

​

Зупинка

• Надсилання /stop у чаті запитувача перериває сесію запитувача і зупиняє всі активні запуски підагентів, створені з неї, каскадно охоплюючи вкладених дочірніх агентів.
• /subagents kill <id> зупиняє конкретного підагента і каскадно зупиняє його дочірніх агентів.

​

Обмеження

• Повідомлення підагента про завершення виконується в режимі best-effort. Якщо gateway перезапуститься, очікувана робота з «повідомленням назад» буде втрачена.
• Підагенти все ще спільно використовують ресурси того самого процесу 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). Для більшості випадків використання рекомендується depth 2.
• maxChildrenPerAgent обмежує кількість активних дочірніх агентів на сесію (типово: 5, діапазон: 1–20).