Перейти к основному содержанию

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

OpenClaw рассматривает один сеанс прямого чата на агента как основной. Прямые чаты сворачиваются к agent:<agentId>:<mainKey> (по умолчанию main), тогда как групповые/канальные чаты получают собственные ключи. session.mainKey соблюдается. Используйте session.dmScope, чтобы управлять тем, как группируются личные сообщения (DM):
  • main (по умолчанию): все DM используют основной сеанс для непрерывности.
  • per-peer: изоляция по идентификатору отправителя между каналами.
  • per-channel-peer: изоляция по каналу + отправителю (рекомендуется для многопользовательских входящих).
  • per-account-channel-peer: изоляция по аккаунту + каналу + отправителю (рекомендуется для многоаккаунтных входящих). Используйте session.identityLinks, чтобы сопоставлять peer id с префиксом провайдера с канонической идентичностью, чтобы один и тот же человек разделял один DM-сеанс между каналами при использовании per-peer, per-channel-peer или per-account-channel-peer.

​
Режим безопасных DM (рекомендуется для многопользовательских настроек)

Предупреждение по безопасности: если ваш агент может получать DM от нескольких людей, настоятельно рекомендуется включить режим безопасных DM. Без него все пользователи разделяют один и тот же контекст разговора, что может привести к утечке приватной информации между пользователями.
Пример проблемы с настройками по умолчанию:
  • Алиса (<SENDER_A>) пишет вашему агенту о приватной теме (например, о медицинском приёме)
  • Боб (<SENDER_B>) пишет вашему агенту, спрашивая: «О чём мы говорили?»
  • Поскольку оба DM используют один и тот же сеанс, модель может ответить Бобу, используя предыдущий контекст Алисы.
Исправление: установите dmScope, чтобы изолировать сеансы по пользователям: 
// ~/.openclaw/openclaw.json
{
  session: {
    // Secure DM mode: isolate DM context per channel + sender.
    dmScope: "per-channel-peer",
  },
}
Когда стоит включить:
  • У вас есть подтверждения сопряжения для более чем одного отправителя
  • Вы используете allowlist DM с несколькими записями
  • Вы установили dmPolicy: "open"
  • Несколько телефонных номеров или аккаунтов могут писать вашему агенту
Примечания:
  • По умолчанию используется dmScope: "main" для непрерывности (все DM используют основной сеанс). Это подходит для однопользовательских настроек.
  • Для многоаккаунтных входящих в одном и том же канале предпочтительнее per-account-channel-peer.
  • Если один и тот же человек связывается с вами через несколько каналов, используйте session.identityLinks, чтобы свернуть его DM-сеансы в одну каноническую идентичность.
  • Вы можете проверить настройки DM с помощью openclaw security audit (см. security).

​
Gateway — источник истины

Всё состояние сеансов принадлежит Gateway (шлюзу) ( «master» OpenClaw). Клиенты UI (приложение для macOS, WebChat и т. п.) должны запрашивать у шлюза списки сеансов и счётчики токенов, а не читать локальные файлы.
  • В удалённом режиме хранилище сеансов, которое вас интересует, находится на удалённом хосте шлюза Gateway, а не на вашем Mac.
  • Счётчики токенов, отображаемые в UI, берутся из полей хранилища шлюза (inputTokens, outputTokens, totalTokens, contextTokens). Клиенты не парсят JSONL‑транскрипты, чтобы «исправлять» итоги.

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

  • На хосте шлюза Gateway:
    • Файл хранилища: ~/.openclaw/agents/<agentId>/sessions/sessions.json (на агента).
  • Транскрипты: ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl (сеансы тем Telegram используют .../<SessionId>-topic-<threadId>.jsonl).
  • Хранилище — это отображение sessionKey -> { sessionId, updatedAt, ... }. Удаление записей безопасно; они пересоздаются по требованию.
  • Групповые записи могут включать displayName, channel, subject, room и space для маркировки сеансов в UI.
  • Записи сеансов включают метаданные origin (метка + подсказки маршрутизации), чтобы UI мог объяснять происхождение сеанса.
  • OpenClaw не читает устаревшие папки сеансов Pi/Tau.

​
Обрезка сеансов

По умолчанию OpenClaw обрезает старые результаты инструментов из контекста в памяти непосредственно перед вызовами LLM. Это не переписывает историю JSONL. См. /concepts/session-pruning.

​
Предварительный сброс памяти перед уплотнением

Когда сеанс приближается к автоуплотнению, OpenClaw может выполнить тихий сброс памяти — ход, который напоминает модели записать устойчивые заметки на диск. Это выполняется только когда рабочее пространство доступно для записи. Memory и Compaction.

​
Сопоставление транспортов → ключи сеансов

  • Прямые чаты следуют session.dmScope (по умолчанию main).
    • main: agent:<agentId>:<mainKey> (непрерывность между устройствами/каналами).
      • Несколько телефонных номеров и каналов могут сопоставляться с одним основным ключом агента; они действуют как транспорты в один разговор.
    • per-peer: agent:<agentId>:dm:<peerId>.
    • per-channel-peer: agent:<agentId>:<channel>:dm:<peerId>.
    • per-account-channel-peer: agent:<agentId>:<channel>:<accountId>:dm:<peerId> (accountId по умолчанию — default).
    • Если session.identityLinks совпадает с peer id с префиксом провайдера (например, telegram:123), канонический ключ заменяет <peerId>, чтобы один и тот же человек разделял сеанс между каналами.
  • Групповые чаты изолируют состояние: agent:<agentId>:<channel>:group:<id> (комнаты/каналы используют agent:<agentId>:<channel>:channel:<id>).
    • Темы форумов Telegram добавляют :topic:<threadId> к идентификатору группы для изоляции.
    • Устаревшие ключи group:<id> всё ещё распознаются для миграции.
  • Входящие контексты всё ещё могут использовать group:<id>; канал выводится из Provider и нормализуется к канонической форме agent:<agentId>:<channel>:group:<id>.
  • Другие источники:
    • Cron‑задачи: cron:<job.id>
    • Webhooks: hook:<uuid> (если явно не задано хуком)
    • Запуски узлов: node-<nodeId>

