---
read_when:
    - Потрібно налагодити ідентифікатори сеансів, події журналу розмови або поля рядків сеансу
    - Ви змінюєте поведінку автоматичної Compaction або додаєте обслуговування «перед Compaction»
    - Ви хочете реалізувати скидання пам’яті або безмовні системні ходи
summary: 'Докладний огляд: сховище сесій і транскрипти, життєвий цикл та внутрішня реалізація (автоматичного) Compaction'
title: Поглиблений огляд керування сеансами
x-i18n:
    generated_at: "2026-07-16T18:32:12Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 7551a94a4e2dc8be8b69503795309d0200cc3b5d7231b54083dbcaade697b06c
    source_path: reference/session-management-compaction.md
    workflow: 16
---

Один **процес Gateway** повністю керує станом сеансу. Інтерфейси користувача (застосунок macOS, вебінтерфейс Control UI, TUI) запитують у Gateway списки сеансів і кількість токенів. У віддаленому режимі файли сеансів зберігаються на віддаленому хості, тому перевірка файлів на локальному Mac не відображатиме дані, які використовує Gateway.

Спочатку оглядова документація: [Керування сеансами](/uk/concepts/session), [Compaction](/uk/concepts/compaction), [Огляд пам’яті](/uk/concepts/memory), [Пошук у пам’яті](/uk/concepts/memory-search), [Очищення сеансів](/uk/concepts/session-pruning), [Гігієна стенограм](/uk/reference/transcript-hygiene), повний довідник конфігурації в розділі [Конфігурація агента](/uk/gateway/config-agents).

## Два рівні збереження даних

1. **Рядки сеансів (окрема SQLite для кожного агента)** - мапа ключів і значень `sessionKey -> SessionEntry`. Змінний стан середовища виконання, яким керує Gateway. Відстежує метадані: ідентифікатор поточного сеансу, останню активність, перемикачі та лічильники токенів.
2. **Події стенограми (окрема SQLite для кожного агента)** - структура лише для дописування у вигляді дерева (записи мають `id` + `parentId`). Зберігає розмову, виклики інструментів і підсумки Compaction; відновлює контекст моделі для майбутніх ходів. Контрольні точки Compaction — це метадані наступної стенограми після стискання: нова операція Compaction не записує другу копію `.checkpoint.*.jsonl`.

