​

Управление сеансами и уплотнение (подробный разбор)

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

• /concepts/session
• /concepts/compaction
• /concepts/session-pruning
• /reference/transcript-hygiene

​

Источник истины: Gateway (шлюз)

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

​

Два уровня сохранения

1. Хранилище сеансов (sessions.json)
   • Карта ключ/значение: sessionKey -> SessionEntry
   • Небольшое, изменяемое, безопасно для редактирования (или удаления записей)
   • Отслеживает метаданные сеанса (текущий идентификатор сеанса, последнюю активность, переключатели, счётчики токенов и т. д.)
2. Транскрипт (<sessionId>.jsonl)
   • Только добавляемый транскрипт с древовидной структурой (записи имеют id + parentId)
   • Хранит фактический диалог + вызовы инструментов + сводки уплотнения
   • Используется для восстановления контекста модели в будущих ходах

​

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

• Хранилище: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Транскрипты: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Сеансы тем Telegram: .../<sessionId>-topic-<threadId>.jsonl

​

Ключи сеансов (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> (если не переопределено)

​

Идентификаторы сеансов (sessionId)

• Сброс (/new, /reset) создаёт новый sessionId для данного sessionKey.
• Ежедневный сброс (по умолчанию 4:00 утра по локальному времени на хосте шлюза Gateway) создаёт новый sessionId при следующем сообщении после границы сброса.
• Истечение по бездействию (session.reset.idleMinutes или устаревший session.idleMinutes) создаёт новый sessionId, когда сообщение приходит после окна простоя. Если настроены и ежедневный сброс, и бездействие, срабатывает то, что истекает раньше.

​

Схема хранилища сеансов (sessions.json)

• sessionId: текущий идентификатор транскрипта (имя файла выводится из него, если не задан sessionFile)
• updatedAt: отметка времени последней активности
• sessionFile: необязательное явное переопределение пути к транскрипту
• chatType: direct | group | room (помогает UI и политике отправки)
• provider, subject, room, space, displayName: метаданные для маркировки групп/каналов
• Переключатели:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (переопределение на уровне сеанса)
• Выбор модели:
  • providerOverride, modelOverride, authProfileOverride
• Счётчики токенов (best-effort / зависят от провайдера):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: как часто автоуплотнение завершалось для этого ключа сеанса
• memoryFlushAt: отметка времени последнего предуплотнительного сброса памяти
• memoryFlushCompactionCount: счётчик уплотнений на момент последнего сброса

​

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

• Первая строка: заголовок сеанса (type: "session", включает id, cwd, timestamp, необязательный parentSession)
• Далее: записи сеанса с id + parentId (дерево)

• message: сообщения пользователя/ассистента/результата инструмента
• custom_message: сообщения, внедрённые расширениями, которые входят в контекст модели (могут быть скрыты из UI)
• custom: состояние расширений, которое не входит в контекст модели
• compaction: сохранённая сводка уплотнения с firstKeptEntryId и tokensBefore
• branch_summary: сохранённая сводка при навигации по ветви дерева

​

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

1. Окно контекста модели: жёсткий предел для модели (токены, видимые модели)
2. Счётчики хранилища сеансов: скользящая статистика, записываемая в sessions.json (используется для /status и дашбордов)

• Окно контекста берётся из каталога моделей (и может быть переопределено через конфиг).
• contextTokens в хранилище — это оценка/значение для отчётности во время выполнения; не воспринимайте его как строгую гарантию.

​

Уплотнение: что это такое

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

​

Когда происходит автоуплотнение (рантайм Pi)

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

• contextWindow — окно контекста модели
• reserveTokens — запас, зарезервированный под промпты + следующий вывод модели

​

Настройки уплотнения (reserveTokens, keepRecentTokens)

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

• Если compaction.reserveTokens < reserveTokensFloor, OpenClaw увеличивает значение.
• Минимум по умолчанию — 20000 токенов.
• Установите agents.defaults.compaction.reserveTokensFloor: 0, чтобы отключить минимум.
• Если значение уже выше, OpenClaw оставляет его без изменений.

​

Пользовательские поверхности

• /status (в любом чате)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• Подробный режим: 🧹 Auto-compaction complete + счётчик уплотнений

​

Тихая служебная обработка (NO_REPLY)

• Ассистент начинает свой вывод с NO_REPLY, чтобы обозначить «не доставлять ответ пользователю».
• OpenClaw удаляет/подавляет это на уровне доставки.

​

Предуплотнительный «сброс памяти» (реализовано)

1. Мониторинг использования контекста сеанса.
2. При пересечении «мягкого порога» (ниже порога уплотнения Pi) — запуск тихой директивы агенту «записать память сейчас».
3. Использование NO_REPLY, чтобы пользователь ничего не увидел.

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

• Промпт по умолчанию/системный промпт включает подсказку NO_REPLY для подавления доставки.
• Сброс выполняется один раз за цикл уплотнения (отслеживается в sessions.json).
• Сброс выполняется только для встроенных сеансов Pi (CLI-бэкенды его пропускают).
• Сброс пропускается, когда рабочее пространство сеанса доступно только для чтения (workspaceAccess: "ro" или "none").
• См. Memory для схемы файлов рабочего пространства и шаблонов записи.

​

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

• Неверный ключ сеанса? Начните с /concepts/session и подтвердите sessionKey в /status.
• Несоответствие хранилища и транскрипта? Проверьте хост шлюза Gateway и путь к хранилищу из openclaw status.
• Спам уплотнений? Проверьте:
  • окно контекста модели (слишком маленькое)
  • настройки уплотнения (reserveTokens слишком высокое относительно окна модели может вызывать более раннее уплотнение)
  • раздувание результатов инструментов: включите/настройте прореживание сеансов
• «Тихие» ходы протекают? Убедитесь, что ответ начинается с NO_REPLY (точный токен) и что вы используете сборку, включающую исправление подавления потоковой передачи.