Сессии и агенты в OpenClaw: маршрутизация на русском

Когда AI-агент общается с несколькими людьми через разные мессенджеры — как он решает, какой контекст показывать какому пользователю? Как разделить рабочие и личные чаты? Как обеспечить, чтобы один пользователь не видел переписку другого? Всё это решает система сессий OpenClaw.

Эта статья — адаптированный перевод документации по Session Management. Если вы только начинаете — рекомендуем сначала прочитать что такое OpenClaw и руководство по быстрому старту.

Что такое сессия в OpenClaw

Сессия — это контейнер для разговора. Она хранит историю сообщений, контекст и состояние. У каждой сессии есть уникальный ключ, который определяет, откуда пришло сообщение и кому оно принадлежит.

OpenClaw автоматически маршрутизирует входящие сообщения в нужную сессию на основе:

• Канала (Telegram, WhatsApp, Discord...)
• Типа чата (личное сообщение или группа)
• ID отправителя
• Настроек dmScope

Режимы группировки личных сообщений (dmScope)

Параметр session.dmScope — ключевая настройка, определяющая, как организованы личные чаты:

main (по умолчанию)

Все личные сообщения со всех каналов попадают в одну общую сессию. Это удобно для одного пользователя — вы можете начать разговор в Telegram, продолжить в WhatsApp, и агент сохранит контекст.

per-peer

Изоляция по отправителю. Каждый человек получает свою сессию, но один и тот же человек из разных каналов — в одной.

per-channel-peer (рекомендуется для нескольких пользователей)

Изоляция по каналу и отправителю. Самый безопасный вариант для ботов, доступных нескольким людям.

per-account-channel-peer

Максимальная изоляция — если у вас несколько аккаунтов на одном канале.

Пример проблемы без изоляции

Алиса пишет агенту о медицинском приёме. Борис спрашивает агента: «О чём мы говорили?» Без изоляции модель может ответить Борису, используя контекст Алисы. Чтобы этого не произошло:

{
  session: {
    dmScope: "per-channel-peer",
  },
}

Маршрутизация: как формируются ключи сессий

Каждая сессия имеет ключ, построенный по формуле:

• ЛС (main): agent:main:main — все ЛС в одной сессии
• ЛС (per-channel-peer): agent:main:telegram:dm:123456 — изоляция по каналу и отправителю
• Группа: agent:main:telegram:group:-1001234567 — каждая группа отдельно
• Telegram-форум: agent:main:telegram:group:-1001234567:topic:42 — каждый топик отдельно
• Cron-задача: cron:job-123 — изолированная сессия
• Вебхук: hook:uuid — изолированная сессия

Связывание идентичностей (identityLinks)

Если один и тот же человек пишет вам из Telegram и Discord, можно объединить его сессии:

{
  session: {
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321"],
    },
  },
}

Теперь Алиса получит один общий контекст, независимо от канала.

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

Сброс сессий

Сессии автоматически сбрасываются по политике:

• Ежедневный сброс — по умолчанию в 4:00 утра по локальному времени Gateway
• Сброс по бездействию — через idleMinutes (опционально)
• Если настроены оба — срабатывает тот, что наступит раньше

{
  session: {
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

Ручной сброс

Отправьте /new или /reset в чате, чтобы начать новую сессию. Можно указать модель: /new opus.

Настройки по типу чата

{
  session: {
    resetByType: {
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
      thread: { mode: "daily", atHour: 4 },
    },
  },
}

Политика отправки (Send Policy)

Можно заблокировать отправку ответов для определённых сессий без указания конкретных ID:

{
  session: {
    sendPolicy: {
      rules: [
        { action: "deny", match: { channel: "discord", chatType: "group" } },
        { action: "deny", match: { keyPrefix: "cron:" } },
      ],
      default: "allow",
    },
  },
}

Управление на лету: /send on, /send off, /send inherit.

Где хранятся данные сессий

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

Gateway — единственный источник истины для сессий. UI-клиенты (macOS, WebChat) запрашивают данные у Gateway, а не читают файлы напрямую.

Полезные команды для отладки

• openclaw status — показать путь к хранилищу и недавние сессии
• openclaw sessions --json — вывести все сессии
• /status (в чате) — информация о текущей сессии
• /context list (в чате) — что содержится в системном промпте
• /compact (в чате) — сжать контекст для освобождения окна
• /stop (в чате) — остановить текущий запуск