​

Субагенти

​

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

• /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 зі стабільним ключем ідемпотентності.
  • Якщо пряма доставка не вдається, він повертається до маршрутизації через чергу.
  • Якщо маршрутизація через чергу все ще недоступна, спроба повідомлення повторюється з короткою експоненційною затримкою перед остаточною відмовою.
• Доставка після завершення зберігає визначений маршрут запитувача:
  • маршрути завершення, прив’язані до треда або розмови, мають пріоритет, коли доступні
  • якщо джерело завершення надає лише канал, OpenClaw заповнює відсутні target/account із визначеного маршруту сесії запитувача (lastChannel / lastTo / lastAccountId), щоб пряма доставка все одно працювала
• Передача завершення до сесії запитувача — це внутрішній контекст, згенерований runtime (а не текст, створений користувачем), і вона включає:
  • Result (останній видимий текст відповіді assistant, інакше санітизований останній текст tool/toolResult)
  • Status (completed successfully / failed / timed out / unknown)
  • компактну статистику runtime/токенів
  • інструкцію доставки, яка вказує агенту запитувача переписати це звичайним голосом помічника (а не пересилати сирі внутрішні метадані)
• --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-агенти.

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

​

Інструмент

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

• 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 відхиляє запуск, якщо цільовий дочірній runtime не ізольований)
• 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.
• Захист успадкування ізоляції: якщо сесія запитувача ізольована, sessions_spawn відхиляє цілі, які працювали б без ізоляції.
• 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, // глобальне обмеження concurrency для lane (типово: 8)
        runTimeoutSeconds: 900, // типовий timeout для sessions_spawn, коли його пропущено (0 = без timeout)
      },
    },
  },
}

​

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

​

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

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

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

​

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

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

​

Обмеження запуску для окремого агента

​

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

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

​

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

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

​

Повідомлення

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

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

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

​

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

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

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

​

Конкурентність

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