​
Жизненный цикл

  • Политика сброса: сеансы переиспользуются до истечения срока, а истечение оценивается при следующем входящем сообщении.
  • Ежедневный сброс: по умолчанию 4:00 по местному времени на хосте шлюза Gateway. Сеанс считается устаревшим, если его последнее обновление раньше времени последнего ежедневного сброса.
  • Сброс по бездействию (необязательно): idleMinutes добавляет скользящее окно простоя. Когда настроены и ежедневный, и простой‑сброс, что истечёт раньше, то и принудит новый сеанс.
  • Устаревший режим «только простой»: если вы установили session.idleMinutes без какой‑либо конфигурации session.reset/resetByType, OpenClaw остаётся в режиме только по простоям для обратной совместимости.
  • Переопределения по типам (необязательно): resetByType позволяет переопределять политику для сессий direct, group и thread (thread = треды Slack/Discord, темы Telegram, треды Matrix, когда они предоставляются коннектором).
  • Переопределения по каналам (необязательно): resetByChannel переопределяет политику сброса для канала (применяется ко всем типам сеансов этого канала и имеет приоритет над reset/resetByType).
  • Триггеры сброса: точные /new или /reset (плюс любые дополнительные в resetTriggers) запускают новый идентификатор сеанса и пропускают остаток сообщения дальше. /new <model> принимает алиас модели, provider/model или имя провайдера (нечёткое совпадение), чтобы задать модель нового сеанса. Если /new или /reset отправлены отдельно, OpenClaw выполняет короткий приветственный ход «hello» для подтверждения сброса.
  • Ручной сброс: удалите конкретные ключи из хранилища или удалите JSONL‑транскрипт; следующее сообщение пересоздаст их.
  • Изолированные cron‑задачи всегда создают новый sessionId на каждый запуск (без повторного использования по простою).

​
Политика отправки (необязательно)

Блокируйте доставку для конкретных типов сеансов без перечисления отдельных идентификаторов. 
{
  session: {
    sendPolicy: {
      rules: [
        { action: "deny", match: { channel: "discord", chatType: "group" } },
        { action: "deny", match: { keyPrefix: "cron:" } },
      ],
      default: "allow",
    },
  },
}
Переопределение во время выполнения (только владелец):
  • /send on → разрешить для этого сеанса
  • /send off → запретить для этого сеанса
  • /send inherit → очистить переопределение и использовать правила конфига Отправляйте их как отдельные сообщения, чтобы они зарегистрировались.

​
Конфигурация (пример необязательного переименования)

// ~/.openclaw/openclaw.json
{
  session: {
    scope: "per-sender", // keep group keys separate
    dmScope: "main", // DM continuity (set per-channel-peer/per-account-channel-peer for shared inboxes)
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      // Defaults: mode=daily, atHour=4 (gateway host local time).
      // If you also set idleMinutes, whichever expires first wins.
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    mainKey: "main",
  },
}

​
Инспектирование

  • openclaw status — показывает путь к хранилищу и недавние сеансы.
  • openclaw sessions --json — выгружает каждую запись (фильтрация с помощью --active <minutes>).
  • openclaw gateway call sessions.list --params '{}' — получает сеансы из работающего шлюза (используйте --url/--token для доступа к удалённому шлюзу).
  • Отправьте /status как отдельное сообщение в чате, чтобы увидеть, доступен ли агент, какая часть контекста сеанса используется, текущие переключатели thinking/verbose и когда в последний раз обновлялись ваши учётные данные WhatsApp Web (помогает выявлять необходимость перепривязки).
  • Отправьте /context list или /context detail, чтобы увидеть содержимое системного промпта и внедрённых файлов рабочего пространства (и крупнейших вкладчиков в контекст).
  • Отправьте /stop как отдельное сообщение, чтобы прервать текущий запуск, очистить очередь последующих действий для этого сеанса и остановить любые запуски субагентов, порождённые им (ответ включает количество остановленных).
  • Отправьте /compact (необязательные инструкции) как отдельное сообщение, чтобы суммировать более старый контекст и освободить место в окне. См. /concepts/compaction.
  • JSONL‑транскрипты можно открыть напрямую для просмотра полных ходов.

​
Советы

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

​
Метаданные происхождения сеанса

Каждая запись сеанса фиксирует, откуда она пришла (best‑effort), в origin:
  • label: человекочитаемая метка (разрешается из метки разговора + темы группы/канала)
  • provider: нормализованный идентификатор канала (включая расширения)
  • from/to: сырые идентификаторы маршрутизации из входящего конверта
  • accountId: идентификатор аккаунта провайдера (при многоаккаунтности)
  • threadId: идентификатор треда/темы, когда канал это поддерживает Поля происхождения заполняются для личных сообщений, каналов и групп. Если коннектор обновляет только маршрутизацию доставки (например, чтобы поддерживать актуальность основного DM‑сеанса), он всё равно должен предоставлять входящий контекст, чтобы сеанс сохранял свои поясняющие метаданные. Расширения могут сделать это, отправив ConversationLabel, GroupSubject, GroupChannel, GroupSpace и SenderName во входящем контексте и вызвав recordSessionMetaFromInbound (или передав тот же контекст в updateLastRoute).