---
read_when:
    - Вам потрібно діагностувати ідентифікатори сеансів, JSONL транскрипту або поля sessions.json
    - Ви змінюєте поведінку автоматичного Compaction або додаєте службові дії перед Compaction
    - Ви хочете реалізувати очищення пам’яті або тихі системні репліки
summary: 'Поглиблений розбір: сховище сеансів + транскрипти, життєвий цикл і внутрішній устрій (авто)Compaction'
title: Поглиблений огляд керування сеансами
x-i18n:
    generated_at: "2026-04-28T11:25:07Z"
    model: gpt-5.5
    provider: openai
    source_hash: 1e9785723ebf9b5411440a8f3b2885a50d659f669811ba749c431a2b3aeed700
    source_path: reference/session-management-compaction.md
    workflow: 16
---

OpenClaw керує сеансами від початку до кінця в таких областях:

- **Маршрутизація сеансів** (як вхідні повідомлення зіставляються з `sessionKey`)
- **Сховище сеансів** (`sessions.json`) і те, що воно відстежує
- **Збереження транскриптів** (`*.jsonl`) і їхня структура
- **Гігієна транскриптів** (виправлення, специфічні для провайдера, перед запусками)
- **Обмеження контексту** (вікно контексту проти відстежуваних токенів)
- **Compaction** (ручна й автоматична Compaction) і де підключати роботу перед Compaction
- **Тихе обслуговування** (записи в пам’ять, які не повинні створювати видимий для користувача вивід)

Якщо спершу потрібен загальніший огляд, почніть із:

- [Керування сеансами](/uk/concepts/session)
- [Compaction](/uk/concepts/compaction)
- [Огляд пам’яті](/uk/concepts/memory)
- [Пошук у пам’яті](/uk/concepts/memory-search)
- [Очищення сеансів](/uk/concepts/session-pruning)
- [Гігієна транскриптів](/uk/reference/transcript-hygiene)

---

## Джерело істини: Gateway

OpenClaw спроєктовано навколо одного **процесу Gateway**, який володіє станом сеансів.

- UI (застосунок macOS, веб Control UI, TUI) мають запитувати Gateway щодо списків сеансів і кількості токенів.
- У віддаленому режимі файли сеансів розташовані на віддаленому хості; «перевірка локальних файлів Mac» не відображатиме того, що використовує Gateway.

---

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

OpenClaw зберігає сеанси на двох рівнях:

1. **Сховище сеансів (`sessions.json`)**
   - Мапа ключ/значення: `sessionKey -> SessionEntry`
   - Невелике, змінюване, безпечне для редагування (або видалення записів)
   - Відстежує метадані сеансів (поточний ідентифікатор сеансу, останню активність, перемикачі, лічильники токенів тощо)

2. **Транскрипт (`<sessionId>.jsonl`)**
   - Транскрипт лише з додаванням із деревоподібною структурою (записи мають `id` + `parentId`)
   - Зберігає фактичну розмову + виклики інструментів + підсумки Compaction
   - Використовується для відновлення контексту моделі для майбутніх ходів
   - Великі налагоджувальні контрольні точки перед Compaction пропускаються, щойно активний
     транскрипт перевищує ліміт розміру контрольної точки, щоб уникнути другої гігантської
     копії `.checkpoint.*.jsonl`.

---

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

Для кожного агента на хості Gateway:

