​

세션 관리 & 컴팩션 (심층 분석)

• 세션 라우팅 (인바운드 메시지가 sessionKey 에 어떻게 매핑되는지)
• 세션 스토어 (sessions.json) 와 그 추적 대상
• 트랜스크립트 영속화 (*.jsonl) 및 구조
• 트랜스크립트 위생 (실행 전 프로바이더별 보정)
• 컨텍스트 한계 (컨텍스트 윈도우 vs 추적 토큰)
• 컴팩션 (수동 + 자동 컴팩션) 및 사전 컴팩션 작업을 연결하는 위치
• 무음 하우스키핑 (예: 사용자에게 보이는 출력이 없어야 하는 메모리 쓰기)

• /concepts/session
• /concepts/compaction
• /concepts/session-pruning
• /reference/transcript-hygiene

​

진실의 원천: Gateway(게이트웨이)

• UI (macOS 앱, 웹 Control UI, TUI) 는 세션 목록과 토큰 수를 Gateway 에 질의해야 합니다.
• 원격 모드에서는 세션 파일이 원격 호스트에 있으며, ‘로컬 Mac 파일 확인’은 Gateway 가 사용하는 내용을 반영하지 않습니다.

​

두 가지 영속화 계층

1. 세션 스토어 (sessions.json)
   • 키/값 맵: sessionKey -> SessionEntry
   • 작고 가변적이며, 편집(또는 항목 삭제)이 안전합니다.
   • 세션 메타데이터(현재 세션 id, 마지막 활동, 토글, 토큰 카운터 등)를 추적합니다.
2. 트랜스크립트 (<sessionId>.jsonl)
   • 트리 구조를 가진 append-only 트랜스크립트(항목은 id + parentId 를 가짐)
   • 실제 대화 + 도구 호출 + 컴팩션 요약을 저장합니다.
   • 향후 턴을 위한 모델 컨텍스트를 재구성하는 데 사용됩니다.

​

디스크 상 위치

• 스토어: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• 트랜스크립트: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Telegram 토픽 세션: .../<sessionId>-topic-<threadId>.jsonl

​

세션 키 (sessionKey)

• 메인/다이렉트 채팅(에이전트별): agent:<agentId>:<mainKey> (기본값 main)
• 그룹: agent:<agentId>:<channel>:group:<id>
• 룸/채널(Discord/Slack): agent:<agentId>:<channel>:channel:<id> 또는 ...:room:<id>
• 크론: cron:<job.id>
• 웹훅: hook:<uuid> (재정의되지 않는 한)

​

세션 id (sessionId)

• 리셋 (/new, /reset) 은 해당 sessionKey 에 대해 새로운 sessionId 를 생성합니다.
• 일일 리셋 (기본값 Gateway 호스트 로컬 시간 오전 4:00) 은 리셋 경계 이후 첫 메시지에서 새로운 sessionId 를 생성합니다.
• 유휴 만료 (session.reset.idleMinutes 또는 레거시 session.idleMinutes) 는 유휴 윈도우 이후 메시지가 도착하면 새로운 sessionId 를 생성합니다. 일일 + 유휴가 모두 구성된 경우 먼저 만료되는 쪽이 우선합니다.

​

세션 스토어 스키마 (sessions.json)

• sessionId: 현재 트랜스크립트 id (파일명은 sessionFile 가 설정되지 않는 한 여기에서 파생됨)
• updatedAt: 마지막 활동 타임스탬프
• sessionFile: 선택적 명시적 트랜스크립트 경로 오버라이드
• chatType: direct | group | room (UI 및 전송 정책에 도움)
• provider, subject, room, space, displayName: 그룹/채널 라벨링을 위한 메타데이터
• 토글:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (세션별 오버라이드)
• 모델 선택:
  • providerOverride, modelOverride, authProfileOverride
• 토큰 카운터(최선의 노력 / 프로바이더 의존):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: 이 세션 키에 대해 자동 컴팩션이 완료된 횟수
• memoryFlushAt: 마지막 사전 컴팩션 메모리 플러시의 타임스탬프
• memoryFlushCompactionCount: 마지막 플러시가 실행되었을 때의 컴팩션 카운트

​

트랜스크립트 구조 (*.jsonl)

• 첫 줄: 세션 헤더 (type: "session", id, cwd, timestamp, 선택적 parentSession 포함)
• 이후: id + parentId (트리) 를 가진 세션 항목

