Управление сеансами

OpenClaw направляет каждое входящее сообщение в сеанс в зависимости от его источника: личные сообщения, групповые чаты, задания Cron и т. д. Всем состоянием сеансов управляет Gateway; клиенты пользовательского интерфейса запрашивают данные сеансов у Gateway.

Как маршрутизируются сообщения

Изоляция личных сообщений

По умолчанию все личные сообщения используют один общий сеанс для сохранения непрерывности диалога, что подходит для конфигураций с одним пользователем.

{  session: {    dmScope: "per-channel-peer", // isolate by channel + sender  },}

Варианты session.dmScope:

Закрепление связанных каналов

Команды закрепления переносят маршрут ответа текущего сеанса личного чата в другой связанный канал, не создавая новый сеанс. Примеры, конфигурацию и сведения об устранении неполадок см. в разделе Закрепление каналов.

Проверьте свою конфигурацию с помощью openclaw security audit.

Жизненный цикл сеанса

Сеансы используются повторно до истечения срока их действия согласно session.reset:

• Ежедневный сброс (по умолчанию mode: "daily") — новый сеанс в заданный локальный час (session.reset.atHour, по умолчанию 4, 0-23) на хосте Gateway. Срок ежедневного обновления отсчитывается с момента запуска текущего sessionId, а не с последующих записей метаданных.
• Сброс при простое (mode: "idle") — новый сеанс после session.reset.idleMinutes бездействия. Срок простоя отсчитывается с момента последнего реального взаимодействия с пользователем или каналом, поэтому системные события Heartbeat, Cron и exec не поддерживают сеанс активным.
• Ручной сброс — введите /new или /reset в чате. /new <model> также переключает модель.

Если настроены и ежедневный сброс, и сброс при простое, применяется тот, срок которого истечёт первым. Ходы Heartbeat, Cron, exec и других системных событий могут записывать метаданные сеанса, но эти записи не продлевают срок ежедневного сброса или сброса при простое. Когда при сбросе создаётся новый сеанс, уведомления о системных событиях из очереди для старого сеанса отбрасываются, чтобы устаревшие фоновые обновления не добавлялись в начало первого запроса нового сеанса.

Сеансы с активным CLI-сеансом, принадлежащим провайдеру, не прерываются неявным ежедневным сбросом по умолчанию. Используйте /reset или явно настройте session.reset, если срок действия таких сеансов должен истекать по таймеру.

Переопределите значение по умолчанию для каждого типа чата или канала:

{  session: {    reset: { mode: "daily", atHour: 4 },    resetByType: {      group: { mode: "idle", idleMinutes: 120 },      thread: { mode: "daily", atHour: 6 },    },    resetByChannel: {      discord: { mode: "idle", idleMinutes: 10080 },    },  },}

resetByType поддерживает direct (устаревший псевдоним dm), group и thread. Устаревший параметр верхнего уровня session.idleMinutes по-прежнему работает как псевдоним совместимости для режима простоя по умолчанию, если блок session.reset/resetByType не задан.

Где хранится состояние

• Строки сеансов среды выполнения: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• Архивные файлы расшифровок: ~/.openclaw/agents/<agentId>/sessions/
• Источник миграции устаревших строк: ~/.openclaw/agents/<agentId>/sessions/sessions.json

Строки сеансов в базе данных SQLite каждого агента содержат отдельные временные метки жизненного цикла:

• sessionStartedAt: момент начала текущего sessionId; используется для ежедневного сброса.
• lastInteractionAt: последнее взаимодействие пользователя или канала, продлевающее срок простоя.
• updatedAt: последнее изменение строки хранилища; полезно для вывода списка и очистки, но не является определяющим для срока ежедневного сброса или сброса при простое.

Во время миграции со старых установок запуск Gateway и openclaw doctor --fix автоматически импортируют устаревшие строки sessions.json и актуальную историю расшифровок JSONL в SQLite. Значения строк без sessionStartedAt извлекаются из заголовка сеанса устаревшей расшифровки JSONL, если он доступен. Если в старой строке также отсутствует lastInteractionAt, срок простоя отсчитывается от времени начала этого сеанса, а не от последующих служебных записей. Используйте openclaw doctor --session-sqlite inspect --session-sqlite-all-agents и последовательность миграции Doctor, если требуется явная проверка или подтверждение миграции.

Обслуживание сеансов

OpenClaw со временем ограничивает размер хранилища сеансов с помощью session.maintenance; ниже показаны значения по умолчанию:

{  session: {    maintenance: {      mode: "enforce", // "enforce" applies cleanup; "warn" only reports      pruneAfter: "30d",      maxEntries: 500,    },  },}

При значениях ограничения maxEntries, характерных для рабочей среды, операции записи Gateway используют небольшой буфер верхнего порога и пакетно сокращают объём до настроенного предела. Операции чтения хранилища сеансов не очищают и не ограничивают записи во время запуска Gateway, поэтому запуск и изолированные сеансы Cron не требуют полной очистки хранилища. openclaw sessions cleanup --enforce применяет ограничение немедленно.

Сеансы проверки запуска модели Gateway по умолчанию кратковременны. Для строк, соответствующих agent:*:explicit:model-run-<uuid>, используется фиксированный срок хранения 24h, но очистка выполняется только при достижении порога: устаревшие строки проверок удаляются лишь при возникновении нагрузки на обслуживание или ограничение количества записей сеансов, причём это происходит до применения общего возрастного порога устаревших записей и ограничения количества записей. Обычные личные, групповые, потоковые сеансы, а также сеансы Cron, Webhook, Heartbeat, ACP и субагентов не наследуют этот срок хранения 24h.

При обслуживании сохраняются постоянные внешние указатели на диалоги, включая групповые сеансы и ограниченные потоком сеансы чатов, тогда как синтетические записи Cron, Webhook, Heartbeat, ACP и субагентов могут устаревать и удаляться.

Если ранее вы использовали изоляцию личных сообщений, а затем вернули session.dmScope к main, предварительно просмотрите устаревшие строки личных сообщений с ключами собеседников с помощью openclaw sessions cleanup --dry-run --fix-dm-scope. Применение того же флага выводит эти старые строки личных сообщений из использования и сохраняет их расшифровки как удалённые архивы.

Предварительно просмотреть любой запуск обслуживания можно с помощью openclaw sessions cleanup --dry-run.

Просмотр сеансов

Дополнительные материалы

• Поиск по сеансам — полнотекстовый поиск по прошлым расшифровкам
• Очистка сеансов — сокращение результатов инструментов
• Compaction — краткое изложение длинных диалогов
• Инструменты сеансов — инструменты агента для работы между сеансами
• Подробное руководство по управлению сеансами — схема хранилища, расшифровки, политика отправки, метаданные источника и расширенная конфигурация
• Несколько агентов — маршрутизация и изоляция сеансов между агентами
• Фоновые задачи — как автономная работа создаёт записи задач со ссылками на сеансы
• Маршрутизация каналов — как входящие сообщения направляются в сеансы

Связанные материалы

• Очистка сеансов
• Инструменты сеансов
• Очередь команд