У старіших інсталяціях у каталозі агента `sessions/`
ще можуть бути файли `sessions.json`. Вважайте ці файли вхідними даними для перенесення рядків застарілих сеансів або явними
цілями автономного обслуговування. Запуск Gateway і `openclaw doctor --fix` автоматично імпортують
активні застарілі рядки та історію стенограм у сховище SQLite відповідного агента.
Запустіть `openclaw doctor --session-sqlite inspect
--session-sqlite-all-agents`, а потім дотримуйтеся [послідовності перенесення
Doctor](/uk/cli/doctor#session-sqlite-migration), якщо потрібні явна
перевірка або докази валідації. Якщо перенесення завершилося помилкою після архівування застарілих артефактів
стенограм, скористайтеся режимом відновлення Doctor із цієї послідовності.
Відновлення використовує маніфести перенесення, відновлює лише зачеплені архівовані допоміжні
артефакти, за запитом готує очищений від конфіденційних даних звіт про проблему для GitHub і не
змушує активне середовище виконання знову читати файли JSONL.

Зчитувачі історії Gateway не завантажують у пам’ять усю стенограму, якщо поверхні не потрібен довільний доступ до історичних даних. Історія першої сторінки, вбудована історія чату, відновлення після перезапуску та перевірки токенів і використання застосовують обмежене читання хвоста з SQLite. Повне сканування стенограм виконується через асинхронний індекс стенограм і спільно використовується паралельними зчитувачами.

## Розташування на диску

Для кожного агента на хості Gateway (визначається через `src/config/sessions.ts`):

- Сховище рядків сеансів середовища виконання: `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite`
- Рядки стенограм середовища виконання: `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite`
- Застарілі/архівні артефакти стенограм: `~/.openclaw/agents/<agentId>/sessions/`
- Вхідні дані перенесення застарілих рядків: `~/.openclaw/agents/<agentId>/sessions/sessions.json`

## Обслуговування сховища та керування диском

`session.maintenance` керує автоматичним обслуговуванням рядків сеансів SQLite, рядків стенограм SQLite, архівних артефактів і допоміжних файлів траєкторій:

| Ключ                    | Типове значення        | Примітки                                                                                    |
| ----------------------- | --------------------- | ------------------------------------------------------------------------------------------- |
| `mode`                  | `"enforce"`           | або `"warn"` (лише звіт, без змін)                                                      |
| `pruneAfter`            | `"30d"`               | граничний вік застарілих записів                                                                      |
| `maxEntries`            | `500`                 | обмеження кількості записів сеансів                                                                      |
| `resetArchiveRetention` | зберігати (без обмеження за віком)  | граничний вік архівів стенограм `*.reset.*`/`*.deleted.*`; указання тривалості вмикає видалення |
| `maxDiskBytes`          | `2gb`                 | дисковий бюджет сеансів для кожного агента; `false` вимикає                                            |
| `highWaterBytes`        | 80% від `maxDiskBytes` | цільове значення після очищення відповідно до бюджету                                                                 |

Архівовані стенограми типово зберігаються та стискаються за допомогою zstd (`*.jsonl.<reason>.<timestamp>.zst`), якщо середовище виконання це підтримує, тому видалення або скидання сеансу ніколи непомітно не видаляє історію розмови. Дисковий бюджет спочатку витісняє найстаріші архіви й лише потім торкається активних сеансів.

Активне застосування `maxDiskBytes` у SQLite вимірює сумарний розмір JSON рядка сеансу та JSON подій стенограми для кожного сеансу в байтах; застосування під час автономного обслуговування застарілих даних вимірює файли у вибраному каталозі сеансів.

Пробні сеанси запуску моделі Gateway (ключі, що відповідають `agent:*:explicit:model-run-<uuid>`) мають окремий фіксований строк зберігання `24h`. Це очищення виконується лише за наявності навантаження: тільки коли досягнуто порога обслуговування або обмеження кількості записів сеансів і лише перед глобальним очищенням або обмеженням застарілих записів. Інші явні сеанси не використовують цей строк зберігання.

Порядок застосування очищення відповідно до дискового бюджету (`mode: "enforce"`):

1. Спочатку видалити найстаріші архівовані артефакти стенограм, осиротілі застарілі артефакти або осиротілі артефакти траєкторій.
2. Якщо обсяг усе ще перевищує цільове значення, витіснити найстаріші записи сеансів і відповідні рядки стенограм або артефакти траєкторій.
3. Повторювати, доки використання не стане меншим або дорівнюватиме `highWaterBytes`.

`mode: "warn"` повідомляє про можливі витіснення, не змінюючи сховище або файли.

Запуск обслуговування на вимогу:

```bash
openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce
```

Обслуговування зберігає сталі зовнішні вказівники на розмови, як-от групові сеанси та сеанси чату в межах гілки, але синтетичні записи середовища виконання (Cron, хуки, Heartbeat, ACP, підагенти) усе одно можуть бути видалені після перевищення налаштованого віку, кількості або дискового бюджету. Ізольовані запуски Cron використовують окремий параметр `cron.sessionRetention`, незалежний від строку зберігання пробних запусків моделі.

Звичайні операції запису Gateway проходять через засіб доступу до сеансів, який серіалізує зміни SQLite окремо для кожного агента через шлях запису середовища виконання. Код середовища виконання має надавати перевагу допоміжним засобам доступу в `src/config/sessions/session-accessor.ts`; застарілі допоміжні засоби `sessions.json` призначені для перенесення й автономного обслуговування. Коли Gateway доступний, команди `openclaw sessions cleanup` і `openclaw agents delete` без режиму пробного запуску делегують зміни сховища Gateway, щоб очищення потрапляло до тієї самої черги запису; `--store <path>` — це явний шлях автономного виправлення вибраного застарілого сховища, який завжди виконується локально (як і `--dry-run`). Очищення `maxEntries` виконується пакетами для сховищ виробничого розміру, тому сховище може ненадовго перевищити налаштоване обмеження, перш ніж наступне очищення за верхнім порогом зменшить його. Операції читання ніколи не очищують і не обмежують записи під час запуску Gateway — це роблять лише операції запису або `openclaw sessions cleanup --enforce`; остання також негайно застосовує обмеження й видаляє старі застарілі артефакти стенограм, контрольних точок і траєкторій, на які немає посилань, навіть якщо дисковий бюджет не налаштовано.

OpenClaw більше не створює автоматичні резервні копії ротації `sessions.json.bak.*` під час запису Gateway. Поточна схема відхиляє застарілий ключ `session.maintenance.rotateBytes`, а `openclaw doctor --fix` видаляє його зі старіших конфігурацій.

Зміни стенограм використовують чергу запису сеансів для цільової стенограми SQLite:

| Налаштування                           | Типове значення | Перевизначення змінною середовища                |
| ------------------------------------ | --------- | ------------------------------------------------ |
| `session.writeLock.acquireTimeoutMs` | `60000`   | `OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS` |
| `session.writeLock.staleMs`          | `1800000` | `OPENCLAW_SESSION_WRITE_LOCK_STALE_MS`           |
| `session.writeLock.maxHoldMs`        | `300000`  | `OPENCLAW_SESSION_WRITE_LOCK_MAX_HOLD_MS`        |

`acquireTimeoutMs` визначає, скільки триває очікування блокування, перш ніж з’явиться помилка зайнятого сеансу й очікування припиниться; збільшуйте це значення лише тоді, коли допустима підготовка, очищення, Compaction або дзеркалювання стенограми довше конкурують за ресурс на повільних машинах. `staleMs` визначає, коли наявне блокування можна звільнити як застаріле. `maxHoldMs` — це поріг примусового звільнення сторожовим таймером у межах процесу.

### Повернення до попередньої версії після переходу на SQLite

Відновіть архівовані застарілі артефакти стенограм перед запуском старішої
файлової версії OpenClaw:

```bash
openclaw doctor --session-sqlite restore --session-sqlite-all-agents
```

Після перенесення застарілі файли `sessions.json` залишаються на місці для підтримки та
відкочування, але активні файли стенограм JSONL, імпортовані в SQLite,
перейменовуються на `session-sqlite-import-archive/`. Старіші файлові середовища виконання використовують
шляхи `sessionFile` у `sessions.json`, тому ці артефакти потрібно відновити
до запуску. Відновлення використовує маніфести перенесення, переміщує лише записані архівовані
артефакти, початкові шляхи яких відсутні, і залишає базу даних SQLite
на місці для подальшого відновлення.

Сеанси, створені після переходу на SQLite, існують лише в SQLite і не відображатимуться в
старішому файловому середовищі виконання. Якщо після повернення до попередньої версії знову виконати оновлення, повторно запустіть
послідовність перевірки й валідації Doctor, щоб OpenClaw міг перевірити відновлені застарілі
артефакти перед імпортом.

## Сеанси Cron і журнали запусків

Ізольовані запуски Cron створюють власні записи сеансів і стенограми з окремим строком зберігання:

- `cron.sessionRetention` (типово `"24h"`) видаляє зі сховища старі сеанси ізольованих запусків Cron; `false` вимикає цю функцію.
- В історії запусків зберігаються найновіші 2000 завершальних рядків для кожного завдання Cron. Втрачені рядки зберігають своє 24-годинне вікно очищення.

Коли Cron примусово створює новий ізольований сеанс запуску, він очищує попередній запис сеансу `cron:<jobId>` перед записом нового рядка: переносить безпечні параметри (налаштування мислення, швидкості, докладності та міркування, мітки, відображуване ім’я), а також явно вибрані користувачем перевизначення моделі й автентифікації, але відкидає фоновий контекст розмови (маршрутизацію каналів і груп, політику надсилання та черги, підвищення привілеїв, походження, прив’язку середовища виконання ACP), щоб новий ізольований запуск не успадкував застарілі повноваження доставки або середовища виконання від попереднього запуску.

## Ключі сеансів (`sessionKey`)

`sessionKey` визначає, у якому контейнері розмови ви перебуваєте (маршрутизація + ізоляція). Канонічні правила: [/concepts/session](/uk/concepts/session).

| Шаблон                       | Приклад                                                     |
| ---------------------------- | ----------------------------------------------------------- |
| Основний/прямий чат (для кожного агента) | `agent:<agentId>:<mainKey>` (типово `main`)                |
| Група                        | `agent:<agentId>:<channel>:group:<id>`                      |
| Кімната/канал (Discord/Slack) | `agent:<agentId>:<channel>:channel:<id>` або `...:room:<id>` |
| Cron                         | `cron:<job.id>`                                             |
| Webhook                      | `hook:<uuid>` (якщо не перевизначено)                           |

## Ідентифікатори сеансів (`sessionId`)

Кожен `sessionKey` вказує на поточний `sessionId` (ідентифікатор стенограми SQLite, яка продовжує розмову). Логіка ухвалення рішень міститься в `initSessionState()` у `src/auto-reply/reply/session.ts`.

- **Скидання** (`/new`, `/reset`) створює новий `sessionId` для цього `sessionKey`.
- **Щоденне скидання** (за замовчуванням о 4:00 за місцевим часом на хості Gateway) створює новий `sessionId` під час наступного повідомлення після межі скидання.
- **Завершення через бездіяльність** (`session.reset.idleMinutes` або застарілий `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після завершення вікна бездіяльності. Якщо налаштовано і щоденне скидання, і завершення через бездіяльність, спрацьовує те, термін якого спливає першим.
- **Продовження після повторного підключення інтерфейсу керування** зберігає видимий зараз сеанс для одного надсилання після повторного підключення, коли Gateway отримує відповідний `sessionId` від клієнта операторського інтерфейсу. Це одноразовий сигнал; звичайні застарілі надсилання й надалі створюють новий `sessionId`.
- **Системні події** (Heartbeat, пробудження Cron, сповіщення про виконання, службові операції Gateway) можуть змінювати рядок сеансу, але ніколи не подовжують актуальність щоденного скидання або скидання через бездіяльність. Під час переходу після скидання сповіщення про системні події в черзі для попереднього сеансу відкидаються до побудови нового запиту.
- **Політика відгалуження від батьківського сеансу** використовує активну гілку OpenClaw під час створення потоку або відгалуження субагента. Якщо ця гілка завелика (понад фіксоване внутрішнє обмеження, наразі 100K токенів), OpenClaw запускає дочірній процес з ізольованим контекстом замість помилки або успадкування непридатної історії. Визначення розміру відбувається автоматично й не налаштовується; застарілу конфігурацію `session.parentForkMaxTokens` видаляє `openclaw doctor --fix`.
- **Відгалуження оператора**: `sessions.create { parentSessionKey, fork: true }` створює новий сеанс, стенограма якого відгалужується від поточного стану батьківського сеансу (використовується той самий механізм відгалуження, що й під час запуску субагентів, включно з наведеним вище обмеженням розміру). Відгалуження відхиляється, поки батьківський сеанс має активний запуск, успадковує вибір моделі батьківського сеансу, якщо модель не передано явно, і позначає дочірній сеанс як `forkedFromParent` з новими лічильниками токенів.

## Схема сховища сеансів

Сховище середовища виконання зберігає значення `SessionEntry` у SQLite для кожного агента. Тип значення — `SessionEntry` у `src/config/sessions.ts`. Основні поля (перелік не вичерпний):

- `sessionId`: поточний ідентифікатор стенограми, який використовується для адресації рядків стенограми SQLite
- `sessionStartedAt`: часова позначка початку поточного `sessionId`; використовується для визначення актуальності щоденного скидання. Для застарілих рядків її можна отримати із заголовка сеансу JSONL.
- `lastInteractionAt`: часова позначка останньої реальної взаємодії користувача або каналу; використовується для визначення актуальності скидання через бездіяльність, щоб події Heartbeat, Cron і виконання не підтримували сеанси активними. Для застарілих рядків без цього поля використовується відновлений час початку сеансу.
- `updatedAt`: часова позначка останньої зміни рядка сховища, що використовується для формування списків, очищення та службових операцій, — вона не є джерелом істини щодо актуальності щоденного скидання або скидання через бездіяльність.
- `archivedAt`: необов’язкова часова позначка архівування. Архівовані сеанси залишаються у сховищі з неушкодженою стенограмою та виключаються зі звичайних списків активних сеансів.
- `pinnedAt`: необов’язкова часова позначка закріплення. Активні закріплені сеанси сортуються перед незакріпленими; архівування сеансу скасовує його закріплення.
- Сумісність із потоками Codex: обидва поля відповідають структурі керування потоками Codex — булеві значення `archived`/`pinned` у протоколі завжди обчислюються з часової позначки та встановлюються на сервері відповідно до семантики Codex `threads.archived_at` і серіалізації camelCase. OpenClaw використовує часові позначки в мілісекундах від початку епохи, а Codex — у секундах, тому мости виконують перетворення на межі Plugin `codex`. Codex ще не має API закріплення (лише `thread/archive`/`thread/unarchive`); стан закріплення залишається на боці OpenClaw, доки такий API не з’явиться, після чого відповідна структура дасть змогу механічно передавати стан закріплення пов’язаних сеансів в обох напрямках.
- Нагляд Codex показує лише неархівовані нативні потоки. Локальний для Gateway потік `idle` або `notLoaded` з невідомим станом активності можна архівувати через нативний `thread/archive` лише після явного підтвердження оператором, що ним не володіє жоден інший процес Codex; спочатку Plugin виконує нове локальне для процесу зчитування стану, після чого потік зникає з каталогу. Це зчитування не може довести, що потік не використовується іншим процесом App Server. OpenClaw відмовляється архівувати активні рядки та рядки з помилками, а архівування на спареному вузлі недоступне, доки міст вузла не зможе керувати повним життєвим циклом потокової передачі потоку. Розархівування в нативному клієнті Codex знову робить потік придатним для відображення.
- `lastReadAt` / `markedUnreadAt`: часові позначки стану прочитання, які встановлює сервер через `sessions.patch { unread }` — `unread: false` реєструє прочитання (установлює `lastReadAt`, очищає `markedUnreadAt`); `unread: true` позначає сеанс як непрочитаний до наступного прочитання. Рядки сеансів надають обчислюване булеве значення `unread`: явно позначено як непрочитаний або прочитано до останньої активності. Сеанси, які ніколи не позначалися як прочитані, залишаються `unread: false`, щоб наявні інсталяції не показували їх як нові після оновлення.
- `lastActivityAt`: часова позначка останнього завершеного запуску агента, який вважається активністю, гідною позначення як непрочитаної (запуски користувача, каналу та Cron). Ходи Heartbeat і внутрішніх подій, а також оновлення метаданих не змінюють її; `updatedAt` не є сигналом активності.
- `sessionFile`: застарілий маркер, збережений для сумісності з міграцією та архівуванням; активне середовище виконання використовує ідентичність SQLite
- `chatType`: `direct | group | room`
- `provider`, `subject`, `room`, `space`, `displayName`: метадані позначення групи/каналу
- Перемикачі: `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel`, `sendPolicy` (перевизначення для окремого сеансу)
- Вибір моделі: `providerOverride`, `modelOverride`, `authProfileOverride`
- Лічильники токенів (наскільки можливо, залежно від постачальника): `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`
- `compactionCount`: кількість завершень автоматичного ущільнення для цього ключа сеансу
- `memoryFlushAt` / `memoryFlushCompactionCount`: часова позначка та кількість ущільнень під час останнього скидання пам’яті перед ущільненням

Gateway є джерелом істини: він може перезаписувати або відновлювати записи під час
виконання сеансів. Для застарілих інсталяцій із файловим сховищем виконайте міграцію за допомогою
`openclaw doctor --session-sqlite import --session-sqlite-all-agents` замість
редагування `sessions.json` з очікуванням, що середовище виконання й надалі читатиме цей файл.

## Структура подій стенограми

Стенограмами керує засіб доступу до сеансів OpenClaw, а код середовища виконання отримує до них доступ через допоміжні засоби на основі ідентичності. Потік подій підтримує лише дописування:

- Перший запис: заголовок сеансу — `type: "session"`, `id`, `cwd`, `timestamp`, необов’язковий `parentSession`.
- Далі: записи з `id` + `parentId` (деревоподібна структура).

Важливі типи записів:

- `message`: повідомлення користувача/асистента/toolResult
- `custom_message`: повідомлення, додане розширенням, яке _входить_ до контексту моделі (відтворюється в TUI, коли `display: true`, і повністю приховується, коли `display: false`)
- `custom`: стан розширення, який _не входить_ до контексту моделі (для збереження стану розширення між перезавантаженнями)
- `compaction`: збережений підсумок ущільнення з `firstKeptEntryId` і `tokensBefore`
- `branch_summary`: збережений підсумок під час переходу гілкою дерева

OpenClaw навмисно не «виправляє» стенограми; Gateway використовує `SessionManager` для їх читання та запису.

## Вікна контексту та відстежувані токени

Два різні поняття:

1. **Вікно контексту моделі**: жорстке обмеження для кожної моделі (токени, видимі моделі). Надходить із каталогу моделей і може бути перевизначене через конфігурацію.
2. **Лічильники сховища сеансів**: накопичувальна статистика, записана в рядок сеансу (використовується для `/status` і панелей моніторингу). `contextTokens` — це оцінне значення або звіт середовища виконання; не вважайте його суворою гарантією.

Докладніше про обмеження: [/reference/token-use](/uk/reference/token-use).

## Compaction: що це таке

Compaction узагальнює давнішу розмову в збереженому записі `compaction` у стенограмі та залишає останні повідомлення без змін. Після Compaction наступні ходи бачать підсумок Compaction і повідомлення після `firstKeptEntryId`. Compaction є **стійким**, на відміну від очищення сеансів — див. [/concepts/session-pruning](/uk/concepts/session-pruning).

Повторне вставлення розділів AGENTS.md після Compaction вмикається за бажанням через `agents.defaults.compaction.postCompactionSections`; якщо значення не задано або встановлено `[]`, OpenClaw не додає фрагменти AGENTS.md поверх підсумку Compaction.

### Межі фрагментів і поєднання викликів інструментів

Під час поділу довгої стенограми на фрагменти для Compaction OpenClaw зберігає виклики інструментів асистента разом із відповідними записами `toolResult`:

- Якщо поділ за часткою токенів мав би пройти між викликом інструмента та його результатом, OpenClaw переносить межу до повідомлення асистента з викликом інструмента, а не розділяє цю пару.
- Якщо кінцевий блок результатів інструмента інакше перевищив би цільовий розмір фрагмента, OpenClaw зберігає цей незавершений блок інструмента та залишає неузагальнений кінець без змін.
- Перервані блоки викликів інструментів і блоки з помилками не утримують незавершений поділ відкритим.

## Коли відбувається автоматичний Compaction

Два тригери у вбудованому агенті OpenClaw:

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` та інші варіанти, характерні для постачальників) — виконується Compaction, а потім повторна спроба. Коли постачальник повідомляє кількість токенів у спробі, OpenClaw передає це спостережене значення до Compaction для відновлення після переповнення; якщо постачальник підтверджує переповнення, але не надає значення, яке можна розібрати, OpenClaw передає механізмам Compaction і діагностиці синтетичне значення, мінімально вище за ліміт. Якщо відновлення після переповнення все одно завершується невдало, OpenClaw показує чіткі вказівки та зберігає поточне зіставлення сеансу замість непомітного переходу до нового ідентифікатора сеансу — повторіть повідомлення, виконайте `/compact` або виконайте `/new`.
2. **Порогове обслуговування**: після успішного ходу, коли `contextTokens > contextWindow - reserveTokens`, де `contextWindow` — вікно контексту моделі, а `reserveTokens` — запас, зарезервований для запитів і наступного виведення моделі.

Поза цими двома тригерами діють ще два запобіжники:

- **Попередній локальний Compaction**: задайте `agents.defaults.compaction.maxActiveTranscriptBytes` (у байтах або як рядок на кшталт `"20mb"`), щоб запускати локальний Compaction перед відкриттям наступного запуску, щойно активна стенограма досягне цього розміру. Це обмеження розміру для вартості локального повторного відкриття, а не просте архівування — звичайний семантичний Compaction усе одно виконується та потребує `truncateAfterCompaction`, щоб ущільнений підсумок став новою наступною стенограмою.
- **Проміжна перевірка під час ходу**: задайте `agents.defaults.compaction.midTurnPrecheck.enabled: true` (за замовчуванням `false`), щоб додати запобіжник циклу інструментів. Після додавання результату інструмента й перед наступним викликом моделі OpenClaw оцінює навантаження на запит за тією самою логікою попереднього бюджету, яка використовується на початку ходу. Якщо контекст більше не вміщується, запобіжник не виконує Compaction безпосередньо — він створює структурований сигнал проміжної перевірки під час ходу, зупиняє поточне надсилання запиту та дає зовнішньому циклу запуску скористатися наявним шляхом відновлення (обрізати завеликі результати інструментів, якщо цього достатньо, або запустити налаштований режим Compaction і повторити спробу). Працює з обома режимами Compaction — `default` і `safeguard`, включно із запобіжним Compaction на боці постачальника. Не залежить від `maxActiveTranscriptBytes`: запобіжник за розміром у байтах спрацьовує перед відкриттям ходу, а проміжна перевірка — пізніше, після додавання нових результатів інструментів.

## Налаштування Compaction

```json5
{
  agents: {
    defaults: {
      compaction: {
        enabled: true,
        reserveTokens: 16384,
        keepRecentTokens: 20000,
      },
    },
  },
}
```

OpenClaw також установлює мінімальний безпечний поріг для вбудованих запусків: якщо `compaction.reserveTokens` нижче за `reserveTokensFloor` (типове значення — `20000`), OpenClaw підвищує його. Установіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути цей поріг. Коли відомий розмір контекстного вікна активної моделі, і мінімальний поріг, і остаточний ефективний резерв обмежуються так, щоб резерв не міг зайняти весь бюджет запиту. Завдяки цьому моделі з малим контекстом (наприклад, локальна модель із контекстом у 16K токенів) не починають ущільнення вже з першого токена; якщо контекстне вікно невідоме, налаштований і поточний бюджети резерву залишаються необмеженими. Навіщо взагалі потрібен мінімальний поріг: щоб залишити достатньо запасу для багатоходового «службового обслуговування» (як-от скидання пам’яті, описане нижче), перш ніж ущільнення стане неминучим. Реалізація: `applyAgentCompactionSettingsFromConfig()` у `src/agents/agent-settings.ts`, що викликається зі шляхів налаштування ходу вбудованого засобу запуску та ущільнення.

Ручний `/compact` враховує явно заданий `agents.defaults.compaction.keepRecentTokens` і зберігає точку відсікання нещодавньої кінцевої частини середовища виконання. Без явно заданого бюджету збереження ручне ущільнення є жорсткою контрольною точкою, а перебудований контекст починається з нового підсумку.

Коли ввімкнено `truncateAfterCompaction`, OpenClaw після ущільнення перемикає активну стенограму на ущільненого наступника. Дії створення гілки або відновлення контрольної точки використовують цього ущільненого наступника; застарілі файли контрольних точок до ущільнення залишаються доступними для читання, доки на них є посилання.

## Підключувані постачальники ущільнення

Плагіни реєструють постачальника ущільнення через `registerCompactionProvider()` в API плагіна. Коли для `agents.defaults.compaction.provider` задано ідентифікатор зареєстрованого постачальника, розширення запобіжного механізму делегує створення підсумку цьому постачальнику замість вбудованого конвеєра `summarizeInStages`.

- `provider`: ідентифікатор зареєстрованого плагіна постачальника ущільнення. Не задавайте його, щоб використовувати типове створення підсумку за допомогою LLM. Задання `provider` примусово вмикає `mode: "safeguard"`.
- Постачальники отримують ті самі інструкції з ущільнення та політику збереження ідентифікаторів, що й вбудований шлях, а запобіжний механізм після отримання результату постачальника й надалі зберігає контекст суфікса останніх ходів і розділеного ходу.
- Вбудоване створення підсумку запобіжним механізмом повторно узагальнює попередні підсумки разом із новими повідомленнями, а не зберігає весь попередній підсумок дослівно.
- Режим запобіжного механізму типово вмикає перевірки якості підсумку; установіть `qualityGuard.enabled: false`, щоб пропустити повторну спробу в разі некоректно сформованого результату.
- Якщо постачальник завершується помилкою або повертає порожній результат, OpenClaw автоматично повертається до вбудованого створення підсумку за допомогою LLM. Сигнали переривання або завершення за тайм-аутом, які явно ініціював викликач, передаються далі, а не приховуються, тому скасування завжди враховується.

Джерело: `src/plugins/compaction-provider.ts`, `src/agents/agent-hooks/compaction-safeguard.ts`.

## Видимі користувачеві поверхні

- `/status` у будь-якому сеансі чату
- `openclaw status` (CLI)
- `openclaw sessions` / `openclaw sessions --json`
- Журнали Gateway (`pnpm gateway:watch` або `openclaw logs --follow`): `embedded run auto-compaction start` + `complete`
- Докладний режим: `🧹 Auto-compaction complete` разом із кількістю ущільнень

## Безшумне службове обслуговування (`NO_REPLY`)

OpenClaw підтримує «безшумні» ходи для фонових завдань, проміжні результати яких користувач не повинен бачити.

- Асистент починає свій результат із точного безшумного токена `NO_REPLY` / `no_reply`, що означає «не доставляти відповідь користувачеві». OpenClaw видаляє або приховує його на рівні доставки.
- Приховування точного безшумного токена не залежить від регістру: `NO_REPLY` і `no_reply` однаково враховуються, якщо все корисне навантаження складається лише з безшумного токена.
- Починаючи з `2026.1.10`, OpenClaw також приховує потокове передавання чернетки або індикатора введення, коли частковий фрагмент починається з `NO_REPLY`, щоб безшумні операції не розкривали частковий результат посеред ходу.
- Це призначено лише для справжніх фонових ходів без доставки — це не скорочений спосіб обробки звичайних дієвих запитів користувача.

## Скидання пам’яті перед ущільненням

Перед автоматичним ущільненням OpenClaw може виконати безшумний агентний хід, який записує довготривалий стан на диск (наприклад, `memory/YYYY-MM-DD.md` у робочому просторі агента), щоб ущільнення не могло стерти критично важливий контекст. OpenClaw відстежує використання контексту сеансу, і щойно воно перетинає м’який поріг нижче за поріг ущільнення, надсилає безшумну директиву «записати пам’ять зараз» із точним безшумним токеном `NO_REPLY` / `no_reply`, тому користувач нічого не бачить.

Конфігурація (`agents.defaults.compaction.memoryFlush`), повний довідник: [/gateway/config-agents](/uk/gateway/config-agents#agentsdefaultscompaction)

| Ключ                        | Типове значення   | Примітки                                                                                                                               |
| --------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`                   | `true`           |                                                                                                                                        |
| `model`                     | не задано        | точне перевизначення постачальника/моделі лише для ходу скидання, наприклад `ollama/qwen3:8b`                                          |
| `softThresholdTokens`       | `4000`           | відступ нижче за поріг ущільнення, який запускає скидання                                                                               |
| `forceFlushTranscriptBytes` | не задано (вимкнено) | примусово виконати скидання, щойно файл стенограми досягне цього розміру в байтах (або значення-рядка на кшталт `"2mb"`), навіть якщо лічильники токенів застаріли; `0` вимикає |
| `prompt`                    | вбудоване        | повідомлення користувача для ходу скидання                                                                                              |
| `systemPrompt`              | вбудоване        | додатковий системний запит, доданий до ходу скидання                                                                                     |

Примітки:

- Типовий запит і системний запит містять підказку `NO_REPLY` для приглушення доставки.
- Коли задано `model`, хід скидання використовує цю модель, не успадковуючи ланцюжок резервних варіантів активного сеансу, тому локальне службове обслуговування в разі помилки непомітно не перемикається на платну розмовну модель.
- Скидання виконується один раз за цикл ущільнення (відстежується в рядку сеансу).
- Скидання виконується лише для вбудованих сеансів OpenClaw; серверні частини CLI та ходи Heartbeat його пропускають.
- Скидання пропускається, коли робочий простір сеансу доступний лише для читання (`workspaceAccess: "ro"` або `"none"`).
- Структуру файлів робочого простору та шаблони запису див. у розділі [Пам’ять](/uk/concepts/memory).

OpenClaw надає обробник `session_before_compact` в API розширень, але описана вище логіка скидання розташована на боці Gateway (`src/auto-reply/reply/memory-flush.ts`, `src/auto-reply/reply/agent-runner-memory.ts`), а не в цьому обробнику.

## Контрольний список усунення несправностей

- **Неправильний ключ сеансу?** Почніть із [/concepts/session](/uk/concepts/session) і перевірте `sessionKey` у `/status`.
- **Невідповідність між сховищем і стенограмою?** Перевірте хост Gateway і шлях до сховища з `openclaw status`.
- **Надмірно часті ущільнення?** Перевірте контекстне вікно моделі (надто мале вікно спричиняє часте ущільнення), `reserveTokens` (надто велике значення для вікна моделі спричиняє раніше ущільнення) та надмірний обсяг результатів інструментів (налаштуйте скорочення сеансу).
- **Здається, що кожен запит переповнює малу локальну модель?** Перевірте, чи постачальник повідомляє правильний розмір контекстного вікна моделі. OpenClaw може обмежити ефективний резерв, лише коли розмір цього вікна відомий.
- **Безшумні ходи розкривають результат?** Перевірте, чи відповідь починається з точного безшумного токена `NO_REPLY` (без урахування регістру) і чи використовується збірка з виправленням приглушення потокового передавання (`2026.1.10`+).

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

- [Керування сеансами](/uk/concepts/session)
- [Скорочення сеансу](/uk/concepts/session-pruning)
- [Рушій контексту](/uk/concepts/context-engine)
- [Довідник конфігурації агента](/uk/gateway/config-agents)
