Інструменти сеансу

OpenClaw надає агентам інструменти для роботи між сеансами, перевірки стану та оркестрування субагентів.

Доступні інструменти

На ці інструменти й надалі поширюються активний профіль інструментів і політика дозволів/заборон. tools.profile: "coding" містить повний набір засобів оркестрування сеансів, зокрема sessions_spawn, sessions_yield і subagents. tools.profile: "messaging" містить інструменти обміну повідомленнями між сеансами (sessions_list, sessions_history, sessions_send, session_status), але не містить засобу створення субагентів. Щоб зберегти профіль обміну повідомленнями й водночас дозволити нативне делегування, додайте:

{  tools: {    profile: "messaging",    alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"],  },}

Політики групи, постачальника, пісочниці та окремого агента все одно можуть вилучити ці інструменти після етапу застосування профілю. Використайте /tools у відповідному сеансі, щоб переглянути фактичний список інструментів.

Перелік і читання сеансів

sessions_list повертає сеанси з їхнім ключем, agentId, типом, каналом, моделлю, кількістю токенів і часовими позначками. Фільтруйте за kinds (масив; допустимі значення: main, group, cron, hook, node, other), точним label, точним agentId, текстом search або давністю (activeMinutes). Типово повертаються активні сеанси; передайте archived: true, щоб натомість переглянути архівні сеанси. Рядки містять стан pinned і archived. Установіть includeDerivedTitles, includeLastMessage або messageLimit (щонайбільше 20), коли потрібне сортування на зразок поштової скриньки: похідний заголовок з урахуванням області видимості, фрагмент попереднього перегляду останнього повідомлення або обмежена кількість нещодавніх повідомлень у кожному рядку. Похідні заголовки й попередні перегляди створюються лише для сеансів, які викликач уже може бачити відповідно до налаштованої політики видимості інструментів сеансу, тому сторонні сеанси залишаються прихованими. Коли видимість обмежена, sessions_list повертає необов’язкові метадані visibility, що показують фактичний режим і попередження про можливе обмеження результатів областю видимості.

sessions_history отримує журнал розмови для певного сеансу. Типово результати інструментів не включаються; передайте includeTools: true, щоб побачити їх. Використайте limit для найновішої обмеженої кінцевої частини. Передайте offset: 0, коли потрібні метадані пагінації, а потім передавайте повернені значення nextOffset, щоб посторінково рухатися назад старішими вікнами журналу OpenClaw без читання необроблених файлів журналу. Сторінки з явним зміщенням не об’єднують зовнішні імпорти резервного варіанта CLI; використовуйте типовий перегляд найновішої кінцевої частини (без offset), коли потрібна об’єднана історія відображення.

Повернений перегляд навмисно обмежено й відфільтровано задля безпеки:

• текст асистента нормалізується перед відновленням:
  • теги міркувань вилучаються
  • службові блоки <relevant-memories> / <relevant_memories> вилучаються
  • XML-блоки корисного навантаження викликів інструментів у звичайному тексті, як-от <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls> і <function_calls>...</function_calls>, вилучаються, зокрема й обрізані корисні навантаження, які не мають коректного закриття
  • службові конструкції викликів/результатів інструментів зі зниженим форматом, як-от [Tool Call: ...], [Tool Result ...] і [Historical context ...], вилучаються
  • витіклі керівні токени моделі, як-от <|assistant|>, інші ASCII-токени <|...|> і повноширинні варіанти <｜...｜>, вилучаються
  • некоректний XML викликів інструментів MiniMax, як-от <invoke ...> / </minimax:tool_call>, вилучається
• текст, схожий на облікові дані або токени, редагується перед поверненням
• довгі текстові блоки обрізаються
• у дуже великих історіях можуть вилучатися старіші рядки або надмірно великий рядок може замінюватися на [sessions_history omitted: message too large]
• інструмент повідомляє прапорці зведення, як-от truncated, droppedMessages, contentTruncated, contentRedacted, bytes, і метадані пагінації

Обидва інструменти приймають або ключ сеансу (наприклад, "main"), або ідентифікатор сеансу з попереднього виклику списку.

Якщо потрібен точний необроблений журнал, перегляньте рядки журналу SQLite у відповідній області замість того, щоб вважати sessions_history невідфільтрованим дампом.

Надсилання повідомлень між сеансами

sessions_send доставляє повідомлення іншому сеансу та за потреби очікує на відповідь:

• Без очікування відповіді: установіть timeoutSeconds: 0, щоб поставити повідомлення в чергу та негайно повернутися.
• Очікування відповіді: установіть час очікування та отримайте відповідь безпосередньо.

Сеанси чату, прив’язані до гілки, наприклад ключі, що закінчуються на :thread:<id>, не є допустимими цілями sessions_send. Для координації між агентами використовуйте ключ батьківського сеансу каналу, щоб повідомлення, спрямовані через інструменти, не з’являлися в активній гілці, яку бачить користувач.

Повідомлення та подальші відповіді A2A позначаються як міжсеансові дані в отриманому запиті ([Inter-session message ... isUser=false]) і в походженні журналу. Агент-отримувач має розглядати їх як дані, спрямовані через інструменти, а не як безпосередню інструкцію від кінцевого користувача.

Після відповіді цільового агента OpenClaw може запустити цикл зворотних відповідей, у якому агенти почергово обмінюються повідомленнями (до session.agentToAgent.maxPingPongTurns, діапазон 0-20, типове значення 5). Цільовий агент може відповісти REPLY_SKIP, щоб завершити цикл достроково.

Передайте watch: true, щоб також зареєструвати відправника як спостерігача за змінами стану цілі: коли інший учасник згодом надсилає цілі безпосереднє повідомлення від людини або змінює її ціль, відправник отримує системне сповіщення з посиланням на session_status changesSince. Реєстрація відбувається після успішного надсилання, спрямовується на сеанс, який фактично отримав повідомлення, і починається з його поточної версії стану, тому сповіщення спричиняють лише подальші зміни. Результат повідомляє watched: true, коли реєстрація успішна. Див. Відстеження стану сеансу.

Допоміжні засоби стану й оркестрування

session_status — це полегшений інструмент, еквівалентний /status, для поточного або іншого видимого сеансу. Він повідомляє про використання, час, стан моделі/середовища виконання та контекст пов’язаного фонового завдання, якщо він наявний. Як і /status, він може доповнювати неповні лічильники токенів/кешу з останнього запису про використання в журналі, а model=default скидає перевизначення для окремого сеансу. Використовуйте sessionKey="current" для поточного сеансу викликача; видимі клієнтські мітки, як-от openclaw-tui, не є ключами сеансів.

Коли доступні метадані маршруту, session_status також містить видимий JSON-блок Route context і відповідні структуровані поля details. Ці поля дають змогу відрізнити ключ сеансу від маршруту, який наразі обробляє активний запуск:

• origin — місце створення сеансу або постачальник, визначений із префікса ключа сеансу, придатного для доставки, коли в старішому стані немає збережених метаданих походження.
• active — поточний маршрут активного запуску. Він повідомляється лише для активного або поточного сеансу, який обробляється зараз.
• deliveryContext — збережений у сеансі маршрут доставки, який OpenClaw може повторно використовувати для подальшої доставки, навіть коли активна поверхня відрізняється.

Зміни стану сеансу

OpenClaw зберігає довговічний журнал сигналів про суттєві зміни стану сеансу (безпосередні повідомлення від людей до відстежуваних сеансів, результати дочірніх запусків, зміни цілі, Compaction). Рядки sessions_list і session_status надають stateVersion сеансу, а session_status приймає changesSince: <version>, щоб повернути типізовані події після цієї версії, із точним сигналом historyGap, коли запитана версія передує збереженій історії. Спостерігачі — батьківські сеанси створення автоматично, sessions_send watch: true явно — отримують одне об’єднане сповіщення про застарілий стан, коли інший учасник змінює відстежуваний сеанс.

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

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

subagents — це допоміжний засіб видимості для вже створених субагентів OpenClaw. Він підтримує action: "list" для перегляду активних/нещодавніх запусків.

Створення субагентів

sessions_spawn типово створює ізольований сеанс для фонового завдання. Він завжди працює без блокування: негайно повертає runId і childSessionKey. Нативні запуски субагентів отримують делеговане завдання в першому видимому повідомленні [Subagent Task] дочірнього сеансу, тоді як системний запит містить лише правила середовища виконання субагента й контекст маршрутизації.

Основні параметри:

• runtime: "subagent" (типово) або "acp" для агентів зовнішнього середовища.
• перевизначення model і thinking для дочірнього сеансу.
• thread: true для прив’язування створеного сеансу до гілки чату (Discord, Slack тощо).
• sandbox: "require" для примусового застосування пісочниці до дочірнього сеансу.
• context: "fork" для нативних субагентів, коли дочірньому сеансу потрібен журнал поточного запитувача; не вказуйте його або використайте context: "isolated" для чистого дочірнього сеансу. context: "fork" допустимий лише з runtime: "subagent". Прив’язані до гілки нативні субагенти типово використовують context: "fork", якщо threadBindings.defaultSpawnContext не вказує інше.

Типові листові субагенти не отримують інструментів сеансу. Коли maxSpawnDepth >= 2, субагенти-оркестратори глибини 1 додатково отримують sessions_spawn, subagents, sessions_list і sessions_history, щоб керувати власними дочірніми сеансами. Листові запуски все одно не отримують інструментів рекурсивного оркестрування.

Після завершення етап оголошення публікує результат у каналі запитувача. Доставка результату зберігає маршрутизацію прив’язаної гілки/теми, коли вона доступна, а якщо походження завершення визначає лише канал, OpenClaw усе одно може повторно використати збережений маршрут сеансу запитувача (lastChannel / lastTo) для безпосередньої доставки.

Поведінку, специфічну для ACP, див. у розділі Агенти ACP.

Видимість

Область дії інструментів сеансу обмежує те, що може бачити агент:

Типове значення — tree. Сеанси в пісочниці примусово обмежуються до tree незалежно від конфігурації.

Додаткові матеріали

• Керування сеансами: маршрутизація, життєвий цикл, обслуговування
• Підагeнти: життєвий цикл дочірніх сеансів і доставлення
• Агенти ACP: запуск у зовнішньому середовищі
• Мультиагентна система: мультиагентна архітектура
• Конфігурація Gateway: параметри конфігурації інструмента сеансів

Пов’язані матеріали

• Керування сеансами
• Очищення сеансів