Compaction UI v2.1.0
OpenClaw 제어 UI를 위한 메모리 압축 시스템 — 백그라운드 실행 및 토스트 알림, 구성 가능한 토큰 임계값 기반 자동 트리거, 압축 출력 내 대화 요약 문단, 전용 설정 탭(모델 선택기 포함), 결과 기록 저장.
상태: ✅ 활성
| 구성 요소 | 상태 |
|---|---|
| 컨텍스트 게이지 버튼 | ✅ 작동 중 |
| 백그라운드 압축 (토스트) | ✅ 작동 중 |
| 자동 압축 트리거 | ✅ 작동 중 |
| 대화 요약 문단 | ✅ 작동 중 |
| 설정 탭 (플러그인 등록) | ✅ 작동 중 |
| 모델 선택기 | ✅ 작동 중 |
| 마지막 결과 저장 및 뷰어 | ✅ 작동 중 |
| 설정 지속성 및 다시 불러오기 | ✅ 작동 중 |
| 인증 계층 (OAuth > API > 폴백) | ✅ 작동 중 |
| 채팅 기록 필터 | ✅ 작동 중 |
| 완전한 백그라운드 격리 (채팅 간섭 없음) | ✅ 작동 중 |
기능
1. 컨텍스트 게이지 버튼 (app-render.helpers.ts)
채팅 툴바에 위치한 원형 SVG 프로그레스 링으로, 수동 압축 트리거 역할도 합니다.
- 위치:
renderChatControls()내 세션 선택기 드롭다운 다음 - 데이터 소스:
sessionsResult.sessions[].totalTokens및 세션 행의contextTokens - 색상: 녹색 (<60%), 노란색 (60-85%), 빨간색 (≥85%)
- 비활성화: 사용률이 20% 미만이거나 압축이 진행 중일 때
- 툴팁: "컨텍스트: XK / YK 토큰 (Z%)" 표시
2. 백그라운드 압축 (토스트)
클릭(또는 자동 트리거) 시 압축이 표준 오른쪽 하단 토스트 시스템을 사용하여 백그라운드에서 실행됩니다. 차단 모달이 없습니다. UI는 완전히 상호작용 가능한 상태를 유지합니다.
- 실행 중 토스트: 스피너와 함께 "메모리 압축 중" 표시
- 완료 토스트: 체크 표시와 함께 "압축 완료: XK → YK" 표시 (5초 후 자동 종료)
- 오류 토스트: 실패 메시지 표시 (5초 후 자동 종료)
- 모든 백그라운드 프로세스(cron, 지식 추출 등)와 동일한
backgroundJobToasts시스템 사용
3. 자동 압축
매 채팅 응답(final 이벤트) 후, UI는 설정된 임계값과 토큰 사용량을 비교합니다. 초과 시:
- 백그라운드 압축이 자동으로 트리거됩니다.
- 현재 사용률과 함께 "자동 압축 중 (X%)" 토스트가 표시됩니다.
- 5분 디바운스로 반복 트리거를 방지합니다.
- 압축 성공 후 채팅이 자동으로 새로고침됩니다.
- 압축할 내용이 없으면 토스트가 자동으로 제거됩니다.
4. 대화 요약 문단
모든 압축 출력은 이제 구조화된 ## Goal 섹션 앞에 ## Conversation Summary 섹션으로 시작합니다. 이는 3-6문장의 자연어 문단으로, 다음을 포함합니다:
- 대화의 전반적인 주제 설명
- 논의 흐름 및 주요 전환점 설명
- 대화가 어떻게 진행되었는지 요약
- 과거 시제의 서사적 개요로 작성
구현: compact.ts에서 상류 압축 LLM 호출에 사용자 정의 지침이 주입됩니다. 이 지침은 사용자가 제공한 사용자 정의 지침(/compact [지침]) 앞에 추가되어 둘이 공존합니다.
출력 예시:
## Conversation Summary
대화는 사용자가 압축 시스템의 개선 사항(특히 차단 모달에서 백그라운드 토스트로의 전환)을 요청하면서 시작되었습니다. 이후 논의는 자동 압축 컨트롤이 포함된 설정 탭 추가로 이어졌습니다. 이러한 기능을 구현하고 테스트한 후, 사용자는 탭 탐색 간에 설정이 유지되지 않는 문제를 발견했고, 이는 모듈 수준 상태 캐시 수정으로 이어졌습니다. 마지막으로, 사용자는 더 나은 맥락을 위해 압축 출력에 서사적 요약 문단을 추가할 것을 요청했습니다.
## Goal
...
5. 설정 탭 (플러그인 등록)
Agent 탐색 그룹 아래 전용 Compaction 탭으로, 플러그인 UI 아키텍처를 통해 등록됩니다.
등록: plugins-ui.ts → BUILTIN_UI_VIEWS에 id: "compaction", group: "agent", position: 7, icon: "archive"로 등록
카드:
자동 압축 카드
- 토글: 자동 압축 활성화/비활성화
- 임계값 슬라이더: 10% ~ 95% (기본값: 60%)
- 색상 코드: 녹색 (<60%), 노란색 (60-85%), 빨간색 (≥85%)
모델 카드
- 드롭다운: 압축에 사용할 특정 모델 선택 또는 세션 기본값 사용
- 프로바이더별 그룹화 및 컨텍스트 창 크기 표시
- 경고 콜아웃 사용자 지정 모델 선택 시 (API 키 알림)
- 폴백: 사용자 지정 모델이 실패하면 자동으로 세션 기본값으로 폴백
결과 저장 카드
- 토글: 압축된 요약 텍스트를 검토용으로 저장하는 기능 선택
마지막 압축 카드
- Before/After: 2열 그리드의 큰 스타일 토큰 개수
- 통계: 저장된 토큰, 감소율, 트리거 유형, 타임스탬프, 세션 키
- 결과 보기: 접을 수 있는 요약 뷰어 (저장이 활성화된 경우)
- 지우기: 저장된 결과 초기화
- 힌트: 저장이 꺼져 있을 때 "결과 저장 활성화" 메시지 표시
상태 관리:
- 모듈 수준 상태는 세션 내에서 재렌더링 간에 유지됩니다.
- 탭을 방문할 때마다 설정을 백엔드에서 다시 불러옵니다 (2초 지연 임계값).
resetCompactionSettingsState()는 테스트 및 탭 전환을 위해 내보내집니다.
6. 인증 계층
압축은 getApiKeyForModel을 통해 resolveApiKeyForProvider를 사용합니다. 이는 채팅과 동일한 인증 체인입니다:
OAuth → API 키 → 폴백
별도의 설정이 필요하지 않습니다. OAuth(Claude Max)가 기본 인증 프로필로 구성된 경우 압축이 자동으로 사용합니다. 사용자 지정 모델 선택도 이 동일한 인증 체인을 독립적으로 사용합니다.
7. 결과 저장
활성화되면 가장 최근 압축 결과가 {agentDir}/compaction-config.json에 저장됩니다:
{
"settings": {
"autoEnabled": true,
"autoThresholdPercent": 60,
"storeLastResult": true,
"compactionModel": "anthropic/claude-sonnet-4-6"
},
"lastResult": {
"timestamp": 1709283600000,
"trigger": "manual",
"tokensBefore": 50614,
"tokensAfter": 4766,
"tokensSaved": 45848,
"percentReduction": 91,
"sessionKey": "agent:main:main",
"summary": "## Conversation Summary\n대화는 ...에 초점을 맞췄습니다.\n\n## Goal\n..."
}
}
저장이 비활성화된 경우 메타데이터(타임스탬프, 토큰 개수)는 계속 저장되지만 요약 텍스트는 생략됩니다.
8. 채팅 기록 필터
- NO_REPLY/HEARTBEAT_OK 필터링: 정확히 이 텍스트를 포함하는 어시스턴트 메시지를 건너뜁니다.
- 압축 구분선:
__openclaw.kind === "compaction"메시지에 대해 레이블이 지정된 구분선을 렌더링합니다.
아키텍처
백엔드 RPC
| 메서드 | 설명 |
|---|---|
sessions.compact | 압축 실행 (완료 후 결과 기록) |
compaction.getSettings | 설정 파일에서 설정 읽기 |
compaction.saveSettings | 설정 업데이트 (임계값 자동 클램프 10-95%) |
compaction.getLastResult | 저장된 마지막 압축 결과 가져오기 |
compaction.clearLastResult | 저장된 결과 지우기 |
수정된 파일
| 파일 | 목적 |
|---|---|
src/gateway/server-methods/compaction.ts | 설정 RPC, 설정 I/O, 결과 기록 |
src/gateway/server-methods/sessions.ts | sessions.compact RPC (압축 후 결과 기록) |
src/gateway/server-methods/plugins-ui.ts | 플러그인 뷰 등록 |
src/gateway/server-methods.ts | 핸들러 연결 |
src/gateway/server-methods-list.ts | 메서드 등록 |
src/gateway/method-scopes.ts | 스코프 등록 |
src/agents/pi-embedded-runner/compact.ts | 채팅 요약 명령어 주입 |
ui/src/ui/app-render.helpers.ts | 컨텍스트 게이지 + 백그라운드 토스트 트리거 |
ui/src/ui/app-gateway.ts | final 이벤트 후 자동 압축 확인 |
ui/src/ui/views/compaction-settings.ts | 설정 탭 뷰 |
ui/src/ui/app-render.ts | 뷰 연결 + 임포트 |
ui/src/ui/views/chat.ts | 채팅 기록 필터 |
설정 파일
{agentDir}/compaction-config.json — 에이전트별, 첫 번째 설정 저장 시 생성됩니다.
플러그인 등록
압축 탭은 plugins-ui.ts에 내장 플러그인 뷰로 등록됩니다:
{
id: "compaction",
label: "Compaction",
subtitle: "메모리 관리",
icon: "archive",
group: "agent",
position: 7,
pluginId: "compaction-ui",
}
알려진 문제점
- 탭 방문 간 설정이 유지되지 않음: v2.1.0에서 수정되었습니다. 모듈 수준의
_state.loaded플래그가 다시 불러오기를 방지하고 있었습니다. 이제 탭에 다시 진입할 때 2초마다 다시 불러옵니다. - 모델 선택기에는 API 키가 필요합니다: 사용자 지정 모델을 선택하는 경우 프로바이더의 API 키가 구성되었는지 확인하세요. UI에 경고 콜아웃이 표시됩니다.
- 압축 모델 형식:
"provider/model"형식이어야 합니다 (예:"anthropic/claude-sonnet-4-6"). 잘못된 형식은 자동으로 무시되고 세션 기본값으로 폴백됩니다. - parentId 스킵-셋 전파는 메시지 전용이어야 합니다:
readSessionMessages에서 메모리 플러시 메시지를 필터링할 때 스킵 셋은message필드가 있는 항목을 통해서만 전파되어야 합니다. 메시지가 아닌 프로토콜 항목(type:"custom")은 논리적 턴을 연결합니다. 해당 ID가 스킵 셋에 들어가면 나머지 대화 전체가 숨겨집니다. 수정 방법: 스킵 셋에 대해parsed?.message항목만 확인하고 해당 ID만 스킵 셋에 추가합니다. - 차단 모달 없음 — 절대:
app-render.helpers.ts의 게이지 버튼은 절대 전체 화면 오버레이 모달을 렌더링해서는 안 됩니다. 압축은 백그라운드 프로세스입니다. 모든 상태는 오른쪽 하단 토스트 시스템을 통해 전달됩니다.compactState.phase에 조건부로 설정된position:fixed; inset:0오버레이를 제거하세요. 버튼은 실행 중에 스피너 아이콘을 표시할 수 있지만 UI를 차단해서는 안 됩니다.
변경 로그
v2.1.0
- 대화 요약 문단: 압축 출력이 이제 구조화된 섹션 앞에
## Conversation Summary서사 문단으로 시작합니다. - 모델 선택기: 압축에 사용할 특정 모델을 선택하거나 세션 기본값을 사용할 수 있으며, 프로바이더별로 그룹화된 드롭다운을 제공합니다.
- 설정 다시 불러오기 수정: 탭이 이제 설정을 영구 캐싱하는 대신 2초마다 백엔드에서 다시 불러옵니다.
- 참조 파일 업데이트:
references/를 현재 소스와 동기화했습니다.
v2.0.0
- 백그라운드 압축: 차단 전체 화면 모달을 백그라운드 작업 토스트로 대체했습니다.
- 자동 압축: 토큰 사용량이 임계값을 초과할 때 채팅 응답 후 트리거됩니다 (설정 가능, 기본값 60%, 5분 디바운스).
- 설정 탭: Agent 탐색 그룹 아래 플러그인 등록된 Compaction 탭.
- 결과 기록:
sessions.compact가 압축 전/후 토큰 개수와 선택적 요약을 기록합니다. - 인증 계층: 채팅과 동일한 OAuth → API → 폴백 체인.
- 설정 RPC:
compaction.getSettings,compaction.saveSettings,compaction.getLastResult,compaction.clearLastResult.
v1.0.0
- 초기 릴리스: 컨텍스트 게이지 버튼, 애니메이션 단계가 있는 차단 모달, LLM 요약을 사용한
sessions.compactRPC, 채팅 기록 NO_REPLY/HEARTBEAT_OK 필터링, 압축 구분선.