From 111efc271a5d89f07537216e03526f54b624c0fa Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 2 May 2026 14:00:55 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/concepts/agent-loop.md | 179 +++++----- .../session-management-compaction.md | 333 +++++++++--------- 2 files changed, 259 insertions(+), 253 deletions(-) diff --git a/docs/uk/concepts/agent-loop.md b/docs/uk/concepts/agent-loop.md index 240ea5121..2f46d7aad 100644 --- a/docs/uk/concepts/agent-loop.md +++ b/docs/uk/concepts/agent-loop.md @@ -1,24 +1,24 @@ --- read_when: - Вам потрібен точний покроковий опис циклу агента або подій життєвого циклу - - Ви змінюєте додавання сеансів до черги, записування транскриптів або поведінку блокування запису сеансу + - Ви змінюєте постановку сеансів у чергу, записи стенограми або поведінку блокування запису сеансу summary: Життєвий цикл циклу агента, потоки та семантика очікування title: Цикл агента x-i18n: - generated_at: "2026-05-01T23:48:22Z" + generated_at: "2026-05-02T13:59:23Z" model: gpt-5.5 provider: openai - source_hash: 4182cf13d43a111a94014d695dee4b1e7385dd3b928b16e2072bd24189256b49 + source_hash: 39c49e8c5d1e380e0569e31856d855484d5a8fa33b04cf85cccde4c9ac21fbe7 source_path: concepts/agent-loop.md workflow: 16 --- -Агентний цикл — це повний «справжній» запуск агента: прийом → складання контексту → інференс моделі → -виконання інструментів → потокові відповіді → збереження стану. Це визначальний шлях, який перетворює повідомлення -на дії та фінальну відповідь, зберігаючи узгоджений стан сеансу. +Агентний цикл — це повний «реальний» запуск агента: приймання → складання контексту → виведення моделі → +виконання інструментів → потокові відповіді → збереження. Це авторитетний шлях, який перетворює повідомлення +на дії та фінальну відповідь, водночас підтримуючи узгоджений стан сеансу. -В OpenClaw цикл — це один серіалізований запуск на сеанс, який випускає події життєвого циклу й потоку, -поки модель думає, викликає інструменти та передає вихідні дані потоком. Цей документ пояснює, як цей автентичний цикл +В OpenClaw цикл — це один серіалізований запуск на сеанс, який надсилає події життєвого циклу та потоку, +поки модель думає, викликає інструменти й транслює вивід. У цьому документі пояснено, як цей автентичний цикл з’єднано від початку до кінця. ## Точки входу @@ -26,69 +26,70 @@ x-i18n: - Gateway RPC: `agent` і `agent.wait`. - CLI: команда `agent`. -## Як це працює (загальний огляд) +## Як це працює (на високому рівні) -1. `agent` RPC перевіряє параметри, визначає сеанс (sessionKey/sessionId), зберігає метадані сеансу, одразу повертає `{ runId, acceptedAt }`. +1. RPC `agent` перевіряє параметри, визначає сеанс (sessionKey/sessionId), зберігає метадані сеансу, одразу повертає `{ runId, acceptedAt }`. 2. `agentCommand` запускає агента: - - визначає стандартні значення моделі + мислення/докладності/трасування + - визначає модель і типові значення thinking/verbose/trace - завантажує знімок Skills - викликає `runEmbeddedPiAgent` (середовище виконання pi-agent-core) - - випускає **кінець/помилку життєвого циклу**, якщо вбудований цикл не випускає їх + - надсилає **lifecycle end/error**, якщо вбудований цикл цього не зробив 3. `runEmbeddedPiAgent`: - - серіалізує запуски через черги на рівні сеансу + глобальні черги - - визначає модель + профіль автентифікації та створює сеанс pi - - підписується на події pi та передає потоком дельти асистента/інструментів - - застосовує тайм-аут -> перериває запуск, якщо його перевищено - - для ходів сервера застосунку Codex перериває прийнятий хід, який перестає створювати прогрес сервера застосунку до термінальної події - - повертає корисні навантаження + метадані використання -4. `subscribeEmbeddedPiSession` з’єднує події pi-agent-core з потоком OpenClaw `agent`: + - серіалізує запуски через черги на рівні сеансу й глобальні черги + - визначає модель і профіль автентифікації та створює сеанс pi + - підписується на події pi та транслює дельти асистента/інструментів + - примусово застосовує тайм-аут -> перериває запуск, якщо його перевищено + - для ходів Codex app-server перериває прийнятий хід, який припинив створювати прогрес app-server до термінальної події + - повертає payload-и й метадані використання +4. `subscribeEmbeddedPiSession` з’єднує події pi-agent-core із потоком OpenClaw `agent`: - події інструментів => `stream: "tool"` - дельти асистента => `stream: "assistant"` - події життєвого циклу => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) 5. `agent.wait` використовує `waitForAgentRun`: - - очікує **кінець/помилку життєвого циклу** для `runId` + - очікує **lifecycle end/error** для `runId` - повертає `{ status: ok|error|timeout, startedAt, endedAt, error? }` -## Черги + паралельність +## Черги + конкурентність -- Запуски серіалізуються за ключем сеансу (доріжка сеансу) і, за потреби, через глобальну доріжку. -- Це запобігає гонкам інструментів/сеансу та зберігає узгоджену історію сеансу. -- Канали повідомлень можуть вибирати режими черги (збір/скерування/подальша відповідь), які подають дані в цю систему доріжок. +- Запуски серіалізуються для кожного ключа сеансу (доріжка сеансу) і, за потреби, через глобальну доріжку. +- Це запобігає гонкам інструментів/сеансів і підтримує узгоджену історію сеансу. +- Канали повідомлень можуть вибирати режими черги (collect/steer/followup), які подаються в цю систему доріжок. Див. [Черга команд](/uk/concepts/queue). -- Записи транскрипту також захищено блокуванням запису сеансу на файлі сеансу. Блокування - враховує процеси й базується на файлі, тому воно виявляє записувачів, які обходять внутрішньопроцесну чергу або надходять - з іншого процесу. -- Блокування запису сеансу за замовчуванням не є реентерабельними. Якщо допоміжна функція навмисно вкладає отримання - того самого блокування, зберігаючи одного логічного записувача, вона має явно ввімкнути це за допомогою +- Записи транскрипту також захищені блокуванням запису сеансу на файлі сеансу. Блокування + враховує процеси й базується на файлі, тому воно ловить записувачів, які обходять внутрішньопроцесну чергу або приходять + з іншого процесу. Записувачі транскрипту сеансу очікують до `session.writeLock.acquireTimeoutMs` + перед тим як повідомити, що сеанс зайнятий; типове значення — `60000` мс. +- Блокування запису сеансу за замовчуванням не є реентерабельними. Якщо допоміжний засіб навмисно вкладає отримання + того самого блокування, зберігаючи одного логічного записувача, він має явно увімкнути це за допомогою `allowReentrant: true`. -## Підготовка сеансу + робочого простору +## Підготовка сеансу + робочої області -- Робочий простір визначається та створюється; запуски в пісочниці можуть перенаправлятися до кореня робочого простору пісочниці. -- Skills завантажуються (або повторно використовуються зі знімка) та впроваджуються в середовище й промпт. -- Файли початкового завантаження/контексту визначаються та впроваджуються у звіт системного промпта. -- Отримується блокування запису сеансу; `SessionManager` відкривається й готується до потокової передачі. Будь-який - подальший шлях переписування транскрипту, Compaction або обрізання має отримати те саме блокування перед відкриттям або - зміненням файлу транскрипту. +- Робоча область визначається та створюється; sandboxed-запуски можуть перенаправлятися до кореня sandbox-робочої області. +- Skills завантажуються (або повторно використовуються зі знімка) та інжектяться в env і промпт. +- Bootstrap-/контекстні файли визначаються та інжектяться у звіт системного промпта. +- Отримується блокування запису сеансу; `SessionManager` відкривається й готується перед потоковою передачею. Будь-який + пізніший шлях перезапису транскрипту, Compaction або усікання має взяти те саме блокування перед відкриттям або + зміною файлу транскрипту. ## Складання промпта + системний промпт -- Системний промпт будується з базового промпта OpenClaw, промпта Skills, початкового контексту та перевизначень для окремого запуску. -- Застосовуються обмеження для конкретної моделі та резерв токенів Compaction. +- Системний промпт будується з базового промпта OpenClaw, промпта Skills, bootstrap-контексту та перевизначень для конкретного запуску. +- Застосовуються обмеження, специфічні для моделі, і резерв токенів Compaction. - Див. [Системний промпт](/uk/concepts/system-prompt), щоб дізнатися, що бачить модель. -## Точки хуків (де можна перехопити) +## Точки хуків (де можна перехоплювати) OpenClaw має дві системи хуків: -- **Внутрішні хуки** (хуки Gateway): подієво-орієнтовані скрипти для команд і подій життєвого циклу. -- **Хуки Plugin**: точки розширення всередині життєвого циклу агента/інструмента та конвеєра gateway. +- **Внутрішні хуки** (хуки Gateway): скрипти, керовані подіями, для команд і подій життєвого циклу. +- **Хуки Plugin**: точки розширення всередині життєвого циклу агента/інструментів і конвеєра Gateway. ### Внутрішні хуки (хуки Gateway) -- **`agent:bootstrap`**: виконується під час побудови файлів початкового завантаження до фіналізації системного промпта. - Використовуйте це, щоб додавати/видаляти файли початкового контексту. -- **Командні хуки**: `/new`, `/reset`, `/stop` та інші події команд (див. документацію про хуки). +- **`agent:bootstrap`**: запускається під час побудови bootstrap-файлів до фіналізації системного промпта. + Використовуйте це, щоб додавати/видаляти файли bootstrap-контексту. +- **Командні хуки**: `/new`, `/reset`, `/stop` та інші події команд (див. документ про хуки). Див. [Хуки](/uk/automation/hooks) для налаштування та прикладів. @@ -96,96 +97,96 @@ OpenClaw має дві системи хуків: Вони виконуються всередині циклу агента або конвеєра gateway: -- **`before_model_resolve`**: виконується до сеансу (без `messages`), щоб детерміновано перевизначити провайдера/модель перед визначенням моделі. -- **`before_prompt_build`**: виконується після завантаження сеансу (з `messages`), щоб впровадити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` перед надсиланням промпта. Використовуйте `prependContext` для динамічного тексту на окремий хід, а поля системного контексту — для стабільних настанов, які мають перебувати в просторі системного промпта. +- **`before_model_resolve`**: виконується до сеансу (без `messages`), щоб детерміновано перевизначити provider/model до визначення моделі. +- **`before_prompt_build`**: виконується після завантаження сеансу (з `messages`), щоб інжектити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` перед надсиланням промпта. Використовуйте `prependContext` для динамічного тексту на хід і поля системного контексту для стабільних настанов, які мають перебувати в просторі системного промпта. - **`before_agent_start`**: застарілий хук сумісності, який може виконуватися в будь-якій фазі; віддавайте перевагу явним хукам вище. -- **`before_agent_reply`**: виконується після вбудованих дій і перед викликом LLM, даючи Plugin змогу прийняти хід і повернути синтетичну відповідь або повністю заглушити хід. +- **`before_agent_reply`**: виконується після inline-дій і перед викликом LLM, даючи Plugin змогу забрати хід і повернути синтетичну відповідь або повністю приглушити хід. - **`agent_end`**: перевіряє фінальний список повідомлень і метадані запуску після завершення. -- **`before_compaction` / `after_compaction`**: спостерігає або анотує цикли Compaction. +- **`before_compaction` / `after_compaction`**: спостерігає за циклами Compaction або анотує їх. - **`before_tool_call` / `after_tool_call`**: перехоплює параметри/результати інструментів. -- **`before_install`**: перевіряє вбудовані результати сканування та, за потреби, блокує встановлення Skills або Plugin. -- **`tool_result_persist`**: синхронно трансформує результати інструментів перед записом у транскрипт сеансу, яким володіє OpenClaw. -- **`message_received` / `message_sending` / `message_sent`**: хуки вхідних + вихідних повідомлень. +- **`before_install`**: перевіряє вбудовані результати сканування та, за потреби, блокує встановлення skill або plugin. +- **`tool_result_persist`**: синхронно перетворює результати інструментів перед записом у транскрипт сеансу, що належить OpenClaw. +- **`message_received` / `message_sending` / `message_sent`**: хуки вхідних і вихідних повідомлень. - **`session_start` / `session_end`**: межі життєвого циклу сеансу. - **`gateway_start` / `gateway_stop`**: події життєвого циклу gateway. -Правила рішень хуків для захистів вихідних повідомлень/інструментів: +Правила рішень хуків для вихідних/інструментальних захистів: - `before_tool_call`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. +- `before_tool_call`: `{ block: false }` не виконує дій і не скасовує попереднє блокування. - `before_install`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `before_install`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. +- `before_install`: `{ block: false }` не виконує дій і не скасовує попереднє блокування. - `message_sending`: `{ cancel: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування. +- `message_sending`: `{ cancel: false }` не виконує дій і не скасовує попереднє скасування. Див. [Хуки Plugin](/uk/plugins/hooks) для API хуків і деталей реєстрації. -Тестові обв’язки можуть адаптувати ці хуки по-різному. Обв’язка сервера застосунку Codex зберігає +Harness-и можуть адаптувати ці хуки по-різному. Harness Codex app-server зберігає хуки Plugin OpenClaw як контракт сумісності для документованих дзеркальних -поверхонь, тоді як нативні хуки Codex залишаються окремим низькорівневим механізмом Codex. +поверхонь, тоді як нативні хуки Codex залишаються окремим нижчорівневим механізмом Codex. ## Потокова передача + часткові відповіді -- Дельти асистента передаються потоком із pi-agent-core і випускаються як події `assistant`. -- Блокова потокова передача може випускати часткові відповіді або на `text_end`, або на `message_end`. -- Потокова передача міркувань може випускатися як окремий потік або як блокові відповіді. +- Дельти асистента транслюються з pi-agent-core і надсилаються як події `assistant`. +- Блокова потокова передача може надсилати часткові відповіді або на `text_end`, або на `message_end`. +- Потокова передача міркувань може надсилатися як окремий потік або як блокові відповіді. - Див. [Потокова передача](/uk/concepts/streaming) для поведінки фрагментації та блокових відповідей. ## Виконання інструментів + інструменти повідомлень -- Події початку/оновлення/завершення інструмента випускаються в потоці `tool`. -- Результати інструментів очищуються за розміром і корисними навантаженнями зображень перед журналюванням/випуском. -- Надсилання через інструменти повідомлень відстежуються, щоб пригнічувати дублікати підтверджень асистента. +- Події початку/оновлення/завершення інструментів надсилаються в потоці `tool`. +- Результати інструментів очищаються за розміром і payload-ами зображень перед журналюванням/надсиланням. +- Надсилання інструментами повідомлень відстежуються, щоб придушити дублікати підтверджень від асистента. -## Формування відповіді + пригнічення +## Формування відповіді + придушення -- Фінальні корисні навантаження складаються з: - - тексту асистента (і необов’язкових міркувань) - - вбудованих підсумків інструментів (коли докладність увімкнено + дозволено) - - тексту помилки асистента, коли модель завершується з помилкою -- Точний тихий токен `NO_REPLY` / `no_reply` відфільтровується з вихідних - корисних навантажень. -- Дублікати інструментів повідомлень видаляються з фінального списку корисних навантажень. -- Якщо не залишилося придатних до відображення корисних навантажень і інструмент завершився з помилкою, випускається резервна відповідь про помилку інструмента +- Фінальні payload-и складаються з: + - тексту асистента (і необов’язкового reasoning) + - inline-підсумків інструментів (коли verbose + дозволено) + - тексту помилки асистента, коли модель помиляється +- Точний silent-токен `NO_REPLY` / `no_reply` фільтрується з вихідних + payload-ів. +- Дублікати інструментів повідомлень видаляються з фінального списку payload-ів. +- Якщо не лишається жодного придатного до рендерингу payload-а, а інструмент завершився помилкою, надсилається резервна відповідь про помилку інструмента (якщо інструмент повідомлень уже не надіслав видиму для користувача відповідь). ## Compaction + повторні спроби -- Автоматичний Compaction випускає події потоку `compaction` і може запустити повторну спробу. -- Під час повторної спроби буфери в пам’яті та підсумки інструментів скидаються, щоб уникнути дублювання вихідних даних. +- Auto-compaction надсилає події потоку `compaction` і може запустити повторну спробу. +- Під час повторної спроби буфери в пам’яті та підсумки інструментів скидаються, щоб уникнути дублювання виводу. - Див. [Compaction](/uk/concepts/compaction) для конвеєра Compaction. ## Потоки подій (сьогодні) -- `lifecycle`: випускається `subscribeEmbeddedPiSession` (і як резервний варіант — `agentCommand`) +- `lifecycle`: надсилається `subscribeEmbeddedPiSession` (і як fallback через `agentCommand`) - `assistant`: потокові дельти з pi-agent-core -- `tool`: потокові події інструментів із pi-agent-core +- `tool`: потокові події інструментів з pi-agent-core -## Обробка чат-каналу +## Обробка каналу чату -- Дельти асистента буферизуються в чат-повідомлення `delta`. -- Чатове `final` випускається на **кінець/помилку життєвого циклу**. +- Дельти асистента буферизуються в повідомлення чату `delta`. +- `final` чату надсилається на **lifecycle end/error**. ## Тайм-аути - Типове значення `agent.wait`: 30 с (лише очікування). Параметр `timeoutMs` перевизначає. -- Середовище виконання агента: `agents.defaults.timeoutSeconds` за замовчуванням 172800 с (48 годин); застосовується в таймері переривання `runEmbeddedPiAgent`. -- Середовище виконання Cron: ізольований `timeoutSeconds` для ходу агента належить cron. Планувальник запускає цей таймер, коли починається виконання, перериває базовий запуск у налаштований дедлайн, а потім виконує обмежене очищення перед записом тайм-ауту, щоб застарілий дочірній сеанс не міг залишити доріжку застряглою. -- Діагностика активності сеансу: коли діагностику ввімкнено, `diagnostics.stuckSessionWarnMs` класифікує довгі сеанси `processing`, у яких немає спостереженої відповіді, інструмента, статусу, блока або прогресу ACP. Активні вбудовані запуски, виклики моделей і виклики інструментів повідомляються як `session.long_running`; активна робота без нещодавнього прогресу повідомляється як `session.stalled`; `session.stuck` зарезервовано для застарілого обліку сеансу без активної роботи, і лише цей шлях звільняє відповідну доріжку сеансу, щоб запланована стартова робота могла стекти. Повторні діагностичні події `session.stuck` відступають, поки сеанс лишається незмінним. -- Тайм-аут простою моделі: OpenClaw перериває запит до моделі, коли до завершення вікна простою не надходять фрагменти відповіді. `models.providers..timeoutSeconds` розширює цей сторожовий таймер простою для повільних локальних/самостійно розміщених провайдерів; інакше OpenClaw використовує `agents.defaults.timeoutSeconds`, коли його налаштовано, з типовим обмеженням 120 с. Запуски, ініційовані Cron, без явного тайм-ауту моделі або агента вимикають сторожовий таймер простою та покладаються на зовнішній тайм-аут cron. -- Тайм-аут HTTP-запиту провайдера: `models.providers..timeoutSeconds` застосовується до HTTP-запитів вибірки моделі цього провайдера, зокрема підключення, заголовків, тіла, тайм-ауту запиту SDK, загальної обробки переривання захищеної вибірки та сторожового таймера простою потоку моделі. Використовуйте це для повільних локальних/самостійно розміщених провайдерів, як-от Ollama, перед підвищенням тайм-ауту всього середовища виконання агента. +- Час виконання агента: типове значення `agents.defaults.timeoutSeconds` — 172800 с (48 годин); застосовується таймером переривання в `runEmbeddedPiAgent`. +- Час виконання Cron: ізольований агентний хід `timeoutSeconds` належить cron. Планувальник запускає цей таймер, коли починається виконання, перериває базовий запуск у налаштований дедлайн, а потім виконує обмежене очищення перед записом тайм-ауту, щоб застарілий дочірній сеанс не міг утримувати доріжку заблокованою. +- Діагностика активності сеансу: коли діагностику ввімкнено, `diagnostics.stuckSessionWarnMs` класифікує довгі сеанси `processing`, які не мають спостережуваної відповіді, інструмента, статусу, блока або прогресу ACP. Активні вбудовані запуски, виклики моделі та виклики інструментів повідомляються як `session.long_running`; активна робота без нещодавнього прогресу повідомляється як `session.stalled`; `session.stuck` зарезервовано для застарілого обліку сеансів без активної роботи, і лише цей шлях звільняє відповідну доріжку сеансу, щоб робота запуску в черзі могла продовжитися. Повторні діагностики `session.stuck` відступають, доки сеанс залишається незмінним. +- Тайм-аут простою моделі: OpenClaw перериває запит до моделі, коли до завершення вікна простою не надходять фрагменти відповіді. `models.providers..timeoutSeconds` розширює цей idle watchdog для повільних local/self-hosted провайдерів; інакше OpenClaw використовує `agents.defaults.timeoutSeconds`, коли його налаштовано, з типовим обмеженням 120 с. Запуски, викликані Cron, без явного тайм-ауту моделі або агента вимикають idle watchdog і покладаються на зовнішній тайм-аут cron. +- Тайм-аут HTTP-запиту провайдера: `models.providers..timeoutSeconds` застосовується до HTTP fetch-ів моделі цього провайдера, включно з підключенням, заголовками, тілом, тайм-аутом SDK-запиту, загальною обробкою переривання guarded-fetch і idle watchdog потоку моделі. Використовуйте це для повільних local/self-hosted провайдерів, як-от Ollama, перед підвищенням тайм-ауту всього часу виконання агента. ## Де все може завершитися раніше - Тайм-аут агента (переривання) - AbortSignal (скасування) -- Від’єднання Gateway або тайм-аут RPC +- Відключення Gateway або тайм-аут RPC - Тайм-аут `agent.wait` (лише очікування, не зупиняє агента) ## Пов’язане - [Інструменти](/uk/tools) — доступні інструменти агента -- [Хуки](/uk/automation/hooks) — подієво-орієнтовані скрипти, які запускаються подіями життєвого циклу агента -- [Compaction](/uk/concepts/compaction) — як узагальнюються довгі розмови -- [Погодження Exec](/uk/tools/exec-approvals) — ворота погодження для команд оболонки -- [Мислення](/uk/tools/thinking) — налаштування рівня мислення/міркування +- [Хуки](/uk/automation/hooks) — скрипти, керовані подіями, які запускаються подіями життєвого циклу агента +- [Compaction](/uk/concepts/compaction) — як підсумовуються довгі розмови +- [Схвалення Exec](/uk/tools/exec-approvals) — шлюзи схвалення для shell-команд +- [Thinking](/uk/tools/thinking) — конфігурація рівня thinking/reasoning diff --git a/docs/uk/reference/session-management-compaction.md b/docs/uk/reference/session-management-compaction.md index 65ebda390..03c096722 100644 --- a/docs/uk/reference/session-management-compaction.md +++ b/docs/uk/reference/session-management-compaction.md @@ -1,30 +1,30 @@ --- read_when: - - Потрібно налагодити ідентифікатори сесій, JSONL стенограми або поля sessions.json - - Ви змінюєте поведінку автокомпакції або додаєте службове обслуговування «перед компакцією» + - Потрібно налагодити ідентифікатори сеансів, JSONL транскриптів або поля sessions.json + - Ви змінюєте поведінку автоматичної Compaction або додаєте підготовче обслуговування перед Compaction - Ви хочете реалізувати скидання пам’яті або тихі системні ходи -summary: 'Поглиблений огляд: сховище сесій + транскрипти, життєвий цикл і внутрішні механізми (авто)Compaction' -title: Поглиблений розгляд керування сеансами +summary: 'Глибокий розбір: сховище сеансів + транскрипти, життєвий цикл і внутрішні механізми (авто)Compaction' +title: Поглиблений огляд керування сеансами x-i18n: - generated_at: "2026-05-02T12:45:11Z" + generated_at: "2026-05-02T13:59:33Z" model: gpt-5.5 provider: openai - source_hash: 8038d42c1112172ebdfefdd7d42d5c729a975095e2d695f5d5122b21a2fa93c1 + source_hash: 8271d7b0786e1c47a8cec6e7bd73c3c86a433d629e17937fdd87fa756ed78d73 source_path: reference/session-management-compaction.md workflow: 16 --- -OpenClaw керує сеансами від початку до кінця в таких сферах: +OpenClaw керує сеансами від початку до кінця в таких областях: -- **Маршрутизація сеансів** (як вхідні повідомлення зіставляються із `sessionKey`) +- **Маршрутизація сеансів** (як вхідні повідомлення зіставляються з `sessionKey`) - **Сховище сеансів** (`sessions.json`) і те, що воно відстежує -- **Збереження транскриптів** (`*.jsonl`) і їхня структура -- **Гігієна транскриптів** (специфічні для провайдерів виправлення перед запусками) -- **Ліміти контексту** (вікно контексту проти відстежуваних токенів) -- **Compaction** (ручна й автоматична Compaction) і де підключати роботу перед Compaction -- **Тихе службове обслуговування** (записи пам’яті, які не мають створювати видимий для користувача вивід) +- **Збереження транскриптів** (`*.jsonl`) та їхня структура +- **Гігієна транскриптів** (специфічні для провайдера виправлення перед запусками) +- **Обмеження контексту** (контекстне вікно проти відстежуваних токенів) +- **Compaction** (ручна та автоматична Compaction) і де під’єднувати роботу перед Compaction +- **Тихе обслуговування** (записи в пам’ять, які не мають створювати видимий для користувача вивід) -Якщо спершу потрібен огляд вищого рівня, почніть із: +Якщо спершу потрібен загальніший огляд, почніть із: - [Керування сеансами](/uk/concepts/session) - [Compaction](/uk/concepts/compaction) @@ -40,32 +40,32 @@ OpenClaw керує сеансами від початку до кінця в т OpenClaw спроєктовано навколо єдиного **процесу Gateway**, який володіє станом сеансів. - UI (застосунок macOS, веб Control UI, TUI) мають запитувати в Gateway списки сеансів і кількість токенів. -- У віддаленому режимі файли сеансів розташовані на віддаленому хості; “перевірка ваших локальних файлів Mac” не відображатиме того, що використовує Gateway. +- У віддаленому режимі файли сеансів розміщені на віддаленому хості; «перевірка файлів на локальному Mac» не відображатиме того, що використовує Gateway. --- -## Два шари збереження +## Два рівні збереження -OpenClaw зберігає сеанси у двох шарах: +OpenClaw зберігає сеанси на двох рівнях: 1. **Сховище сеансів (`sessions.json`)** - - Мапа ключ/значення: `sessionKey -> SessionEntry` + - Карта ключ/значення: `sessionKey -> SessionEntry` - Невелике, змінюване, безпечне для редагування (або видалення записів) - - Відстежує метадані сеансу (поточний ідентифікатор сеансу, остання активність, перемикачі, лічильники токенів тощо) + - Відстежує метадані сеансу (поточний id сеансу, остання активність, перемикачі, лічильники токенів тощо) 2. **Транскрипт (`.jsonl`)** - - Транскрипт лише для дописування з деревоподібною структурою (записи мають `id` + `parentId`) - - Зберігає власне розмову + виклики інструментів + підсумки Compaction + - Транскрипт лише з додаванням, зі структурою дерева (записи мають `id` + `parentId`) + - Зберігає фактичну розмову + виклики інструментів + підсумки Compaction - Використовується для відновлення контексту моделі для майбутніх ходів - Великі налагоджувальні контрольні точки перед Compaction пропускаються, щойно активний - транскрипт перевищує обмеження розміру контрольної точки, що запобігає створенню другої гігантської + транскрипт перевищує ліміт розміру контрольної точки, щоб уникнути другої гігантської копії `.checkpoint.*.jsonl`. -Зчитувачі історії Gateway мають уникати матеріалізації всього транскрипта, якщо -поверхні явно не потрібен довільний історичний доступ. Історія першої сторінки, -вбудована історія чату, відновлення після перезапуску та перевірки токенів/використання застосовують обмежене читання хвоста. -Повні сканування транскрипта проходять через асинхронний індекс транскриптів, який -кешується за шляхом файлу плюс `mtimeMs`/`size` і спільно використовується одночасними читачами. +Зчитувачі історії Gateway мають уникати матеріалізації всього транскрипту, якщо +поверхні явно не потрібен довільний доступ до історії. Історія першої сторінки, +вбудована історія чату, відновлення після перезапуску та перевірки токенів/використання використовують обмежене читання хвоста. +Повні сканування транскрипту проходять через асинхронний індекс транскриптів, який +кешується за шляхом до файлу плюс `mtimeMs`/`size` і спільно використовується одночасними зчитувачами. --- @@ -86,26 +86,31 @@ OpenClaw визначає ці шляхи через `src/config/sessions.ts`. Збереження сеансів має автоматичні засоби обслуговування (`session.maintenance`) для `sessions.json`, артефактів транскриптів і допоміжних файлів траєкторій: - `mode`: `warn` (типово) або `enforce` -- `pruneAfter`: поріг віку застарілого запису (типово `30d`) +- `pruneAfter`: граничний вік застарілих записів (типово `30d`) - `maxEntries`: ліміт записів у `sessions.json` (типово `500`) -- `resetArchiveRetention`: термін зберігання архівів транскриптів `*.reset.` (типово: такий самий, як `pruneAfter`; `false` вимикає очищення) +- `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.` (типово: такий самий, як `pruneAfter`; `false` вимикає очищення) - `maxDiskBytes`: необов’язковий бюджет каталогу сеансів - `highWaterBytes`: необов’язкова ціль після очищення (типово `80%` від `maxDiskBytes`) -Звичайні записи Gateway проходять через окремий для кожного сховища writer сеансів, який серіалізує внутрішньопроцесні мутації без runtime-блокування файлу. Помічники виправлень на гарячому шляху позичають перевірений змінюваний кеш, поки утримують цей слот writer, тож великі файли `sessions.json` не клонуються і не перечитуються для кожного оновлення метаданих. Runtime-код має віддавати перевагу `updateSessionStore(...)` або `updateSessionStoreEntry(...)`; прямі збереження всього сховища є інструментами сумісності й офлайн-обслуговування. Коли Gateway доступний, `openclaw sessions cleanup` без `--dry-run` і `openclaw agents delete` делегують мутації сховища Gateway, щоб очищення приєднувалося до тієї самої черги writer; `--store ` є явним офлайн-шляхом ремонту для прямого обслуговування файлів. Очищення `maxEntries` усе ще пакетне для production-лімітів, тому сховище може короткочасно перевищувати налаштований ліміт, перш ніж наступне очищення high-water перепише його донизу. Читання сховища сеансів не обрізають і не лімітують записи під час запуску Gateway; для очищення використовуйте записи або `openclaw sessions cleanup --enforce`. `openclaw sessions cleanup --enforce` усе одно негайно застосовує налаштований ліміт. +Звичайні записи Gateway проходять через окремий для сховища записувач сеансів, який серіалізує внутрішньопроцесні мутації без використання файлового блокування під час виконання. Допоміжні засоби швидкого шляху для латок позичають перевірений змінюваний кеш, поки утримують слот цього записувача, тому великі файли `sessions.json` не клонуються й не перечитуються для кожного оновлення метаданих. Код виконання має віддавати перевагу `updateSessionStore(...)` або `updateSessionStoreEntry(...)`; прямі збереження всього сховища є інструментами сумісності та офлайн-обслуговування. Коли Gateway доступний, не пробні `openclaw sessions cleanup` і `openclaw agents delete` делегують мутації сховища Gateway, щоб очищення приєднувалося до тієї самої черги записувача; `--store ` є явним офлайн-шляхом ремонту для прямого обслуговування файлів. Очищення `maxEntries` усе ще виконується пакетами для production-лімітів, тому сховище може короткочасно перевищувати налаштований ліміт, перш ніж наступне очищення до верхнього порогу перепише його до меншого розміру. Читання сховища сеансів не обрізає і не обмежує записи під час запуску Gateway; для очищення використовуйте записи або `openclaw sessions cleanup --enforce`. `openclaw sessions cleanup --enforce` усе ще застосовує налаштований ліміт негайно. Обслуговування зберігає довговічні зовнішні вказівники розмов, як-от групові сеанси -та сеанси чатів у межах тредів, але синтетичні runtime-записи для Cron, hooks, +та сеанси чату в межах потоків, але синтетичні runtime-записи для Cron, хуків, Heartbeat, ACP і субагентів усе ще можуть бути видалені, коли вони перевищують -налаштований вік, кількість або дисковий бюджет. +налаштований вік, кількість або бюджет диска. OpenClaw більше не створює автоматичні ротаційні резервні копії `sessions.json.bak.*` під час записів Gateway. Застарілий ключ `session.maintenance.rotateBytes` ігнорується, а `openclaw doctor --fix` видаляє його зі старіших конфігурацій. -Порядок застосування очищення дискового бюджету (`mode: "enforce"`): +Мутації транскриптів використовують блокування запису сеансу на файлі транскрипту. Очікування отримання блокування триває до +`session.writeLock.acquireTimeoutMs`, перш ніж буде показано помилку зайнятого сеансу; типове значення — `60000` +мс. Підвищуйте його лише тоді, коли легітимна підготовка, очищення, Compaction або робота дзеркала транскриптів +довше конкурують на повільних машинах. Виявлення застарілих блокувань і попередження про максимальний час утримання залишаються окремими політиками. -1. Спершу видаліть найстаріші заархівовані артефакти, осиротілі транскрипти або осиротілі артефакти траєкторій. -2. Якщо використання все ще перевищує ціль, витісніть найстаріші записи сеансів та їхні файли транскриптів/траєкторій. -3. Продовжуйте, доки використання не стане не більшим за `highWaterBytes`. +Порядок застосування очищення бюджету диска (`mode: "enforce"`): + +1. Спочатку видаляти найстаріші архівовані, осиротілі транскриптні або осиротілі траєкторні артефакти. +2. Якщо все ще вище за ціль, витісняти найстаріші записи сеансів та їхні файли транскриптів/траєкторій. +3. Продовжувати, доки використання не стане на рівні `highWaterBytes` або нижче. У `mode: "warn"` OpenClaw повідомляє про потенційні витіснення, але не змінює сховище/файли. @@ -120,28 +125,28 @@ openclaw sessions cleanup --enforce ## Сеанси Cron і журнали запусків -Ізольовані запуски Cron також створюють записи сеансів/транскрипти та мають окремі засоби керування зберіганням: +Ізольовані запуски Cron також створюють записи сеансів/транскрипти, і для них є окремі засоби керування зберіганням: - `cron.sessionRetention` (типово `24h`) обрізає старі ізольовані сеанси запусків Cron зі сховища сеансів (`false` вимикає). - `cron.runLog.maxBytes` + `cron.runLog.keepLines` обрізають файли `~/.openclaw/cron/runs/.jsonl` (типово: `2_000_000` байтів і `2000` рядків). Коли Cron примусово створює новий ізольований сеанс запуску, він очищає попередній запис сеансу `cron:` перед записом нового рядка. Він переносить безпечні -налаштування, як-от параметри thinking/fast/verbose, мітки та явні +налаштування, як-от параметри thinking/fast/verbose, мітки та явно вибрані користувачем перевизначення моделі/auth. Він відкидає навколишній контекст розмови, як-от -маршрутизацію каналу/групи, політику надсилання або черги, elevation, origin і runtime-прив’язку ACP, -щоб свіжий ізольований запуск не міг успадкувати застарілу доставку або +маршрутизацію channel/group, політику надсилання або черги, підвищення прав, походження та +runtime-прив’язку ACP, щоб свіжий ізольований запуск не міг успадкувати застарілу доставку або runtime-повноваження зі старішого запуску. --- ## Ключі сеансів (`sessionKey`) -`sessionKey` визначає, _у якому контейнері розмови_ ви перебуваєте (маршрутизація + ізоляція). +`sessionKey` визначає, у _якому кошику розмови_ ви перебуваєте (маршрутизація + ізоляція). Поширені шаблони: -- Основний/прямий чат (на агента): `agent::` (типово `main`) +- Основний/прямий чат (для кожного агента): `agent::` (типово `main`) - Група: `agent:::group:` - Кімната/канал (Discord/Slack): `agent:::channel:` або `...:room:` - Cron: `cron:` @@ -153,15 +158,15 @@ runtime-повноваження зі старішого запуску. ## Ідентифікатори сеансів (`sessionId`) -Кожен `sessionKey` вказує на поточний `sessionId` (файл транскрипта, який продовжує розмову). +Кожен `sessionKey` вказує на поточний `sessionId` (файл транскрипту, який продовжує розмову). Практичні правила: - **Скидання** (`/new`, `/reset`) створює новий `sessionId` для цього `sessionKey`. -- **Щоденне скидання** (типово о 4:00 AM за локальним часом на хості gateway) створює новий `sessionId` під час наступного повідомлення після межі скидання. -- **Завершення через бездіяльність** (`session.reset.idleMinutes` або застаріле `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна бездіяльності. Коли налаштовано і щоденне скидання, і бездіяльність, спрацьовує те, що настане першим. -- **Системні події** (Heartbeat, пробудження Cron, сповіщення exec, службовий облік gateway) можуть змінювати рядок сеансу, але не продовжують свіжість щоденного/idle-скидання. Перехід скидання відкидає поставлені в чергу сповіщення системних подій для попереднього сеансу перед побудовою свіжого prompt. -- **Політика fork батьківського сеансу** використовує активну гілку PI під час створення треду або fork субагента. Якщо ця гілка завелика, OpenClaw запускає дочірній сеанс з ізольованим контекстом замість помилки або успадкування непридатної історії. Політика визначення розміру автоматична; застаріла конфігурація `session.parentForkMaxTokens` видаляється `openclaw doctor --fix`. +- **Щоденне скидання** (типово 4:00 AM за локальним часом на хості gateway) створює новий `sessionId` у наступному повідомленні після межі скидання. +- **Завершення через бездіяльність** (`session.reset.idleMinutes` або застарілий `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна бездіяльності. Коли налаштовано і щоденне, і idle-скидання, спрацьовує те, яке завершиться першим. +- **Системні події** (Heartbeat, пробудження Cron, сповіщення exec, службові операції gateway) можуть змінювати рядок сеансу, але не подовжують свіжість щоденного/idle-скидання. Перехід скидання відкидає поставлені в чергу повідомлення системних подій для попереднього сеансу перед побудовою свіжого prompt. +- **Політика батьківського fork** використовує активну гілку Pi під час створення потоку або fork субагента. Якщо ця гілка завелика, OpenClaw запускає дочірній елемент з ізольованим контекстом замість того, щоб завершитись помилкою або успадкувати непридатну історію. Політика розміру автоматична; застарілу конфігурацію `session.parentForkMaxTokens` видаляє `openclaw doctor --fix`. Деталь реалізації: рішення ухвалюється в `initSessionState()` у `src/auto-reply/reply/session.ts`. @@ -171,36 +176,36 @@ runtime-повноваження зі старішого запуску. Тип значення сховища — `SessionEntry` у `src/config/sessions.ts`. -Ключові поля (список не вичерпний): +Ключові поля (не вичерпно): -- `sessionId`: поточний ідентифікатор транскрипта (ім’я файлу походить від нього, якщо `sessionFile` не задано) -- `sessionStartedAt`: часова мітка початку поточного `sessionId`; свіжість щоденного скидання - використовує її. Застарілі рядки можуть виводити її із заголовка сеансу JSONL. -- `lastInteractionAt`: часова мітка останньої реальної взаємодії користувача/каналу; свіжість idle-скидання - використовує її, щоб Heartbeat, Cron і exec-події не підтримували сеанси +- `sessionId`: поточний id транскрипту (ім’я файлу виводиться з нього, якщо не задано `sessionFile`) +- `sessionStartedAt`: часова мітка початку поточного `sessionId`; це використовується для + свіжості щоденного скидання. Застарілі рядки можуть виводити її із заголовка сеансу JSONL. +- `lastInteractionAt`: часова мітка останньої реальної взаємодії користувача/каналу; це використовується для + свіжості idle-скидання, щоб Heartbeat, Cron і події exec не підтримували сеанси активними. Застарілі рядки без цього поля повертаються до відновленого часу початку сеансу - для idle-свіжості. + для свіжості idle. - `updatedAt`: часова мітка останньої мутації рядка сховища, використовується для списків, обрізання та службового обліку. Вона не є авторитетним джерелом для свіжості щоденного/idle-скидання. -- `sessionFile`: необов’язкове явне перевизначення шляху транскрипта -- `chatType`: `direct | group | room` (допомагає UI і політиці надсилання) -- `provider`, `subject`, `room`, `space`, `displayName`: метадані для маркування групи/каналу +- `sessionFile`: необов’язкове явне перевизначення шляху до транскрипту +- `chatType`: `direct | group | room` (допомагає UI та політиці надсилання) +- `provider`, `subject`, `room`, `space`, `displayName`: метадані для позначення груп/каналів - Перемикачі: - `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel` - `sendPolicy` (перевизначення для окремого сеансу) - Вибір моделі: - `providerOverride`, `modelOverride`, `authProfileOverride` -- Лічильники токенів (best-effort / залежно від провайдера): +- Лічильники токенів (найкращі зусилля / залежить від провайдера): - `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens` -- `compactionCount`: скільки разів auto-compaction завершувалася для цього ключа сеансу +- `compactionCount`: як часто автоматична Compaction завершувалася для цього ключа сеансу - `memoryFlushAt`: часова мітка останнього скидання пам’яті перед Compaction -- `memoryFlushCompactionCount`: кількість Compaction на момент останнього скидання +- `memoryFlushCompactionCount`: кількість Compaction, коли востаннє виконувався flush -Сховище безпечно редагувати, але Gateway є авторитетним джерелом: він може переписувати або повторно гідратувати записи під час роботи сеансів. +Сховище безпечно редагувати, але Gateway є авторитетним джерелом: він може переписувати або регідратувати записи під час виконання сеансів. --- -## Структура транскрипта (`*.jsonl`) +## Структура транскрипту (`*.jsonl`) Транскриптами керує `SessionManager` із `@mariozechner/pi-coding-agent`. @@ -211,27 +216,27 @@ runtime-повноваження зі старішого запуску. Важливі типи записів: -- `message`: повідомлення користувача/асистента/toolResult -- `custom_message`: повідомлення, вставлені розширенням, які _потрапляють_ у контекст моделі (можуть бути приховані з UI) -- `custom`: стан розширення, який _не потрапляє_ в контекст моделі +- `message`: повідомлення user/assistant/toolResult +- `custom_message`: повідомлення, ін’єктовані розширенням, які _входять_ у контекст моделі (можуть бути приховані з UI) +- `custom`: стан розширення, який _не входить_ у контекст моделі - `compaction`: збережений підсумок Compaction з `firstKeptEntryId` і `tokensBefore` - `branch_summary`: збережений підсумок під час навігації гілкою дерева -OpenClaw навмисно **не** “виправляє” транскрипти; Gateway використовує `SessionManager` для їх читання/запису. +OpenClaw навмисно **не** «виправляє» транскрипти; Gateway використовує `SessionManager` для їх читання/запису. --- -## Вікна контексту проти відстежуваних токенів +## Контекстні вікна проти відстежуваних токенів -Мають значення два різні поняття: +Важливі дві різні концепції: -1. **Вікно контексту моделі**: жорсткий ліміт для кожної моделі (токени, видимі моделі) -2. **Лічильники сховища сеансів**: ковзні статистики, записані в `sessions.json` (використовуються для /status і dashboard) +1. **Контекстне вікно моделі**: жорсткий ліміт для кожної моделі (токени, видимі моделі) +2. **Лічильники сховища сеансів**: ковзні статистики, записані в `sessions.json` (використовуються для /status і панелей) Якщо ви налаштовуєте ліміти: -- Вікно контексту береться з каталогу моделей (і може бути перевизначене через конфігурацію). -- `contextTokens` у сховищі — runtime-оцінка/звітне значення; не сприймайте його як сувору гарантію. +- Контекстне вікно надходить із каталогу моделей (і може бути перевизначене через конфігурацію). +- `contextTokens` у сховищі — це runtime-оцінка/звітне значення; не сприймайте його як сувору гарантію. Докладніше див. [/token-use](/uk/reference/token-use). @@ -239,7 +244,7 @@ OpenClaw навмисно **не** “виправляє” транскрипт ## Compaction: що це таке -Compaction підсумовує старішу розмову в збережений запис `compaction` у транскрипті та залишає останні повідомлення незмінними. +Compaction підсумовує старішу розмову в збережений запис `compaction` у транскрипті й залишає останні повідомлення без змін. Після Compaction майбутні ходи бачать: @@ -248,17 +253,17 @@ Compaction підсумовує старішу розмову в збереже Compaction є **постійною** (на відміну від обрізання сеансів). Див. [/concepts/session-pruning](/uk/concepts/session-pruning). -## Межі фрагментів Compaction і парування інструментів +## Межі фрагментів Compaction і поєднання інструментів -Коли OpenClaw розбиває довгий транскрипт на фрагменти Compaction, він зберігає -виклики інструментів асистента в парі з відповідними записами `toolResult`. +Коли OpenClaw розбиває довгий transcript на фрагменти Compaction, він зберігає +виклики інструментів assistant у парі з відповідними записами `toolResult`. -- Якщо межа поділу за часткою токенів припадає між викликом інструмента та його результатом, OpenClaw - зсуває межу до повідомлення асистента з викликом інструмента, замість того щоб розділяти +- Якщо поділ за часткою токенів потрапляє між викликом інструмента та його результатом, OpenClaw + зміщує межу до повідомлення assistant з викликом інструмента, замість того щоб розділяти пару. - Якщо кінцевий блок результату інструмента інакше перевищив би цільовий розмір фрагмента, - OpenClaw зберігає цей очікуваний блок інструмента й залишає нескорочений хвіст - без змін. + OpenClaw зберігає цей очікуваний блок інструмента й залишає неузагальнений хвіст + недоторканим. - Перервані блоки викликів інструментів або блоки з помилками не утримують очікуваний поділ відкритим. --- @@ -271,7 +276,7 @@ Compaction є **постійною** (на відміну від обрізан (`request_too_large`, `context length exceeded`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model`, `ollama error: context length -exceeded` та подібні варіанти, сформовані провайдером) → стиснення → повторна спроба. +exceeded` та подібні варіанти, сформовані провайдерами) → compact → повторна спроба. 2. **Підтримання порога**: після успішного ходу, коли: `contextTokens > contextWindow - reserveTokens` @@ -281,34 +286,34 @@ exceeded` та подібні варіанти, сформовані прова - `contextWindow` — контекстне вікно моделі - `reserveTokens` — запас, зарезервований для промптів + наступного виводу моделі -Це семантика середовища виконання Pi (OpenClaw споживає події, але Pi вирішує, коли стискати). +Це семантика середовища виконання Pi (OpenClaw споживає події, але Pi вирішує, коли виконувати compact). OpenClaw також може запускати попередню локальну Compaction перед відкриттям наступного запуску, коли задано `agents.defaults.compaction.maxActiveTranscriptBytes` і -активний файл транскрипту досягає цього розміру. Це захист за розміром файлу для локальної +активний файл transcript досягає цього розміру. Це запобіжник за розміром файлу для локальної вартості повторного відкриття, а не необроблене архівування: OpenClaw усе одно виконує звичайну семантичну Compaction, і для цього потрібен `truncateAfterCompaction`, щоб стиснутий підсумок міг стати -новим наступним транскриптом. +новим наступним transcript. -Для вбудованих запусків Pi параметр `agents.defaults.compaction.midTurnPrecheck.enabled: true` -додає опціональний захист циклу інструментів. Після додавання результату інструмента й перед -наступним викликом моделі OpenClaw оцінює тиск на промпт, використовуючи ту саму логіку попереднього -бюджету, що й на початку ходу. Якщо контекст більше не вміщується, захист -не стискає всередині хуку `transformContext` Pi. Він створює структурований -сигнал попередньої перевірки посеред ходу, зупиняє поточне надсилання промпта й дає -зовнішньому циклу запуску використати наявний шлях відновлення: скоротити завеликі результати інструментів, -коли цього достатньо, або запустити налаштований режим Compaction і повторити спробу. Цей -параметр вимкнено за замовчуванням, і він працює як з режимом Compaction `default`, так і з `safeguard`, -зокрема з Compaction із захистом на базі провайдера. -Це не залежить від `maxActiveTranscriptBytes`: захист за розміром у байтах виконується -перед відкриттям ходу, тоді як попередня перевірка посеред ходу виконується пізніше у вбудованому циклі інструментів Pi +Для вбудованих запусків Pi `agents.defaults.compaction.midTurnPrecheck.enabled: true` +додає опціональний запобіжник циклу інструментів. Після додавання результату інструмента й перед +наступним викликом моделі OpenClaw оцінює тиск на промпт, використовуючи ту саму логіку бюджету +попередньої перевірки, що й на початку ходу. Якщо контекст більше не вміщується, запобіжник +не виконує compact усередині хука Pi `transformContext`. Він піднімає структурований +сигнал попередньої перевірки посеред ходу, зупиняє поточне подання промпта й дає +зовнішньому циклу запуску використати наявний шлях відновлення: обрізати завеликі результати інструментів, +коли цього достатньо, або запустити налаштований режим Compaction і повторити спробу. Опцію +вимкнено за замовчуванням, і вона працює як з режимом Compaction `default`, так і з `safeguard`, +зокрема з Compaction `safeguard`, підтриманою провайдером. +Це не залежить від `maxActiveTranscriptBytes`: запобіжник за розміром у байтах працює +перед відкриттям ходу, тоді як попередня перевірка посеред ходу працює пізніше у вбудованому циклі інструментів Pi після додавання нових результатів інструментів. --- ## Налаштування Compaction (`reserveTokens`, `keepRecentTokens`) -Налаштування Compaction Pi містяться в налаштуваннях Pi: +Налаштування Compaction Pi зберігаються в налаштуваннях Pi: ```json5 { @@ -320,52 +325,52 @@ OpenClaw також може запускати попередню локаль } ``` -OpenClaw також забезпечує нижню межу безпеки для вбудованих запусків: +OpenClaw також застосовує мінімальний рівень безпеки для вбудованих запусків: -- Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw підвищує це значення. -- Типова нижня межа — `20000` токенів. -- Установіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути нижню межу. +- Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw підвищує його. +- Стандартний мінімум — `20000` токенів. +- Установіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути мінімум. - Якщо значення вже вище, OpenClaw залишає його без змін. -- Ручна команда `/compact` враховує явне значення `agents.defaults.compaction.keepRecentTokens` - і зберігає точку відсікання недавнього хвоста Pi. Без явного бюджету збереження - ручна Compaction залишається жорсткою контрольною точкою, а перебудований контекст починається з +- Ручний `/compact` враховує явний `agents.defaults.compaction.keepRecentTokens` + і зберігає точку відсікання нещодавнього хвоста Pi. Без явного бюджету збереження + ручна Compaction лишається жорсткою контрольною точкою, а перебудований контекст починається з нового підсумку. -- Установіть `agents.defaults.compaction.midTurnPrecheck.enabled: true`, щоб виконувати +- Установіть `agents.defaults.compaction.midTurnPrecheck.enabled: true`, щоб запускати опціональну попередню перевірку циклу інструментів після нових результатів інструментів і перед наступним викликом - моделі. Це лише тригер; створення підсумку все одно використовує налаштований + моделі. Це лише тригер; генерація підсумку все одно використовує налаштований шлях Compaction. Це не залежить від `maxActiveTranscriptBytes`, який є - захистом за розміром активного транскрипту в байтах на початку ходу. -- Установіть `agents.defaults.compaction.maxActiveTranscriptBytes` у байтове значення або - рядок, наприклад `"20mb"`, щоб виконувати локальну Compaction перед ходом, коли активний - транскрипт стає великим. Цей захист активний лише коли - також увімкнено `truncateAfterCompaction`. Залиште це незаданим або встановіть `0`, щоб + запобіжником за розміром активного transcript у байтах на початку ходу. +- Установіть `agents.defaults.compaction.maxActiveTranscriptBytes` у значення байтів або + рядок на кшталт `"20mb"`, щоб запускати локальну Compaction перед ходом, коли активний + transcript стає великим. Цей запобіжник активний лише тоді, коли + також увімкнено `truncateAfterCompaction`. Залиште його невстановленим або задайте `0`, щоб вимкнути. - Коли ввімкнено `agents.defaults.compaction.truncateAfterCompaction`, - OpenClaw після Compaction ротує активний транскрипт у стиснутий наступний JSONL. - Старий повний транскрипт залишається заархівованим і пов’язаним із - контрольною точкою Compaction замість перезапису на місці. + OpenClaw переносить активний transcript у стиснутий наступний JSONL після + Compaction. Старий повний transcript лишається заархівованим і пов’язаним із + контрольною точкою Compaction, замість того щоб перезаписуватися на місці. -Навіщо: залишити достатній запас для багатокрокового “обслуговування” (наприклад, записів пам’яті), перш ніж Compaction стане неминучою. +Чому: залишити достатньо запасу для багатокрокового «обслуговування» (наприклад, записів пам’яті), перш ніж Compaction стане неминучою. Реалізація: `ensurePiCompactionReserveTokens()` у `src/agents/pi-settings.ts` (викликається з `src/agents/pi-embedded-runner.ts`). --- -## Підключні провайдери Compaction +## Підключувані провайдери Compaction -Plugins можуть зареєструвати провайдера Compaction через `registerCompactionProvider()` в API Plugin. Коли `agents.defaults.compaction.provider` задано як id зареєстрованого провайдера, розширення safeguard делегує підсумовування цьому провайдеру замість вбудованого конвеєра `summarizeInStages`. +Plugin-и можуть реєструвати провайдера Compaction через `registerCompactionProvider()` в API Plugin. Коли `agents.defaults.compaction.provider` задано як id зареєстрованого провайдера, розширення safeguard делегує узагальнення цьому провайдеру замість вбудованого конвеєра `summarizeInStages`. -- `provider`: id зареєстрованого Plugin-провайдера Compaction. Не задавайте для типового підсумовування LLM. -- Задання `provider` примусово вмикає `mode: "safeguard"`. +- `provider`: id зареєстрованого Plugin провайдера Compaction. Залиште незаданим для стандартного LLM-узагальнення. +- Установлення `provider` примусово вмикає `mode: "safeguard"`. - Провайдери отримують ті самі інструкції Compaction і політику збереження ідентифікаторів, що й вбудований шлях. -- Safeguard усе одно зберігає контекст недавнього ходу й суфікса розділеного ходу після виводу провайдера. -- Вбудоване підсумовування safeguard повторно дистилює попередні підсумки з новими повідомленнями - замість дослівного збереження повного попереднього підсумку. -- Режим safeguard типово вмикає аудити якості підсумку; установіть - `qualityGuard.enabled: false`, щоб пропустити поведінку повторної спроби при неправильно сформованому виводі. -- Якщо провайдер зазнає невдачі або повертає порожній результат, OpenClaw автоматично повертається до вбудованого підсумовування LLM. -- Сигнали переривання/тайм-ауту повторно викидаються (не поглинаються), щоб поважати скасування викликачем. +- Safeguard усе одно зберігає контекст суфікса нещодавнього ходу та розділеного ходу після виводу провайдера. +- Вбудоване узагальнення safeguard повторно дистилює попередні підсумки з новими повідомленнями + замість того, щоб дослівно зберігати весь попередній підсумок. +- Режим Safeguard вмикає аудити якості підсумків за замовчуванням; задайте + `qualityGuard.enabled: false`, щоб пропустити поведінку повторної спроби в разі некоректно сформованого виводу. +- Якщо провайдер дає збій або повертає порожній результат, OpenClaw автоматично повертається до вбудованого LLM-узагальнення. +- Сигнали переривання/тайм-ауту перекидаються повторно (не поглинаються), щоб поважати скасування викликачем. Джерело: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`. @@ -373,86 +378,86 @@ Plugins можуть зареєструвати провайдера Compaction ## Поверхні, видимі користувачу -Ви можете спостерігати Compaction і стан сесії через: +Ви можете спостерігати стан Compaction і сеансу через: -- `/status` (у будь-якій чат-сесії) +- `/status` (у будь-якому чат-сеансі) - `openclaw status` (CLI) - `openclaw sessions` / `sessions --json` -- Детальний режим: `🧹 Auto-compaction complete` + кількість Compaction +- Докладний режим: `🧹 Auto-compaction complete` + кількість Compaction --- ## Тихе обслуговування (`NO_REPLY`) -OpenClaw підтримує “тихі” ходи для фонових завдань, де користувач не має бачити проміжний вивід. +OpenClaw підтримує «тихі» ходи для фонових завдань, де користувач не має бачити проміжний вивід. Угода: -- Асистент починає свій вивід із точного тихого токена `NO_REPLY` / - `no_reply`, щоб указати “не доставляти відповідь користувачу”. -- OpenClaw прибирає/пригнічує це на рівні доставки. -- Пригнічення точного тихого токена не залежить від регістру, тому `NO_REPLY` і - `no_reply` обидва враховуються, коли весь payload складається лише з тихого токена. +- Assistant починає свій вивід із точного тихого токена `NO_REPLY` / + `no_reply`, щоб позначити «не доставляти відповідь користувачу». +- OpenClaw видаляє/пригнічує це на рівні доставки. +- Пригнічення точного тихого токена не чутливе до регістру, тож `NO_REPLY` і + `no_reply` обидва враховуються, коли весь payload — це лише тихий токен. - Це лише для справді фонових ходів без доставки; це не скорочення для звичайних дієвих запитів користувача. -Станом на `2026.1.10`, OpenClaw також пригнічує **чернетковий/typing streaming**, коли -частковий фрагмент починається з `NO_REPLY`, тож тихі операції не просочують частковий +Починаючи з `2026.1.10`, OpenClaw також пригнічує **потокове передавання чернетки/набору тексту**, коли +частковий фрагмент починається з `NO_REPLY`, тож тихі операції не розкривають частковий вивід посеред ходу. --- -## Перед-Compaction “скидання пам’яті” (реалізовано) +## Перед-Compaction «скидання пам’яті» (реалізовано) -Мета: перед автоматичною Compaction виконати тихий агентний хід, який записує стійкий +Мета: перед автоматичною Compaction запустити тихий агентний хід, який записує довговічний стан на диск (наприклад, `memory/YYYY-MM-DD.md` у робочому просторі агента), щоб Compaction не могла стерти критичний контекст. OpenClaw використовує підхід **скидання перед порогом**: -1. Відстежувати використання контексту сесії. -2. Коли воно перетинає “м’який поріг” (нижче порога Compaction Pi), виконати тиху - директиву “запиши пам’ять зараз” для агента. -3. Використати точний тихий токен `NO_REPLY` / `no_reply`, щоб користувач - нічого не бачив. +1. Відстежувати використання контексту сеансу. +2. Коли воно перетинає «м’який поріг» (нижче порога Compaction Pi), запустити тиху + директиву «запиши пам’ять зараз» для агента. +3. Використати точний тихий токен `NO_REPLY` / `no_reply`, щоб користувач не бачив + нічого. Конфігурація (`agents.defaults.compaction.memoryFlush`): -- `enabled` (типово: `true`) +- `enabled` (за замовчуванням: `true`) - `model` (опціональне точне перевизначення провайдера/моделі для ходу скидання, наприклад `ollama/qwen3:8b`) -- `softThresholdTokens` (типово: `4000`) +- `softThresholdTokens` (за замовчуванням: `4000`) - `prompt` (повідомлення користувача для ходу скидання) - `systemPrompt` (додатковий системний промпт, доданий для ходу скидання) -Нотатки: +Примітки: -- Типові prompt/system prompt містять підказку `NO_REPLY`, щоб пригнічувати +- Стандартні prompt/system prompt містять підказку `NO_REPLY`, щоб пригнітити доставку. -- Коли задано `model`, хід скидання використовує цю модель без успадкування - ланцюга запасних варіантів активної сесії, тож локальне лише обслуговування не - переходить непомітно на платну розмовну модель. -- Скидання виконується один раз за цикл Compaction (відстежується в `sessions.json`). -- Скидання виконується лише для вбудованих сесій Pi (бекенди CLI його пропускають). -- Скидання пропускається, коли робочий простір сесії доступний лише для читання (`workspaceAccess: "ro"` або `"none"`). -- Див. [Пам’ять](/uk/concepts/memory) щодо структури файлів робочого простору й шаблонів запису. +- Коли `model` задано, хід скидання використовує цю модель без успадкування + ланцюжка fallback активного сеансу, тож локальне обслуговування не переходить непомітно + на платну розмовну модель. +- Скидання виконується один раз на цикл Compaction (відстежується в `sessions.json`). +- Скидання виконується лише для вбудованих сеансів Pi (CLI-бекенди його пропускають). +- Скидання пропускається, коли робочий простір сеансу доступний лише для читання (`workspaceAccess: "ro"` або `"none"`). +- Див. [Пам’ять](/uk/concepts/memory) щодо структури файлів робочого простору та шаблонів запису. -Pi також надає хук `session_before_compact` в API розширення, але логіка скидання OpenClaw +Pi також надає хук `session_before_compact` в API розширень, але логіка скидання OpenClaw сьогодні живе на боці Gateway. --- ## Контрольний список усунення несправностей -- Неправильний ключ сесії? Почніть із [/concepts/session](/uk/concepts/session) і підтвердьте `sessionKey` у `/status`. -- Невідповідність сховища й транскрипту? Підтвердьте хост Gateway і шлях сховища з `openclaw status`. -- Спам Compaction? Перевірте: +- Неправильний ключ сеансу? Почніть з [/concepts/session](/uk/concepts/session) і підтвердьте `sessionKey` у `/status`. +- Невідповідність сховища й transcript? Підтвердьте хост Gateway і шлях до сховища з `openclaw status`. +- Надмірні Compaction? Перевірте: - контекстне вікно моделі (занадто мале) - - налаштування Compaction (`reserveTokens` занадто велике для вікна моделі може спричинити ранішу Compaction) - - роздування результатів інструментів: увімкніть/налаштуйте обрізання сесії -- Просочуються тихі ходи? Підтвердьте, що відповідь починається з `NO_REPLY` (точний токен без урахування регістру) і що ви використовуєте збірку, яка містить виправлення пригнічення streaming. + - налаштування Compaction (`reserveTokens` занадто високий для вікна моделі може спричиняти ранішу Compaction) + - роздування результатів інструментів: увімкніть/налаштуйте обрізання сеансу +- Тихі ходи протікають? Підтвердьте, що відповідь починається з `NO_REPLY` (точний токен, нечутливий до регістру), і що ви на збірці, яка містить виправлення пригнічення streaming. ## Пов’язане -- [Керування сесіями](/uk/concepts/session) -- [Обрізання сесії](/uk/concepts/session-pruning) +- [Керування сеансами](/uk/concepts/session) +- [Обрізання сеансу](/uk/concepts/session-pruning) - [Рушій контексту](/uk/concepts/context-engine)