- Сховище: `~/.openclaw/agents/<agentId>/sessions/sessions.json`
- Транскрипти: `~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
  - Сеанси тем Telegram: `.../<sessionId>-topic-<threadId>.jsonl`

OpenClaw визначає ці шляхи через `src/config/sessions.ts`.

---

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

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

- `mode`: `warn` (за замовчуванням) або `enforce`
- `pruneAfter`: поріг віку застарілих записів (за замовчуванням `30d`)
- `maxEntries`: ліміт записів у `sessions.json` (за замовчуванням `500`)
- `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.<timestamp>` (за замовчуванням: такий самий, як `pruneAfter`; `false` вимикає очищення)
- `maxDiskBytes`: необов’язковий бюджет каталогу сеансів
- `highWaterBytes`: необов’язкова ціль після очищення (за замовчуванням `80%` від `maxDiskBytes`)

Звичайні записи Gateway пакетно виконують очищення `maxEntries` для лімітів виробничого розміру, тому сховище може короткочасно перевищити налаштований ліміт, перш ніж наступне очищення верхньої межі перепише його до меншого розміру. `openclaw sessions cleanup --enforce` усе ще негайно застосовує налаштований ліміт.

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

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

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

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

Запустіть обслуговування на вимогу:

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

---

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

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

- `cron.sessionRetention` (за замовчуванням `24h`) очищає старі ізольовані сеанси запусків Cron зі сховища сеансів (`false` вимикає).
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` очищають файли `~/.openclaw/cron/runs/<jobId>.jsonl` (за замовчуванням: `2_000_000` байтів і `2000` рядків).

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

---

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

`sessionKey` визначає, у якому _кошикові розмови_ ви перебуваєте (маршрутизація + ізоляція).

Поширені шаблони:

- Основний/прямий чат (для кожного агента): `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>` (якщо не перевизначено)

Канонічні правила задокументовано в [/concepts/session](/uk/concepts/session).

---

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

Кожен `sessionKey` вказує на поточний `sessionId` (файл транскрипту, який продовжує розмову).

Орієнтовні правила:

