OpenClaw 세션 관리 및 영속성

소개

멀티 채널, 멀티 사용자 AI 게이트웨이 시나리오에서 세션 관리는 가장 중요한 기반 기능 중 하나입니다. OpenClaw은 JSONL 기반의 영속성 방식과 트리 구조 메시지 모델을 결합하여 세션 분기, 이력 역추적, 자동 압축 등 고급 기능을 구현합니다. 본 문서에서는 OpenClaw의 세션 관리 메커니즘을 저수준 저장소부터 고수준 전략까지 포괄적으로 분석합니다.

세션 저장 위치

각 Agent의 세션 데이터는 자체 디렉토리에 독립적으로 저장됩니다:

~/.openclaw/agents/<agentId>/sessions/
├── telegram_123456.jsonl
├── discord_789012.jsonl
├── whatsapp_345678.jsonl
└── web_dashboard.jsonl

파일명 형식은 <channel>_<userId>.jsonl이며, 각 파일은 특정 채널에서 사용자의 전체 대화 이력에 해당합니다. 이 설계는 서로 다른 채널과 사용자 간의 세션을 자연스럽게 격리하여 데이터 교차 오염을 방지합니다.

JSONL 저장 형식

OpenClaw은 JSONL(JSON Lines) 형식을 사용하여 각 메시지를 저장하며, 한 줄에 하나의 JSON 객체가 포함됩니다:

{"id":"msg_001","parentId":null,"role":"user","content":"안녕하세요","timestamp":1710000000,"channel":"telegram"}
{"id":"msg_002","parentId":"msg_001","role":"assistant","content":"안녕하세요! 무엇을 도와드릴까요?","timestamp":1710000001,"channel":"telegram"}
{"id":"msg_003","parentId":"msg_002","role":"user","content":"영어 문단 번역을 도와주세요","timestamp":1710000010,"channel":"telegram"}

핵심 필드 설명

필드	유형	설명
`id`	string	고유 메시지 식별자, 자동 생성
`parentId`	string/null	부모 메시지 ID, 루트 메시지의 경우 null
`role`	string	역할: `user`, `assistant`, `system`
`content`	string	메시지 텍스트 내용
`timestamp`	number	Unix 타임스탬프
`channel`	string	소스 채널
`metadata`	object	선택 사항, 추가 메타데이터 (예: 미디어 정보)

데이터베이스 대신 JSONL을 선택한 주요 장점은 다음과 같습니다: 추가 전용 쓰기로 우수한 성능 제공, 외부 의존성 불필요, 백업 및 마이그레이션 용이, 디버깅을 위한 사람이 읽을 수 있는 형식.

트리 구조 세션

OpenClaw의 세션 관리에서 가장 독특한 설계는 트리 구조입니다. id와 parentId 필드를 통해 메시지는 단순한 선형 목록이 아닌 부모-자식 관계를 형성합니다.

트리 구조를 사용하는 이유

실제로 사용자는 종종 "특정 지점으로 돌아가서 대화를 다시 시작"해야 합니다. 예를 들어:

msg_001: 이메일 작성을 도와줘
  ├── msg_002: [어시스턴트가 공식적인 이메일 작성]
  │     └── msg_003: 더 짧게 만들어줘 → msg_004: [어시스턴트가 수정]
  └── msg_005: 캐주얼한 톤으로 작성해줘 → msg_006: [어시스턴트가 캐주얼 버전 작성]

사용자가 msg_001에서 분기하여 msg_005를 만들면, OpenClaw은 msg_001을 새 분기 시작점으로 사용하고 독립적인 컨텍스트 경로를 구축합니다. 모델은 대화 이력을 msg_001 → msg_005로 보며, msg_002나 msg_003의 내용은 혼합되지 않습니다.

대시보드에서 분기 사용

웹 대시보드에서 세션의 트리 구조를 시각적으로 확인할 수 있습니다. 과거 메시지의 "여기서 분기" 버튼을 클릭하면 새 대화 분기가 생성됩니다. 각 분기는 독립적으로 컨텍스트를 유지하며 서로 간섭하지 않습니다.

컨텍스트 구축 전략

OpenClaw이 모델 API를 호출해야 할 때, 현재 메시지 노드에서 parentId 체인을 역추적하며 조상 메시지를 컨텍스트로 수집합니다. 이 프로세스는 다음 설정으로 제어됩니다:

