---
read_when:
    - Вам нужно отладить идентификаторы сеансов, события транскрипта или поля строк сеанса
    - Вы изменяете поведение автоматической Compaction или добавляете служебные операции «перед Compaction»
    - Вы хотите реализовать сброс памяти или безмолвные системные ходы
summary: 'Подробный разбор: хранилище сеансов и транскрипты, жизненный цикл и внутреннее устройство (автоматической) Compaction'
title: Подробный разбор управления сеансами
x-i18n:
    generated_at: "2026-07-16T17:27:34Z"
    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, веб-интерфейс управления, TUI) запрашивают у Gateway списки сеансов и количество токенов. В удалённом режиме файлы сеансов находятся на удалённом хосте, поэтому проверка файлов на локальном Mac не покажет, что использует Gateway.

Сначала ознакомьтесь с обзорной документацией: [Управление сеансами](/ru/concepts/session), [Compaction](/ru/concepts/compaction), [Обзор памяти](/ru/concepts/memory), [Поиск по памяти](/ru/concepts/memory-search), [Очистка сеансов](/ru/concepts/session-pruning), [Гигиена стенограмм](/ru/reference/transcript-hygiene); полное справочное руководство по конфигурации см. в разделе [Конфигурация агента](/ru/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](/ru/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](/ru/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`, когда сообщение поступает после окончания периода бездействия. Если настроены и ежедневный сброс, и сброс по бездействию, срабатывает тот, срок которого истекает раньше.
- **Возобновление после переподключения Control UI** сохраняет текущий видимый сеанс для одной отправки после переподключения, когда Gateway получает соответствующий `sessionId` от клиентского интерфейса оператора. Это одноразовый сигнал; обычные устаревшие отправки по-прежнему создают новый `sessionId`.
- **Системные события** (Heartbeat, пробуждения Cron, уведомления exec, служебные операции 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 и exec не поддерживали сеансы активными. Для устаревших строк без этого поля используется восстановленное время начала сеанса.
- `updatedAt`: временная метка последнего изменения строки хранилища, используемая для вывода списков, очистки и служебных операций, но не для определения актуальности ежедневного сброса или сброса по бездействию.
- `archivedAt`: необязательная временная метка архивации. Архивированные сеансы остаются в хранилище с неповреждённым транскриптом и исключаются из обычных списков активных сеансов.
- `pinnedAt`: необязательная временная метка закрепления. Активные закреплённые сеансы сортируются перед незакреплёнными; архивация сеанса снимает его закрепление.
- Совместимость с потоками Codex: оба поля соответствуют форме управления потоками Codex — логические значения `archived`/`pinned`, передаваемые по протоколу, всегда вычисляются из временной метки и устанавливаются на стороне сервера в соответствии с семантикой Codex `threads.archived_at` и сериализацией camelCase. Временные метки OpenClaw представлены миллисекундами эпохи, а Codex использует секунды эпохи, поэтому мосты выполняют преобразование на границе плагина `codex`. В Codex пока нет API закрепления (только `thread/archive`/`thread/unarchive`); до его появления состояние закрепления остаётся на стороне OpenClaw, после чего соответствующая форма позволит связанным сеансам механически передавать состояние закрепления в обе стороны.
- Средства наблюдения Codex отображают только неархивированные нативные потоки. Локальный для Gateway поток `idle` или поток с неизвестной активностью `notLoaded` можно архивировать через нативный `thread/archive` только после явного подтверждения оператором, что он не принадлежит другому процессу Codex; сначала плагин повторно считывает локальное для процесса состояние, после чего поток исчезает из каталога. Это считывание не может доказать, что поток не используется другим процессом 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`: количество завершений автоматической Compaction для этого ключа сеанса
- `memoryFlushAt` / `memoryFlushCompactionCount`: временная метка и количество операций Compaction при последнем сбросе памяти перед Compaction

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`: сохранённая сводка Compaction с `firstKeptEntryId` и `tokensBefore`
- `branch_summary`: сохранённая сводка при переходе по ветви дерева

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

## Окна контекста и отслеживаемые токены

Это два разных понятия:

1. **Окно контекста модели**: жёсткий предел для каждой модели (токены, видимые модели). Значение берётся из каталога моделей и может быть переопределено в конфигурации.
2. **Счётчики хранилища сеансов**: скользящая статистика, записываемая в строку сеанса (используется для `/status` и панелей мониторинга). `contextTokens` — оценочное значение среды выполнения для отчётности; не считайте его строгой гарантией.

Подробнее об ограничениях: [/reference/token-use](/ru/reference/token-use).

## Compaction: что это такое

Compaction сводит старую часть беседы в сохранённую запись `compaction` в транскрипте и сохраняет последние сообщения без изменений. После Compaction последующие ходы видят сводку Compaction и сообщения после `firstKeptEntryId`. Compaction является **постоянной**, в отличие от очистки сеанса — см. [/concepts/session-pruning](/ru/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 токенов) переходить к Compaction с первого токена; если окно контекста неизвестно, настроенный и текущий бюджеты резерва не ограничиваются. Зачем вообще нужен минимальный резерв: чтобы оставить достаточно свободного места для многоходовых «служебных операций» (например, описанного ниже сброса памяти) до того, как Compaction станет неизбежным. Реализация: `applyAgentCompactionSettingsFromConfig()` в `src/agents/agent-settings.ts`, вызывается из путей настройки хода встроенного средства запуска и Compaction.

Ручная `/compact` учитывает явно заданный `agents.defaults.compaction.keepRecentTokens` и сохраняет определённую средой выполнения точку отсечения недавнего хвоста. Если бюджет сохраняемого контекста явно не задан, ручная Compaction служит жёсткой контрольной точкой, а восстановленный контекст начинается с новой сводки.

Когда включён `truncateAfterCompaction`, после Compaction OpenClaw переключает активную расшифровку на её сжатого преемника. Действия создания ветви и восстановления контрольной точки используют этого сжатого преемника; устаревшие файлы контрольных точек до Compaction остаются доступными для чтения, пока на них имеются ссылки.

## Подключаемые поставщики Compaction

Плагины регистрируют поставщика Compaction через `registerCompactionProvider()` в API плагина. Когда `agents.defaults.compaction.provider` содержит идентификатор зарегистрированного поставщика, расширение защитного механизма делегирует создание сводки этому поставщику вместо встроенного конвейера `summarizeInStages`.

- `provider`: идентификатор зарегистрированного плагина — поставщика Compaction. Не задавайте его, чтобы использовать стандартное создание сводки посредством LLM. Задание `provider` принудительно включает `mode: "safeguard"`.
- Поставщики получают те же инструкции Compaction и политику сохранения идентификаторов, что и встроенный путь, а защитный механизм после вывода поставщика по-прежнему сохраняет контекст суффикса недавних и разделённых ходов.
- Встроенное создание сводки защитным механизмом повторно дистиллирует предыдущие сводки вместе с новыми сообщениями, а не сохраняет всю предыдущую сводку дословно.
- Режим защитного механизма по умолчанию включает проверки качества сводки; задайте `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` и число операций Compaction

## Фоновые служебные операции без вывода (`NO_REPLY`)

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

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

## Сброс памяти перед Compaction

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

Конфигурация (`agents.defaults.compaction.memoryFlush`), полное описание см. в разделе [/gateway/config-agents](/ru/gateway/config-agents#agentsdefaultscompaction):

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

Примечания:

- Стандартный промпт и системный промпт содержат подсказку `NO_REPLY` для подавления доставки.
- Когда задан `model`, ход сброса использует эту модель, не наследуя цепочку резервных моделей активного сеанса, поэтому при сбое локальные служебные операции не переключаются незаметно на платную диалоговую модель.
- Сброс выполняется один раз за цикл Compaction (это отслеживается в строке сеанса).
- Сброс выполняется только для встроенных сеансов OpenClaw; серверные части CLI и ходы Heartbeat пропускают его.
- Сброс пропускается, когда рабочая область сеанса доступна только для чтения (`workspaceAccess: "ro"` или `"none"`).
- Структуру файлов рабочей области и способы записи см. в разделе [Память](/ru/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](/ru/concepts/session) и проверьте `sessionKey` в `/status`.
- **Хранилище и расшифровка не соответствуют друг другу?** Проверьте хост Gateway и путь к хранилищу из `openclaw status`.
- **Compaction запускается слишком часто?** Проверьте окно контекста модели (слишком маленькое окно приводит к частой Compaction), `reserveTokens` (слишком большое значение для окна модели приводит к более ранней Compaction) и разрастание результатов инструментов (настройте обрезку сеанса).
- **На небольшой локальной модели каждый промпт, похоже, переполняет контекст?** Убедитесь, что поставщик сообщает правильный размер окна контекста модели. OpenClaw может ограничить эффективный резерв, только когда это окно известно.
- **Безмолвные ходы приводят к утечке вывода?** Убедитесь, что ответ начинается с точного безмолвного токена `NO_REPLY` без учёта регистра и используется сборка с исправлением подавления потоковой передачи (`2026.1.10`+).

## См. также

- [Управление сеансами](/ru/concepts/session)
- [Обрезка сеанса](/ru/concepts/session-pruning)
- [Механизм контекста](/ru/concepts/context-engine)
- [Справочник по конфигурации агента](/ru/gateway/config-agents)
