From c3970790cd2e69d5b96ebd18e41d3e0399063344 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 2 May 2026 06:41:28 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- .../session-management-compaction.md | 332 +++++++++--------- 1 file changed, 169 insertions(+), 163 deletions(-) diff --git a/docs/uk/reference/session-management-compaction.md b/docs/uk/reference/session-management-compaction.md index 09ccf60b2..1d3592cd2 100644 --- a/docs/uk/reference/session-management-compaction.md +++ b/docs/uk/reference/session-management-compaction.md @@ -1,28 +1,28 @@ --- read_when: - - Потрібно налагодити ідентифікатори сеансів, JSONL транскрипту або поля sessions.json - - Ви змінюєте поведінку автоматичного Compaction або додаєте підготовче обслуговування перед Compaction - - Ви хочете реалізувати скидання пам’яті або тихі системні ходи -summary: 'Поглиблений огляд: сховище сеансів + транскрипти, життєвий цикл і внутрішні механізми (авто)Compaction' + - Вам потрібно налагодити ідентифікатори сесій, JSONL транскриптів або поля sessions.json + - Ви змінюєте поведінку автоматичної Compaction або додаєте службове впорядкування перед “Compaction” + - Ви хочете реалізувати очищення пам’яті або тихі системні репліки +summary: 'Глибокий огляд: сховище сеансів + транскрипти, життєвий цикл і внутрішні механізми (авто)Compaction' title: Поглиблений огляд керування сеансами x-i18n: - generated_at: "2026-05-02T06:11:00Z" + generated_at: "2026-05-02T06:40:11Z" model: gpt-5.5 provider: openai - source_hash: fb2df70fb8c70f8ba8236165d9f5455b292e8a6d01d3bbfcafdd14d193df718e + source_hash: b9ca8a35210625051f5051e90a18a005d6103bc1d65d356c34f818d2bfc0058c source_path: reference/session-management-compaction.md workflow: 16 --- -OpenClaw керує сесіями наскрізно в цих областях: +OpenClaw керує сесіями від початку до кінця в таких сферах: - **Маршрутизація сесій** (як вхідні повідомлення зіставляються з `sessionKey`) -- **Сховище сесій** (`sessions.json`) і те, що воно відстежує -- **Збереження транскриптів** (`*.jsonl`) і їхня структура -- **Гігієна транскриптів** (виправлення, специфічні для провайдера, перед запусками) -- **Обмеження контексту** (контекстне вікно порівняно з відстежуваними токенами) -- **Compaction** (ручна й автоматична Compaction) і де під’єднувати роботу перед Compaction -- **Тихе обслуговування** (записи пам’яті, які не мають створювати видимий для користувача вивід) +- **Сховище сесій** (`sessions.json`) і що воно відстежує +- **Збереження транскриптів** (`*.jsonl`) та їхня структура +- **Гігієна транскриптів** (специфічні для провайдера виправлення перед запусками) +- **Обмеження контексту** (контекстне вікно проти відстежуваних токенів) +- **Compaction** (ручний і автоматичний Compaction) і де підключати роботу перед Compaction +- **Тихе обслуговування** (записи в пам’ять, які не мають створювати видимий для користувача вивід) Якщо спершу потрібен огляд вищого рівня, почніть із: @@ -37,30 +37,36 @@ OpenClaw керує сесіями наскрізно в цих областях ## Джерело істини: Gateway -OpenClaw спроєктовано навколо єдиного **процесу Gateway**, який володіє станом сесій. +OpenClaw спроєктовано навколо одного **процесу Gateway**, який володіє станом сесій. -- UI (застосунок macOS, веб Control UI, TUI) мають запитувати в Gateway списки сесій і кількість токенів. -- У віддаленому режимі файли сесій розташовані на віддаленому хості; “перевірка локальних файлів на Mac” не відобразить те, що використовує Gateway. +- Інтерфейси користувача (застосунок macOS, веб Control UI, TUI) мають запитувати Gateway для списків сесій і кількості токенів. +- У віддаленому режимі файли сесій розташовані на віддаленому хості; «перевірка ваших локальних файлів Mac» не відображатиме те, що використовує Gateway. --- -## Два шари збереження +## Два рівні збереження -OpenClaw зберігає сесії у двох шарах: +OpenClaw зберігає сесії на двох рівнях: 1. **Сховище сесій (`sessions.json`)** - Мапа ключ/значення: `sessionKey -> SessionEntry` - - Невелике, змінне, безпечне для редагування (або видалення записів) + - Невелике, змінюване, безпечне для редагування (або видалення записів) - Відстежує метадані сесії (поточний ідентифікатор сесії, останню активність, перемикачі, лічильники токенів тощо) 2. **Транскрипт (`.jsonl`)** - - Транскрипт лише з додаванням записів із деревоподібною структурою (записи мають `id` + `parentId`) + - Транскрипт лише з додаванням зі структурою дерева (записи мають `id` + `parentId`) - Зберігає фактичну розмову + виклики інструментів + підсумки Compaction - Використовується для відновлення контексту моделі для майбутніх ходів - Великі контрольні точки налагодження перед Compaction пропускаються, щойно активний - транскрипт перевищує обмеження розміру контрольної точки, щоб уникнути другої гігантської + транскрипт перевищує ліміт розміру контрольної точки, щоб уникнути другої гігантської копії `.checkpoint.*.jsonl`. +Зчитувачі історії Gateway мають уникати матеріалізації всього транскрипту, якщо +поверхня явно не потребує довільного історичного доступу. Історія першої сторінки, +вбудована історія чату, відновлення після перезапуску та перевірки токенів/використання застосовують обмежене читання хвоста. +Повні сканування транскрипту проходять через асинхронний індекс транскриптів, який +кешується за шляхом файлу плюс `mtimeMs`/`size` і спільно використовується паралельними зчитувачами. + --- ## Розташування на диску @@ -71,39 +77,39 @@ OpenClaw зберігає сесії у двох шарах: - Транскрипти: `~/.openclaw/agents//sessions/.jsonl` - Сесії тем Telegram: `.../-topic-.jsonl` -OpenClaw визначає ці шляхи через `src/config/sessions.ts`. +OpenClaw визначає їх через `src/config/sessions.ts`. --- ## Обслуговування сховища та контроль диска -Збереження сесій має автоматичні засоби обслуговування (`session.maintenance`) для `sessions.json`, артефактів транскриптів і допоміжних файлів траєкторій: +Збереження сесій має автоматичні засоби обслуговування (`session.maintenance`) для `sessions.json`, артефактів транскриптів і супровідних файлів траєкторій: - `mode`: `warn` (типово) або `enforce` -- `pruneAfter`: граничний вік застарілого запису (типово `30d`) -- `maxEntries`: обмеження кількості записів у `sessions.json` (типово `500`) -- `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.` (типово: те саме, що `pruneAfter`; `false` вимикає очищення) +- `pruneAfter`: поріг віку застарілих записів (типово `30d`) +- `maxEntries`: ліміт записів у `sessions.json` (типово `500`) +- `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.` (типово: такий самий, як `pruneAfter`; `false` вимикає очищення) - `maxDiskBytes`: необов’язковий бюджет каталогу сесій - `highWaterBytes`: необов’язкова ціль після очищення (типово `80%` від `maxDiskBytes`) -Звичайні записи Gateway пакетно виконують очищення `maxEntries` для обмежень виробничого розміру, тому сховище може короткочасно перевищувати налаштоване обмеження, доки наступне очищення верхнього рівня не перепише його назад до меншого розміру. Читання сховища сесій не обрізають і не обмежують записи під час запуску Gateway; для очищення використовуйте записи або `openclaw sessions cleanup --enforce`. `openclaw sessions cleanup --enforce` усе одно застосовує налаштоване обмеження негайно. +Звичайні записи Gateway групують очищення `maxEntries` для лімітів виробничого розміру, тому сховище може короткочасно перевищувати налаштований ліміт, перш ніж наступне очищення верхньої межі перепише його назад до меншого розміру. Читання сховища сесій не обрізають і не обмежують записи під час запуску Gateway; для очищення використовуйте записи або `openclaw sessions cleanup --enforce`. `openclaw sessions cleanup --enforce` усе одно негайно застосовує налаштований ліміт. -Обслуговування зберігає надійні зовнішні вказівники розмов, як-от групові сесії -та сесії чату в межах потоку, але синтетичні runtime-записи для cron, hooks, -heartbeat, ACP і підагентів усе ще можуть бути видалені, коли вони перевищують +Обслуговування зберігає тривкі зовнішні покажчики розмов, як-от групові сесії +та сесії чату в межах гілки, але синтетичні runtime-записи для Cron, hooks, +Heartbeat, ACP і субагентів усе ще можуть видалятися, коли перевищують налаштований вік, кількість або дисковий бюджет. -OpenClaw більше не створює автоматичні ротаційні резервні копії `sessions.json.bak.*` під час записів Gateway. Застарілий ключ `session.maintenance.rotateBytes` ігнорується, а `openclaw doctor --fix` видаляє його зі старих конфігурацій. +OpenClaw більше не створює автоматичні ротаційні резервні копії `sessions.json.bak.*` під час записів Gateway. Застарілий ключ `session.maintenance.rotateBytes` ігнорується, а `openclaw doctor --fix` видаляє його зі старіших конфігурацій. -Порядок примусового очищення дискового бюджету (`mode: "enforce"`): +Порядок застосування очищення дискового бюджету (`mode: "enforce"`): -1. Спочатку видалити найстаріші архівовані, осиротілі транскрипти або осиротілі артефакти траєкторій. -2. Якщо все ще вище за ціль, витіснити найстаріші записи сесій та їхні файли транскриптів/траєкторій. -3. Продовжувати, доки використання не стане на рівні `highWaterBytes` або нижче. +1. Спершу видалити найстаріші архівовані, осиротілі артефакти транскриптів або осиротілі артефакти траєкторій. +2. Якщо все ще вище цілі, витіснити найстаріші записи сесій і їхні файли транскриптів/траєкторій. +3. Продовжувати, доки використання не буде на рівні або нижче `highWaterBytes`. У `mode: "warn"` OpenClaw повідомляє про потенційні витіснення, але не змінює сховище/файли. -Запустіть обслуговування на вимогу: +Запуск обслуговування на вимогу: ```bash openclaw sessions cleanup --dry-run @@ -114,28 +120,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 примусово створює нову ізольовану сесію запуску, він санітизує попередній запис сесії `cron:` перед записом нового рядка. Він переносить безпечні -налаштування, як-от параметри thinking/fast/verbose, мітки та явні вибрані -користувачем перевизначення моделі/auth. Він відкидає навколишній контекст розмови, -як-от маршрутизацію каналу/групи, політику надсилання або черги, підвищення, -origin і runtime-прив’язку ACP, щоб свіжий ізольований запуск не міг успадкувати -застарілу доставку або runtime-повноваження від старішого запуску. +налаштування, як-от thinking/fast/verbose, мітки та явно +вибрані користувачем перевизначення моделі/автентифікації. Він відкидає навколишній контекст розмови, як-от +маршрутизацію каналу/групи, політику надсилання або черги, підвищення прав, походження та +runtime-прив’язку ACP, щоб новий ізольований запуск не міг успадкувати застарілу доставку або +runtime-повноваження від старішого запуску. --- ## Ключі сесій (`sessionKey`) -`sessionKey` визначає, _у якому контейнері розмови_ ви перебуваєте (маршрутизація + ізоляція). +`sessionKey` визначає, у якому _контейнері розмови_ ви перебуваєте (маршрутизація + ізоляція). Поширені шаблони: -- Основний/прямий чат (для кожного агента): `agent::` (типово `main`) +- Основний/прямий чат (для агента): `agent::` (типово `main`) - Група: `agent:::group:` - Кімната/канал (Discord/Slack): `agent:::channel:` або `...:room:` - Cron: `cron:` @@ -152,10 +158,10 @@ origin і runtime-прив’язку ACP, щоб свіжий ізольова Практичні правила: - **Скидання** (`/new`, `/reset`) створює новий `sessionId` для цього `sessionKey`. -- **Щоденне скидання** (типово 4:00 AM за локальним часом на хості Gateway) створює новий `sessionId` під час наступного повідомлення після межі скидання. -- **Закінчення через бездіяльність** (`session.reset.idleMinutes` або застарілий `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна бездіяльності. Коли налаштовано і щоденне, і idle-скидання, перемагає те, що спливає першим. -- **Системні події** (heartbeat, пробудження Cron, exec-сповіщення, службовий облік Gateway) можуть змінювати рядок сесії, але не подовжують свіжість щоденного/idle-скидання. Перехід скидання відкидає поставлені в чергу сповіщення системних подій для попередньої сесії до побудови свіжого prompt. -- **Політика parent fork** використовує активну гілку PI під час створення потоку або fork підагента. Якщо ця гілка завелика, OpenClaw запускає дочірню сесію з ізольованим контекстом замість помилки або успадкування непридатної історії. Політика визначення розміру автоматична; застарілу конфігурацію `session.parentForkMaxTokens` видаляє `openclaw doctor --fix`. +- **Щоденне скидання** (типово о 4:00 AM за локальним часом на хості Gateway) створює новий `sessionId` у наступному повідомленні після межі скидання. +- **Закінчення строку бездіяльності** (`session.reset.idleMinutes` або застарілий `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна бездіяльності. Коли налаштовані і щоденне скидання, і бездіяльність, спрацьовує те, що завершується першим. +- **Системні події** (Heartbeat, пробудження Cron, сповіщення exec, облік Gateway) можуть змінювати рядок сесії, але не подовжують свіжість щоденного/бездіяльного скидання. Перехід скидання відкидає сповіщення системних подій у черзі для попередньої сесії до побудови свіжого prompt. +- **Політика parent fork** використовує активну гілку Pi під час створення гілки або форка субагента. Якщо ця гілка завелика, OpenClaw запускає дочірній елемент з ізольованим контекстом замість помилки або успадкування непридатної історії. Політика визначення розміру автоматична; застарілу конфігурацію `session.parentForkMaxTokens` видаляє `openclaw doctor --fix`. Деталь реалізації: рішення ухвалюється в `initSessionState()` у `src/auto-reply/reply/session.ts`. @@ -167,71 +173,71 @@ origin і runtime-прив’язку ACP, щоб свіжий ізольова Ключові поля (не вичерпно): -- `sessionId`: поточний ідентифікатор транскрипту (назва файлу походить від нього, якщо `sessionFile` не задано) -- `sessionStartedAt`: timestamp початку для поточного `sessionId`; свіжість щоденного скидання - використовує його. Застарілі рядки можуть виводити його із заголовка сесії JSONL. -- `lastInteractionAt`: timestamp останньої реальної взаємодії користувача/каналу; свіжість idle-скидання - використовує його, тому heartbeat, Cron і exec-події не підтримують сесії +- `sessionId`: поточний ідентифікатор транскрипту (ім’я файлу виводиться з нього, якщо не встановлено `sessionFile`) +- `sessionStartedAt`: часова позначка початку поточного `sessionId`; щоденне скидання + використовує це для свіжості. Застарілі рядки можуть виводити її із заголовка сесії JSONL. +- `lastInteractionAt`: часова позначка останньої реальної взаємодії користувача/каналу; скидання через бездіяльність + використовує це для свіжості, щоб Heartbeat, Cron і exec-події не підтримували сесії активними. Застарілі рядки без цього поля повертаються до відновленого часу початку сесії - для свіжості idle. -- `updatedAt`: timestamp останньої зміни рядка сховища, використовується для списків, обрізання та - службового обліку. Він не є джерелом істини для свіжості щоденного/idle-скидання. + для свіжості бездіяльності. +- `updatedAt`: часова позначка останньої зміни рядка сховища, використовується для списків, обрізання та + службового обліку. Вона не є джерелом істини для свіжості щоденного/бездіяльного скидання. - `sessionFile`: необов’язкове явне перевизначення шляху транскрипту -- `chatType`: `direct | group | room` (допомагає UI і політиці надсилання) -- `provider`, `subject`, `room`, `space`, `displayName`: метадані для маркування груп/каналів +- `chatType`: `direct | group | room` (допомагає інтерфейсам і політиці надсилання) +- `provider`, `subject`, `room`, `space`, `displayName`: метадані для позначення груп/каналів - Перемикачі: - `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel` - `sendPolicy` (перевизначення для окремої сесії) - Вибір моделі: - `providerOverride`, `modelOverride`, `authProfileOverride` -- Лічильники токенів (best-effort / залежить від провайдера): +- Лічильники токенів (найкращі зусилля / залежить від провайдера): - `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens` -- `compactionCount`: як часто auto-compaction завершувалася для цього ключа сесії -- `memoryFlushAt`: timestamp останнього скидання пам’яті перед Compaction +- `compactionCount`: як часто автоматичний Compaction завершувався для цього ключа сесії +- `memoryFlushAt`: часова позначка останнього скидання пам’яті перед Compaction - `memoryFlushCompactionCount`: кількість Compaction, коли востаннє виконувався flush -Сховище безпечно редагувати, але Gateway є джерелом істини: він може перезаписувати або повторно гідратувати записи під час виконання сесій. +Сховище безпечно редагувати, але Gateway є джерелом істини: він може переписувати або повторно гідратувати записи під час виконання сесій. --- ## Структура транскрипту (`*.jsonl`) -Транскриптами керує `SessionManager` із `@mariozechner/pi-coding-agent`. +Транскриптами керує `SessionManager` з `@mariozechner/pi-coding-agent`. Файл має формат JSONL: -- Перший рядок: заголовок сесії (`type: "session"`, містить `id`, `cwd`, `timestamp`, необов’язковий `parentSession`) +- Перший рядок: заголовок сесії (`type: "session"`, містить `id`, `cwd`, `timestamp`, необов’язково `parentSession`) - Далі: записи сесії з `id` + `parentId` (дерево) Важливі типи записів: -- `message`: повідомлення користувача/асистента/toolResult -- `custom_message`: повідомлення, ін’єктовані extension, які _входять_ до контексту моделі (можуть бути приховані від UI) -- `custom`: стан extension, який _не входить_ до контексту моделі -- `compaction`: збережений підсумок Compaction із `firstKeptEntryId` і `tokensBefore` +- `message`: повідомлення user/assistant/toolResult +- `custom_message`: повідомлення, ін’єктовані extension, які _входять_ у контекст моделі (можуть бути приховані від UI) +- `custom`: стан extension, який _не входить_ у контекст моделі +- `compaction`: збережений підсумок Compaction з `firstKeptEntryId` і `tokensBefore` - `branch_summary`: збережений підсумок під час навігації гілкою дерева -OpenClaw навмисно **не** “виправляє” транскрипти; Gateway використовує `SessionManager` для їх читання/запису. +OpenClaw навмисно **не** «виправляє» транскрипти; Gateway використовує `SessionManager` для їх читання/запису. --- -## Контекстні вікна порівняно з відстежуваними токенами +## Контекстні вікна проти відстежуваних токенів Важливі два різні поняття: -1. **Контекстне вікно моделі**: жорстке обмеження для кожної моделі (токени, видимі моделі) -2. **Лічильники сховища сесій**: рухомі статистики, записані в `sessions.json` (використовуються для /status і dashboard) +1. **Контекстне вікно моделі**: жорсткий ліміт для кожної моделі (токени, видимі моделі) +2. **Лічильники сховища сесій**: ковзна статистика, що записується в `sessions.json` (використовується для /status і dashboard) -Якщо ви налаштовуєте обмеження: +Якщо ви налаштовуєте ліміти: - Контекстне вікно надходить із каталогу моделей (і може бути перевизначене через конфігурацію). -- `contextTokens` у сховищі — це runtime-оцінка/звітне значення; не сприймайте його як сувору гарантію. +- `contextTokens` у сховищі — runtime-оцінка/звітне значення; не сприймайте його як сувору гарантію. Докладніше див. [/token-use](/uk/reference/token-use). --- -## Compaction: що це таке +## Compaction: що це Compaction підсумовує старішу розмову в збережений запис `compaction` у транскрипті та залишає недавні повідомлення без змін. @@ -240,62 +246,62 @@ Compaction підсумовує старішу розмову в збереже - Підсумок Compaction - Повідомлення після `firstKeptEntryId` -Compaction є **постійною** (на відміну від обрізання сесій). Див. [/concepts/session-pruning](/uk/concepts/session-pruning). +Compaction є **постійним** (на відміну від обрізання сесій). Див. [/concepts/session-pruning](/uk/concepts/session-pruning). -## Межі чанків Compaction і парування інструментів +## Межі фрагментів Compaction і поєднання інструментів -Коли OpenClaw ділить довгий транскрипт на чанки Compaction, він зберігає -виклики інструментів асистента в парі з відповідними записами `toolResult`. +Коли OpenClaw розбиває довгий транскрипт на фрагменти Compaction, він зберігає +виклики інструментів assistant разом із відповідними записами `toolResult`. - Якщо розділення за часткою токенів потрапляє між викликом інструмента та його результатом, OpenClaw - зсуває межу до повідомлення асистента з викликом інструмента замість розділення + зміщує межу до повідомлення assistant із викликом інструмента замість розділення пари. -- Якщо кінцевий блок tool-result інакше перевищив би цільовий розмір чанка, - OpenClaw зберігає цей pending-блок інструмента й залишає непідсумований хвіст +- Якщо кінцевий блок результатів інструментів інакше вивів би фрагмент за ціль, + OpenClaw зберігає цей очікуваний блок інструментів і залишає непідсумований хвіст без змін. -- Перервані/помилкові блоки tool-call не утримують pending-розділення відкритим. +- Перервані/помилкові блоки викликів інструментів не утримують очікуване розділення відкритим. --- -## Коли відбувається auto-compaction (Pi runtime) +## Коли відбувається автоматичний Compaction (runtime Pi) -У вбудованому агенті Pi auto-compaction запускається у двох випадках: +У вбудованому агенті Pi автоматичний Compaction запускається у двох випадках: 1. **Відновлення після переповнення**: модель повертає помилку переповнення контексту (`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` і подібні варіанти у формі провайдерів) → compact → retry. -2. **Порогове обслуговування**: після успішного ходу, коли: +exceeded` і подібні варіанти у форматі провайдерів) → compact → retry. +2. **Підтримка порога**: після успішного ходу, коли: `contextTokens > contextWindow - reserveTokens` Де: - `contextWindow` — контекстне вікно моделі -- `reserveTokens` — запас, зарезервований для prompts + наступного виводу моделі +- `reserveTokens` — запас, зарезервований для промптів + наступного виводу моделі -Це семантика Pi runtime (OpenClaw споживає події, але Pi вирішує, коли виконувати compact). +Це семантика runtime Pi (OpenClaw споживає події, але Pi вирішує, коли compact). OpenClaw також може запускати попередню локальну Compaction перед відкриттям наступного запуску, коли встановлено `agents.defaults.compaction.maxActiveTranscriptBytes` і -активний файл транскрипту досягає цього розміру. Це запобіжник за розміром файлу для вартості -локального повторного відкриття, а не необробленого архівування: OpenClaw все одно виконує звичайну семантичну Compaction, -і для цього потрібен `truncateAfterCompaction`, щоб стиснений підсумок міг стати +активний файл транскрипта досягає цього розміру. Це захист за розміром файла для локальної +вартості повторного відкриття, а не сирого архівування: OpenClaw усе одно запускає звичайну семантичну Compaction, +і для цього потрібен `truncateAfterCompaction`, щоб ущільнений підсумок міг стати новим наступним транскриптом. -Для вбудованих запусків Pi параметр `agents.defaults.compaction.midTurnPrecheck.enabled: true` -додає додатковий запобіжник циклу інструментів. Після додавання результату інструмента і перед +Для вбудованих запусків Pi, `agents.defaults.compaction.midTurnPrecheck.enabled: true` +додає опційний захист циклу інструментів. Після додавання результату інструмента та перед наступним викликом моделі OpenClaw оцінює тиск на промпт, використовуючи ту саму логіку попереднього -бюджету, що й на початку ходу. Якщо контекст більше не вміщується, запобіжник -не виконує Compaction всередині хука `transformContext` Pi. Він піднімає структурований -сигнал попередньої перевірки всередині ходу, зупиняє поточне надсилання промпта і дає +бюджету, що й на початку ходу. Якщо контекст більше не вміщується, захист не +виконує compact усередині хуку Pi `transformContext`. Він піднімає структурований +сигнал попередньої перевірки посеред ходу, зупиняє поточне надсилання промпта й дає зовнішньому циклу запуску використати наявний шлях відновлення: обрізати завеликі результати інструментів, -коли цього достатньо, або запустити налаштований режим Compaction і повторити спробу. Цей -параметр за замовчуванням вимкнений і працює з режимами Compaction `default` і `safeguard`, -зокрема з Compaction safeguard на основі провайдера. -Це не залежить від `maxActiveTranscriptBytes`: запобіжник за розміром у байтах запускається -перед відкриттям ходу, тоді як попередня перевірка всередині ходу запускається пізніше у вбудованому циклі інструментів Pi +коли цього достатньо, або запустити налаштований режим Compaction і повторити спробу. Опцію +вимкнено за замовчуванням, і вона працює з режимами Compaction `default` і `safeguard`, +зокрема з Compaction через провайдера safeguard. +Це незалежно від `maxActiveTranscriptBytes`: захист за розміром у байтах запускається +до відкриття ходу, тоді як попередня перевірка посеред ходу запускається пізніше у вбудованому циклі інструментів Pi після додавання нових результатів інструментів. --- @@ -314,32 +320,32 @@ OpenClaw також може запускати попередню локаль } ``` -OpenClaw також забезпечує мінімальний поріг безпеки для вбудованих запусків: +OpenClaw також застосовує безпечний мінімум для вбудованих запусків: - Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw підвищує його. -- Стандартний мінімальний поріг становить `20000` токенів. -- Встановіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути цей поріг. -- Якщо він уже вищий, OpenClaw залишає його без змін. +- Типовий мінімум — `20000` токенів. +- Установіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути мінімум. +- Якщо значення вже вище, OpenClaw залишає його без змін. - Ручний `/compact` враховує явний `agents.defaults.compaction.keepRecentTokens` і зберігає точку відсікання недавнього хвоста Pi. Без явного бюджету збереження ручна Compaction залишається жорсткою контрольною точкою, а перебудований контекст починається з нового підсумку. -- Встановіть `agents.defaults.compaction.midTurnPrecheck.enabled: true`, щоб запускати - додаткову попередню перевірку циклу інструментів після нових результатів інструментів і перед наступним - викликом моделі. Це лише тригер; створення підсумку все одно використовує налаштований - шлях Compaction. Він не залежить від `maxActiveTranscriptBytes`, який є - запобіжником розміру активного транскрипту в байтах на початку ходу. -- Встановіть `agents.defaults.compaction.maxActiveTranscriptBytes` у значення байтів або +- Установіть `agents.defaults.compaction.midTurnPrecheck.enabled: true`, щоб запускати + опційну попередню перевірку циклу інструментів після нових результатів інструментів і перед наступним + викликом моделі. Це лише тригер; генерація підсумку й далі використовує налаштований + шлях Compaction. Вона незалежна від `maxActiveTranscriptBytes`, який є + захистом за розміром у байтах активного транскрипта на початку ходу. +- Установіть `agents.defaults.compaction.maxActiveTranscriptBytes` у значення байтів або рядок на кшталт `"20mb"`, щоб запускати локальну Compaction перед ходом, коли активний - транскрипт стає великим. Цей запобіжник активний лише тоді, коли також увімкнено + транскрипт стає великим. Цей захист активний лише тоді, коли також увімкнено `truncateAfterCompaction`. Залиште його невстановленим або встановіть `0`, щоб вимкнути. -- Коли увімкнено `agents.defaults.compaction.truncateAfterCompaction`, - OpenClaw після Compaction ротирує активний транскрипт у стиснений наступний JSONL. - Старий повний транскрипт залишається заархівованим і пов’язаним із - контрольною точкою Compaction замість перезапису на місці. +- Коли ввімкнено `agents.defaults.compaction.truncateAfterCompaction`, + OpenClaw після Compaction ротуює активний транскрипт у стиснутий наступний JSONL. + Старий повний транскрипт залишається в архіві та пов’язується з + контрольною точкою Compaction, а не переписується на місці. -Навіщо: залишити достатньо запасу для багатокрокового «обслуговування» (наприклад, записів у пам’ять) до того, як Compaction стане неминучою. +Навіщо: залишити достатньо запасу для багатоходового “службового обслуговування” (наприклад, записів пам’яті), перш ніж Compaction стане неминучою. Реалізація: `ensurePiCompactionReserveTokens()` у `src/agents/pi-settings.ts` (викликається з `src/agents/pi-embedded-runner.ts`). @@ -348,18 +354,18 @@ OpenClaw також забезпечує мінімальний поріг бе ## Підключувані провайдери Compaction -Plugins можуть реєструвати провайдера Compaction через `registerCompactionProvider()` в API Plugin. Коли `agents.defaults.compaction.provider` встановлено на ідентифікатор зареєстрованого провайдера, розширення safeguard делегує підсумовування цьому провайдеру замість вбудованого конвеєра `summarizeInStages`. +Plugins можуть зареєструвати провайдера Compaction через `registerCompactionProvider()` в API Plugin. Коли `agents.defaults.compaction.provider` встановлено на ідентифікатор зареєстрованого провайдера, розширення safeguard делегує підсумовування цьому провайдеру замість вбудованого пайплайна `summarizeInStages`. -- `provider`: ідентифікатор зареєстрованого Plugin провайдера Compaction. Залиште невстановленим для стандартного підсумовування LLM. -- Встановлення `provider` примусово задає `mode: "safeguard"`. +- `provider`: ідентифікатор зареєстрованого Plugin-провайдера Compaction. Залиште невстановленим для типового LLM-підсумовування. +- Установлення `provider` примусово вмикає `mode: "safeguard"`. - Провайдери отримують ті самі інструкції Compaction і політику збереження ідентифікаторів, що й вбудований шлях. -- Safeguard усе одно зберігає контекст недавніх ходів і суфікса розділеного ходу після виводу провайдера. +- Safeguard усе одно зберігає контекст суфікса недавнього ходу та розділеного ходу після виводу провайдера. - Вбудоване підсумовування safeguard повторно дистилює попередні підсумки з новими повідомленнями - замість збереження повного попереднього підсумку дослівно. -- Режим safeguard за замовчуванням вмикає аудити якості підсумку; встановіть - `qualityGuard.enabled: false`, щоб пропустити поведінку повторної спроби при некоректно сформованому виводі. -- Якщо провайдер завершується з помилкою або повертає порожній результат, OpenClaw автоматично повертається до вбудованого підсумовування LLM. -- Сигнали переривання/тайм-ауту повторно викидаються (не приглушуються), щоб поважати скасування викликувачем. + замість того, щоб зберігати повний попередній підсумок дослівно. +- Режим safeguard вмикає аудити якості підсумків за замовчуванням; установіть + `qualityGuard.enabled: false`, щоб пропустити поведінку повторної спроби після некоректно сформованого виводу. +- Якщо провайдер зазнає збою або повертає порожній результат, OpenClaw автоматично повертається до вбудованого LLM-підсумовування. +- Сигнали переривання/тайм-ауту перекидаються повторно (не поглинаються), щоб поважати скасування викликачем. Джерело: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`. @@ -367,68 +373,68 @@ Plugins можуть реєструвати провайдера Compaction че ## Поверхні, видимі користувачу -Ви можете спостерігати за Compaction і станом сеансу через: +Ви можете спостерігати Compaction і стан сесії через: -- `/status` (у будь-якому чат-сеансі) +- `/status` (у будь-якій чат-сесії) - `openclaw status` (CLI) - `openclaw sessions` / `sessions --json` -- Докладний режим: `🧹 Auto-compaction complete` + кількість Compaction +- Докладний режим: `🧹 Auto-compaction complete` + лічильник Compaction --- -## Тихе обслуговування (`NO_REPLY`) +## Тихе службове обслуговування (`NO_REPLY`) -OpenClaw підтримує «тихі» ходи для фонових завдань, де користувач не повинен бачити проміжний вивід. +OpenClaw підтримує “тихі” ходи для фонових завдань, де користувач не має бачити проміжний вивід. -Угода: +Домовленість: -- Асистент починає свій вивід із точного тихого токена `NO_REPLY` / - `no_reply`, щоб позначити «не доставляти відповідь користувачу». -- OpenClaw прибирає/пригнічує це на рівні доставки. -- Пригнічення точного тихого токена не чутливе до регістру, тому `NO_REPLY` і +- Асистент починає свій вивід з точного тихого токена `NO_REPLY` / + `no_reply`, щоб указати “не доставляти відповідь користувачу”. +- OpenClaw вилучає/пригнічує це на рівні доставки. +- Пригнічення точного тихого токена не залежить від регістру, тому `NO_REPLY` і `no_reply` обидва зараховуються, коли весь payload є лише тихим токеном. - Це лише для справді фонових ходів без доставки; це не скорочення для звичайних дієвих запитів користувача. -Станом на `2026.1.10` OpenClaw також пригнічує **потокове передавання чернетки/набирання**, коли -частковий фрагмент починається з `NO_REPLY`, тож тихі операції не пропускають частковий -вивід усередині ходу. +Станом на `2026.1.10`, OpenClaw також пригнічує **потокове передавання чернетки/набору** коли +частковий фрагмент починається з `NO_REPLY`, тож тихі операції не протікають частковим +виводом посеред ходу. --- -## «Скидання пам’яті» перед Compaction (реалізовано) +## “Скидання пам’яті” перед Compaction (реалізовано) Мета: перед автоматичною Compaction запустити тихий агентний хід, який записує довговічний -стан на диск (наприклад, `memory/YYYY-MM-DD.md` у робочій області агента), щоб 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`) -- `model` (необов’язкове точне перевизначення провайдера/моделі для ходу скидання, наприклад `ollama/qwen3:8b`) +- `model` (опційне точне перевизначення провайдера/моделі для ходу скидання, наприклад `ollama/qwen3:8b`) - `softThresholdTokens` (за замовчуванням: `4000`) - `prompt` (повідомлення користувача для ходу скидання) - `systemPrompt` (додатковий системний промпт, доданий для ходу скидання) Примітки: -- Стандартний промпт/системний промпт містять підказку `NO_REPLY`, щоб пригнітити +- Типові prompt/system prompt містять підказку `NO_REPLY`, щоб пригнітити доставку. - Коли встановлено `model`, хід скидання використовує цю модель без успадкування - ланцюга fallback активного сеансу, тож локальне обслуговування непомітно не - переходить на платну розмовну модель. + ланцюга fallback активної сесії, тож локальне службове обслуговування не буде непомітно + відступати до платної розмовної моделі. - Скидання запускається один раз за цикл Compaction (відстежується в `sessions.json`). -- Скидання запускається лише для вбудованих сеансів Pi (бекенди CLI його пропускають). -- Скидання пропускається, коли робоча область сеансу доступна лише для читання (`workspaceAccess: "ro"` або `"none"`). -- Див. [Пам’ять](/uk/concepts/memory) щодо структури файлів робочої області та шаблонів запису. +- Скидання запускається лише для вбудованих сесій Pi (CLI-бекенди пропускають його). +- Скидання пропускається, коли робочий простір сесії доступний лише для читання (`workspaceAccess: "ro"` або `"none"`). +- Див. [Пам’ять](/uk/concepts/memory) щодо розкладки файлів робочого простору та патернів запису. Pi також надає хук `session_before_compact` в API розширення, але логіка скидання OpenClaw сьогодні живе на боці Gateway. @@ -437,16 +443,16 @@ Pi також надає хук `session_before_compact` в API розширен ## Контрольний список усунення несправностей -- Неправильний ключ сеансу? Почніть із [/concepts/session](/uk/concepts/session) і підтвердьте `sessionKey` у `/status`. -- Невідповідність сховища й транскрипту? Підтвердьте хост Gateway і шлях сховища з `openclaw status`. +- Неправильний ключ сесії? Почніть з [/concepts/session](/uk/concepts/session) і підтвердьте `sessionKey` у `/status`. +- Невідповідність сховища й транскрипта? Підтвердьте хост Gateway і шлях сховища з `openclaw status`. - Спам Compaction? Перевірте: - - вікно контексту моделі (занадто мале) - - налаштування Compaction (`reserveTokens` занадто високий для вікна моделі може спричиняти ранішу Compaction) - - роздування результатів інструментів: увімкніть/налаштуйте обрізання сеансу -- Тихі ходи просочуються? Підтвердьте, що відповідь починається з `NO_REPLY` (точний токен без урахування регістру) і що ви використовуєте збірку, яка містить виправлення пригнічення потокового передавання. + - контекстне вікно моделі (занадто мале) + - налаштування Compaction (`reserveTokens` занадто високий для вікна моделі може спричинити ранішу Compaction) + - роздування результатів інструментів: увімкніть/налаштуйте обрізання сесії +- Тихі ходи протікають? Підтвердьте, що відповідь починається з `NO_REPLY` (точний токен без урахування регістру) і що ви використовуєте збірку, яка містить виправлення пригнічення streaming. ## Пов’язане -- [Керування сеансами](/uk/concepts/session) -- [Обрізання сеансів](/uk/concepts/session-pruning) +- [Керування сесіями](/uk/concepts/session) +- [Обрізання сесії](/uk/concepts/session-pruning) - [Рушій контексту](/uk/concepts/context-engine)