- **Скидання** (`/new`, `/reset`) створює новий `sessionId` для цього `sessionKey`.
- **Щоденне скидання** (за замовчуванням о 4:00 AM за локальним часом на хості gateway) створює новий `sessionId` під час наступного повідомлення після межі скидання.
- **Завершення через бездіяльність** (`session.reset.idleMinutes` або застарілий `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна бездіяльності. Коли налаштовано і щоденне скидання, і бездіяльність, спрацьовує те, що завершується першим.
- **Системні події** (heartbeat, пробудження cron, сповіщення exec, службове ведення обліку gateway) можуть змінювати рядок сеансу, але не продовжують свіжість щоденного/бездіяльного скидання. Перехід скидання відкидає сповіщення системних подій у черзі для попереднього сеансу перед побудовою свіжого запиту.
- **Захист від форку батьківського потоку** (`session.parentForkMaxTokens`, за замовчуванням `100000`) пропускає форк батьківського транскрипту, коли батьківський сеанс уже завеликий; новий потік починається заново. Установіть `0`, щоб вимкнути.

Деталь реалізації: рішення відбувається в `initSessionState()` у `src/auto-reply/reply/session.ts`.

---

## Схема сховища сеансів (`sessions.json`)

Тип значення сховища — `SessionEntry` у `src/config/sessions.ts`.

Ключові поля (не вичерпно):

- `sessionId`: поточний ідентифікатор транскрипту (ім’я файла виводиться з нього, якщо не задано `sessionFile`)
- `sessionStartedAt`: почасова мітка початку для поточного `sessionId`; щоденне скидання
  використовує її для визначення свіжості. Застарілі рядки можуть виводити її із заголовка сеансу JSONL.
- `lastInteractionAt`: почасова мітка останньої реальної взаємодії користувача/каналу; скидання через бездіяльність
  використовує її для визначення свіжості, тож heartbeat, cron і події exec не підтримують сеанси
  активними. Застарілі рядки без цього поля повертаються до відновленого часу початку сеансу
  для свіжості бездіяльності.
- `updatedAt`: почасова мітка останньої зміни рядка сховища, використовується для переліку, очищення та
  службового обліку. Вона не є авторитетним джерелом для свіжості щоденного/бездіяльного скидання.
- `sessionFile`: необов’язкове явне перевизначення шляху транскрипту
- `chatType`: `direct | group | room` (допомагає UI та політиці надсилання)
- `provider`, `subject`, `room`, `space`, `displayName`: метадані для позначення груп/каналів
- Перемикачі:
  - `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel`
  - `sendPolicy` (перевизначення для окремого сеансу)
- Вибір моделі:
  - `providerOverride`, `modelOverride`, `authProfileOverride`
- Лічильники токенів (найкращі зусилля / залежні від провайдера):
  - `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`
- `compactionCount`: як часто автоматична Compaction завершувалася для цього ключа сеансу
- `memoryFlushAt`: почасова мітка останнього скидання пам’яті перед Compaction
- `memoryFlushCompactionCount`: кількість Compaction на момент останнього скидання

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

---

## Структура транскрипту (`*.jsonl`)

Транскриптами керує `SessionManager` із `@mariozechner/pi-coding-agent`.

Файл має формат JSONL:

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

Помітні типи записів:

- `message`: повідомлення користувача/асистента/результату інструмента
- `custom_message`: повідомлення, впроваджені розширенням, які _входять_ у контекст моделі (можуть бути приховані від UI)
- `custom`: стан розширення, який _не входить_ у контекст моделі
- `compaction`: збережений підсумок Compaction з `firstKeptEntryId` і `tokensBefore`
- `branch_summary`: збережений підсумок під час навігації гілкою дерева

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

---

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

Мають значення два різні поняття:

1. **Вікно контексту моделі**: жорсткий ліміт для кожної моделі (токени, видимі моделі)
2. **Лічильники сховища сеансів**: ковзна статистика, записана в `sessions.json` (використовується для /status і панелей керування)

Якщо ви налаштовуєте ліміти:

- Вікно контексту береться з каталогу моделей (і може бути перевизначене через конфігурацію).
- `contextTokens` у сховищі — це оцінка/звітне значення середовища виконання; не вважайте його строгою гарантією.

Докладніше див. [/token-use](/uk/reference/token-use).

---

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

Compaction підсумовує старішу розмову в збережений запис `compaction` у транскрипті та зберігає останні повідомлення без змін.

Після Compaction майбутні ходи бачать:

- Підсумок Compaction
- Повідомлення після `firstKeptEntryId`

Compaction є **постійною** (на відміну від очищення сеансів). Див. [/concepts/session-pruning](/uk/concepts/session-pruning).

## Межі блоків Compaction і парування інструментів

Коли OpenClaw розбиває довгий транскрипт на блоки Compaction, він зберігає
виклики інструментів асистента в парі з відповідними записами `toolResult`.

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

---

## Коли відбувається автоматична Compaction (середовище виконання Pi)

У вбудованому агенті 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. **Обслуговування порогу**: після успішного ходу, коли:

`contextTokens > contextWindow - reserveTokens`

Де:

- `contextWindow` — це вікно контексту моделі
- `reserveTokens` — це запас, зарезервований для запитів + наступного виводу моделі

Це семантика середовища виконання Pi (OpenClaw споживає події, але Pi вирішує, коли виконувати Compaction).

OpenClaw також може запускати попередню локальну Compaction перед відкриттям наступного
запуску, коли задано `agents.defaults.compaction.maxActiveTranscriptBytes`, а
активний файл транскрипту досягає цього розміру. Це захист за розміром файла для вартості локального
повторного відкриття, а не сирого архівування: OpenClaw все одно виконує звичайну семантичну Compaction,
і для цього потрібен `truncateAfterCompaction`, щоб стиснений підсумок міг стати
новим транскриптом-наступником.

---

## Налаштування Compaction (`reserveTokens`, `keepRecentTokens`)

Налаштування Compaction Pi розташовані в налаштуваннях Pi:

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

OpenClaw також застосовує безпечну нижню межу для вбудованих запусків:

- Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw підвищує це значення.
- Стандартна нижня межа — `20000` токенів.
- Установіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути цю межу.
- Якщо значення вже вище, OpenClaw залишає його без змін.
- Ручний `/compact` враховує явно заданий `agents.defaults.compaction.keepRecentTokens`
  і зберігає точку відсікання недавнього хвоста Pi. Без явно заданого бюджету збереження
  ручний Compaction лишається жорсткою контрольною точкою, а перебудований контекст починається з
  нового підсумку.
- Установіть `agents.defaults.compaction.maxActiveTranscriptBytes` у байтове значення або
  рядок на кшталт `"20mb"`, щоб запускати локальний Compaction перед ходом, коли активний
  транскрипт стає великим. Цей захист активний лише коли
  `truncateAfterCompaction` також увімкнено. Залиште це значення незаданим або встановіть `0`, щоб
  вимкнути.
- Коли `agents.defaults.compaction.truncateAfterCompaction` увімкнено,
  OpenClaw після Compaction переносить активний транскрипт у компактніший наступний JSONL.
  Старий повний транскрипт лишається в архіві та прив’язується з контрольної точки
  Compaction замість перезапису на місці.

Навіщо: залишити достатньо запасу для багатоходового “обслуговування” (наприклад, записів у пам’ять) до того, як Compaction стане неминучим.

Реалізація: `ensurePiCompactionReserveTokens()` у `src/agents/pi-settings.ts`
(викликається з `src/agents/pi-embedded-runner.ts`).

---

## Підключувані провайдери Compaction

Plugin може зареєструвати провайдера Compaction через `registerCompactionProvider()` в API Plugin. Коли `agents.defaults.compaction.provider` встановлено в id зареєстрованого провайдера, розширення-запобіжник делегує підсумовування цьому провайдеру замість вбудованого конвеєра `summarizeInStages`.

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

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

---

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

Ви можете спостерігати Compaction і стан сесії через:

- `/status` (у будь-якій чат-сесії)
- `openclaw status` (CLI)
- `openclaw sessions` / `sessions --json`
- Докладний режим: `🧹 Auto-compaction complete` + кількість Compaction

---

## Тихе обслуговування (`NO_REPLY`)

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

Угода:

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

Починаючи з `2026.1.10`, OpenClaw також пригнічує **потокову передачу чернетки/набору тексту**, коли
частковий фрагмент починається з `NO_REPLY`, тож тихі операції не протікають частковим
виводом посеред ходу.

---

## "Скидання пам’яті" перед Compaction (реалізовано)

Мета: до автоматичного Compaction запустити тихий агентний хід, який записує довговічний
стан на диск (наприклад, `memory/YYYY-MM-DD.md` у робочій області агента), щоб Compaction не міг
стерти критичний контекст.

OpenClaw використовує підхід **скидання перед порогом**:

1. Відстежувати використання контексту сесії.
2. Коли воно перетинає “м’який поріг” (нижче порога Compaction Pi), запустити тиху
   директиву “запиши пам’ять зараз” для агента.
3. Використати точний тихий токен `NO_REPLY` / `no_reply`, щоб користувач не бачив
   нічого.

Конфігурація (`agents.defaults.compaction.memoryFlush`):

- `enabled` (типово: `true`)
- `model` (необов’язкове точне перевизначення провайдера/моделі для ходу скидання, наприклад `ollama/qwen3:8b`)
- `softThresholdTokens` (типово: `4000`)
- `prompt` (повідомлення користувача для ходу скидання)
- `systemPrompt` (додатковий системний prompt, доданий для ходу скидання)

Нотатки:

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

Pi також надає хук `session_before_compact` в API розширення, але логіка скидання OpenClaw
сьогодні живе на боці Gateway.

---

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

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

## Пов’язане

- [Керування сесіями](/uk/concepts/session)
- [Обрізання сесії](/uk/concepts/session-pruning)
- [Рушій контексту](/uk/concepts/context-engine)