{
  "sessions": {
    "maxHistoryMessages": 50,
    "maxHistoryTokens": 8000
  }
}

역추적 프로세스는 다음 조건 중 하나가 충족되면 중지됩니다:

maxHistoryMessages 메시지 한도에 도달
누적 토큰 수가 maxHistoryTokens를 초과
트리의 루트 노드에 도달

자동 압축

대화가 너무 길어져 모델의 컨텍스트 윈도우 한도에 근접하면, OpenClaw이 자동으로 압축을 트리거합니다. 압축 전략은 설정으로 제어됩니다:

{
  "sessions": {
    "autoCompaction": true,
    "compactionStrategy": "summary"
  }
}

요약 전략 (기본값)

OpenClaw은 이전 대화 이력을 모델에 보내 요약을 요청합니다. 이 요약은 컨텍스트의 시작 부분에 system 역할 메시지로 삽입되어 원래의 이력 메시지를 대체합니다. 이를 통해 핵심 정보를 보존하면서 토큰 소비를 크게 줄입니다.

요약 메시지 형식은 다음과 같습니다:

{"id":"compact_001","parentId":null,"role":"system","content":"[세션 요약] 사용자는 이전에 Python 비동기 프로그래밍에 대해 질문했으며, 기본적인 asyncio 사용법과 일반적인 함정에 대해 논의했습니다...","timestamp":1710001000,"metadata":{"type":"compaction","originalCount":35}}

잘라내기 전략

가장 오래된 메시지를 직접 폐기하고 가장 최근의 N개 메시지만 유지하는 단순한 잘라내기입니다. 이 전략은 추가적인 모델 호출을 생성하지 않지만 중요한 컨텍스트를 잃을 수 있습니다. 비용에 민감하고 대화 연속성이 덜 중요한 시나리오에 적합합니다.

채널별 설정

채널마다 사용 패턴이 매우 다릅니다 — DM은 일반적으로 긴 대화이고, 그룹 채팅은 단편적인 짧은 상호작용 경향이 있습니다. OpenClaw은 채널 유형별로 세션 설정을 재정의하는 것을 지원합니다:

{
  "sessions": {
    "maxHistoryMessages": 50,
    "channelOverrides": {
      "dm": {
        "maxHistoryMessages": 100,
        "maxHistoryTokens": 16000
      },
      "group": {
        "maxHistoryMessages": 20,
        "maxHistoryTokens": 4000
      }
    }
  }
}

위 설정에서 DM은 일관된 대화를 유지하기 위해 더 긴 이력을 보존하고, 그룹 채팅은 비용을 줄이고 관련 없는 메시지 노이즈를 최소화하기 위해 제한됩니다.

세션 데이터 유지보수

수동 정리

# 특정 사용자의 세션 삭제
openclaw session clear --agent default --session telegram_123456

# Agent의 모든 세션 삭제
openclaw session clear --agent myagent --all

# 세션을 JSON으로 내보내기 (분석용)
openclaw session export --session telegram_123456 --format json > history.json

자동 정리

세션 파일에 대한 자동 정리 정책을 설정할 수 있습니다:

{
  "sessions": {
    "retention": {
      "maxAge": "30d",
      "maxSize": "100mb"
    }
  }
}

30일이 지난 세션 데이터나 총 크기가 100MB를 초과하는 데이터는 OpenClaw 시작 시 자동으로 아카이브됩니다.

다중 디바이스 동기화

세션 데이터가 파일 시스템에 저장되므로 다중 인스턴스 배포에서는 동기화를 고려해야 합니다. 권장 방식:

단일 머신 배포: 추가 설정 불필요; 파일이 자연스럽게 일관성 유지
다중 머신 배포: 공유 스토리지(예: NFS)를 사용하여 ~/.openclaw/agents/ 디렉토리를 마운트하거나, Redis 스토리지 백엔드로 전환

요약

OpenClaw의 세션 관리 시스템은 JSONL 파일 위에 구축되며, id/parentId를 사용하여 세션 분기와 유연한 컨텍스트 역추적을 지원하는 트리 구조를 구성합니다. 자동 압축 메커니즘은 긴 대화가 모델 한도를 초과하지 않도록 보장하고, 채널별 설정은 리소스 할당을 더 효율적으로 만듭니다. 이러한 메커니즘을 이해하면 특정 사용 사례에 맞게 세션 매개변수를 세밀하게 조정하여 대화 품질과 비용 사이의 적절한 균형을 찾을 수 있습니다.