세션 관리

개요

OpenClaw의 세션은 에이전트와 사용자 간의 대화 컨텍스트를 관리하는 단위이다. 메시지 출처(DM, 그룹, 크론)에 따라 세션이 구성되며, 격리 수준과 초기화 정책을 세밀하게 제어할 수 있다.

메시지 출처별 세션 구성

DM 격리 수준

DM 세션은 격리 수준에 따라 네 가지 모드를 지원한다.

main

모든 DM이 하나의 메인 세션을 공유한다.

• 가장 단순한 구성
• 모든 대화가 하나의 컨텍스트에 섞임

per-peer

대화 상대(peer)별로 세션을 분리한다.

• 사용자 A와의 대화와 사용자 B와의 대화가 분리됨
• 같은 사용자가 여러 채널에서 보내면 하나로 합쳐짐

per-channel-peer (권장)

채널 + 대화 상대 조합으로 세션을 분리한다.

• WhatsApp의 사용자 A ≠ Telegram의 사용자 A
• 가장 세밀한 격리 수준
• 권장 설정

per-account-channel-peer

계정 + 채널 + 대화 상대 조합으로 세션을 분리한다.

• 멀티 계정 운영 시 사용
• 동일 채널의 서로 다른 봇 계정별 격리

세션 초기화

세션은 다음 조건에서 초기화된다.

{
  "sessions": {
    "dailyReset": "04:00",        // 일일 리셋 시각
    "idleTimeout": "4h",          // 유휴 타임아웃
    "timezone": "Asia/Seoul"
  }
}

세션 저장소

세션 데이터는 파일 시스템에 저장된다.

~/.openclaw/agents/<agentId>/sessions/
├── main/
│   └── history.json
├── dm-whatsapp-user123/
│   └── history.json
├── group-telegram-mygroup/
│   └── history.json
└── cron-daily-report-20260401/
    └── history.json

세션 검사 명령어

현재 세션 상태 확인

openclaw status

활성 세션 목록, 메시지 수, 마지막 활동 시각 등을 확인할 수 있다.

세션 목록 JSON 출력

openclaw sessions --json

프로그래밍 방식으로 세션 데이터에 접근할 때 사용한다.

[
  {
    "id": "dm-whatsapp-user123",
    "agent": "my-agent",
    "messages": 42,
    "lastActive": "2026-04-01T08:30:00Z",
    "source": "whatsapp"
  }
]

그룹 세션

그룹 메시지는 항상 그룹 단위로 격리된다.

• 그룹 내 모든 참여자가 동일한 세션을 공유
• 에이전트가 그룹 컨텍스트를 이해하고 응답
• 그룹 나가기 시 세션 데이터 보존 (수동 삭제 필요)

크론 세션

크론 작업은 기본적으로 매 실행마다 새로운 세션을 생성한다.

• isolatedSession: true (기본값)
• 이전 실행의 컨텍스트가 다음 실행에 영향을 주지 않음
• 메인 세션에서 실행하려면 target: "main" 설정