Управление сессиями и компакция (глубокий разбор)

Этот документ объясняет, как OpenClaw управляет сессиями от начала до конца:

  • Маршрутизация сессий (как входящие сообщения сопоставляются с sessionKey)
  • Хранилище сессий (sessions.json) и что отслеживается
  • Персистенция транскриптов (*.jsonl) и их структура
  • Гигиена транскриптов (провайдер-специфичные исправления)
  • Лимиты контекста (окно контекста vs отслеживаемые токены)
  • Компакция (ручная + автоматическая) и хуки пред-компакции
  • Тихое обслуживание (например, запись в память без видимого вывода)

Для обзора высокого уровня:

Источник истины: Gateway

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

  • UI (macOS приложение, веб Control UI, TUI) должны запрашивать Gateway для списков сессий и счётчиков токенов
  • В удалённом режиме файлы сессий находятся на удалённом хосте

Два уровня персистенции

Хранилище сессий (sessions.json)

  • Карта ключ/значение: sessionKey -> SessionEntry
  • Маленькое, изменяемое, безопасно для редактирования
  • Отслеживает метаданные сессии (текущий ID сессии, последняя активность, переключатели, счётчики токенов)

Транскрипт (.jsonl)

  • Транскрипт только для добавления с древовидной структурой (записи имеют id + parentId)
  • Хранит фактический разговор + вызовы инструментов + сводки компакции
  • Используется для восстановления контекста модели

Расположение на диске

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

  • Хранилище: ~/.openclaw/agents/<agent>/sessions/sessions.json
  • Транскрипты: ~/.openclaw/agents/<agent>/sessions/<sessionId>.jsonl

Ключи сессий (sessionKey)

sessionKey определяет, в каком разговорном контейнере вы находитесь (маршрутизация + изоляция).

Типичные паттерны:

  • Основной/прямой чат: agent:<agent>:<provider>
  • Группа: agent:<agent>:<provider>:group:<groupId>
  • Канал (Discord/Slack): agent:<agent>:<provider>:channel:<channelId>
  • Cron: cron:<jobId>

Компакция: обзор

Компакция суммирует старую переписку в постоянную запись компакции в транскрипте и сохраняет недавние сообщения.

После компакции будущие ходы видят:

  • Сводку компакции
  • Сообщения после firstKeptEntryId

Компакция постоянна (в отличие от обрезки сессий). См. /concepts/session-pruning.

Когда срабатывает автокомпакция

  1. Восстановление при переполнении: модель возвращает ошибку переполнения контекста → компакция → повтор
  2. Поддержание порога: после успешного хода, когда contextTokens > contextWindow - reserveTokens

Настройки компакции

\{
  "compaction": \{
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  \}
\}

OpenClaw также применяет нижний предел безопасности: если compaction.reserveTokens < 16384, повышает до 16384.

Пред-компакционный «сброс памяти»

Цель: перед автокомпакцией выполнить тихий агентный ход, записывающий состояние на диск (например, memory/YYYY-MM-DD.md).

Настройка (agents.defaults.compaction.memoryFlush):

  • enabled (по умолчанию: true)
  • softThresholdTokens (по умолчанию: 4000)
  • prompt (сообщение для хода сброса)
  • systemPrompt (дополнительный системный промпт)

Устранение неполадок

  • Неправильный ключ сессии? Начните с /concepts/session и проверьте sessionKey в /status
  • Спам компакции? Проверьте окно контекста модели, настройки компакции, раздутие результатов инструментов
  • Утечка тихих ходов? Убедитесь, что ответ начинается с NO_REPLY
← Назад к документации