• message: 사용자/어시스턴트/toolResult 메시지
• custom_message: 모델 컨텍스트에 포함되는 확장 주입 메시지(UI 에서 숨길 수 있음)
• custom: 모델 컨텍스트에 포함되지 않는 확장 상태
• compaction: firstKeptEntryId 와 tokensBefore 를 포함한 영속화된 컴팩션 요약
• branch_summary: 트리 브랜치를 탐색할 때의 영속화된 요약

​

컨텍스트 윈도우 vs 추적 토큰

1. 모델 컨텍스트 윈도우: 모델별 하드 상한(모델에 보이는 토큰)
2. 세션 스토어 카운터: sessions.json 에 기록되는 롤링 통계(/status 및 대시보드에 사용)

• 컨텍스트 윈도우는 모델 카탈로그에서 오며(구성으로 오버라이드 가능),
• 스토어의 contextTokens 는 런타임 추정/리포팅 값이므로 엄격한 보장으로 취급하지 마십시오.

​

컴팩션: 무엇인가

• 컴팩션 요약
• firstKeptEntryId 이후의 메시지

​

자동 컴팩션이 발생하는 시점 (Pi 런타임)

1. 오버플로 복구: 모델이 컨텍스트 오버플로 오류를 반환 → 컴팩트 → 재시도.
2. 임계값 유지: 성공적인 턴 이후, 다음 조건일 때:

• contextWindow 는 모델의 컨텍스트 윈도우입니다.
• reserveTokens 는 프롬프트 + 다음 모델 출력에 예약된 여유 공간입니다.

​

컴팩션 설정 (reserveTokens, keepRecentTokens)

{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}

• compaction.reserveTokens < reserveTokensFloor 인 경우, OpenClaw 가 이를 상향합니다.
• 기본 하한은 20000 토큰입니다.
• agents.defaults.compaction.reserveTokensFloor: 0 를 설정하면 하한을 비활성화합니다.
• 이미 더 높다면 OpenClaw 는 변경하지 않습니다.

​

사용자에게 보이는 표면

• /status (어떤 채팅 세션에서도)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• 상세 모드: 🧹 Auto-compaction complete + 컴팩션 카운트

​

무음 하우스키핑 (NO_REPLY)

• 어시스턴트는 출력 시작을 NO_REPLY 로 하여 “사용자에게 답변을 전달하지 않음”을 표시합니다.
• OpenClaw 는 전달 계층에서 이를 제거/억제합니다.

​

사전 컴팩션 “메모리 플러시” (구현됨)

1. 세션 컨텍스트 사용량을 모니터링합니다.
2. “소프트 임계값”(Pi 의 컴팩션 임계값보다 낮음)을 넘으면, 에이전트에 무음 “지금 메모리 쓰기” 지시를 실행합니다.
3. NO_REPLY 를 사용하여 사용자에게 아무것도 보이지 않게 합니다.

• enabled (기본값: true)
• softThresholdTokens (기본값: 4000)
• prompt (플러시 턴을 위한 사용자 메시지)
• systemPrompt (플러시 턴에 추가되는 시스템 프롬프트)

• 기본 프롬프트/시스템 프롬프트에는 전달을 억제하기 위한 NO_REPLY 힌트가 포함됩니다.
• 플러시는 컴팩션 사이클당 한 번 실행됩니다(sessions.json 에서 추적).
• 플러시는 임베디드 Pi 세션에서만 실행됩니다(CLI 백엔드는 건너뜁니다).
• 세션 워크스페이스가 읽기 전용인 경우(workspaceAccess: "ro" 또는 "none") 플러시는 건너뜁니다.
• 워크스페이스 파일 레이아웃과 쓰기 패턴은 Memory 를 참고하십시오.

​

문제 해결 체크리스트

• 세션 키가 잘못되었습니까? /concepts/session 부터 시작하여 /status 의 sessionKey 를 확인하십시오.
• 스토어 vs 트랜스크립트 불일치입니까? Gateway 호스트와 openclaw status 에서 스토어 경로를 확인하십시오.
• 컴팩션이 과도합니까? 다음을 확인하십시오:
  • 모델 컨텍스트 윈도우(너무 작음)
  • 컴팩션 설정(모델 윈도우에 비해 reserveTokens 가 너무 높으면 더 이른 컴팩션을 유발할 수 있음)
  • tool-result 팽창: 세션 프루닝을 활성화/조정하십시오
• 무음 턴이 새고 있습니까? 응답이 NO_REPLY (정확한 토큰)로 시작하는지, 그리고 스트리밍 억제 수정이 포함된 빌드인지 확인하십시오.