세션 정리

세션 가지치기는 각 LLM 호출 전에 컨텍스트에서 오래된 도구 결과를 잘라냅니다. 일반 대화 텍스트를 다시 작성하지 않으면서 누적된 도구 출력(실행 결과, 파일 읽기, 검색 결과)으로 인한 컨텍스트 비대화를 줄입니다.

중요한 이유

세션이 길어지면 도구 출력이 누적되어 컨텍스트 창이 커집니다. 이로 인해 비용이 증가하고 필요 이상으로 빨리 Compaction이 수행될 수 있습니다.

가지치기는 특히 Anthropic 프롬프트 캐싱에 유용합니다. 캐시 TTL이 만료되면 다음 요청에서 전체 프롬프트를 다시 캐싱합니다. 가지치기는 캐시 쓰기 크기를 줄여 비용을 직접 절감합니다.

작동 방식

가지치기는 cache-ttl 모드에서 실행되며, 시간 검사와 컨텍스트 크기 검사를 모두 통과해야 합니다.

1. 캐시 TTL이 만료될 때까지 기다립니다(수동 설정 시 기본값은 5분이며, Anthropic 자동 기본값은 스마트 기본값을 참조하세요). TTL이 경과하기 전에는 인접한 턴에서 프롬프트 캐시를 재사용할 수 있도록 가지치기를 완전히 건너뜁니다.
2. TTL이 경과하면 모델의 컨텍스트 창을 기준으로 전체 컨텍스트 크기를 추정합니다. 비율이 softTrimRatio(기본값 0.3)보다 낮으면 가지치기를 건너뛰고 TTL 타이머를 계속 실행합니다.
3. 비율을 초과하는 대용량 도구 결과를 소프트 트리밍합니다. 앞부분과 뒷부분을 유지하고(기본값은 각각 1,500자이며 합계는 최대 4,000자), 그 사이에 ...을 삽입합니다.
4. 비율이 여전히 hardClearRatio(기본값 0.5) 이상이고 가지치기 가능한 도구 콘텐츠가 minPrunableToolChars(기본값 50,000자) 이상 남아 있으면 해당 결과를 완전히 삭제합니다. 콘텐츠를 자리표시자(기본값 [오래된 도구 결과 콘텐츠가 삭제됨])로 대체합니다.
5. 가지치기로 컨텍스트가 실제로 변경된 경우에만 TTL 타이머를 재설정하여 후속 요청이 새 캐시를 재사용하도록 합니다.

임계값과 관계없이 두 가지 안전 규칙이 적용됩니다. 가장 최근의 keepLastAssistants 어시스턴트 턴(기본값 3개)은 절대 가지치기하지 않으며, 세션의 첫 번째 사용자 메시지 이전 항목도 절대 가지치기하지 않습니다(SOUL.md/USER.md와 같은 부트스트랩 읽기를 보호합니다).

toolResult 메시지만 대상이 되며 일반 대화 텍스트는 그대로 유지됩니다. 가지치기할 수 있는 도구 이름의 범위를 지정하려면 agents.defaults.contextPruning.tools.{allow,deny}를 사용하세요.

레거시 이미지 정리

OpenClaw는 원시 이미지 블록이나 프롬프트 하이드레이션 미디어 마커가 기록에 유지되는 세션을 위해 별도의 멱등 재생 뷰도 생성합니다.

• 최근 완료된 3개 턴을 바이트 단위로 그대로 보존하여 최근 후속 요청의 프롬프트 캐시 접두사가 안정적으로 유지되도록 합니다. 이 개수에는 이미지가 포함된 턴뿐만 아니라 완료된 모든 턴이 포함되므로 텍스트 전용 턴도 이 범위에 포함됩니다.
• 재생 뷰에서는 user 또는 toolResult 기록에 있는 이전의 이미 처리된 이미지 블록을 [이미지 데이터 제거됨 - 모델에서 이미 처리함]으로 대체합니다.
• [media attached: ...], [Image: source: ...], media://inbound/...와 같은 이전의 텍스트 미디어 참조는 [미디어 참조 제거됨 - 모델에서 이미 처리함]으로 대체합니다. 현재 턴의 첨부 파일 마커는 그대로 유지되므로 비전 모델이 새 이미지를 계속 하이드레이션할 수 있습니다.
• 원시 세션 트랜스크립트는 다시 작성되지 않으므로 기록 뷰어에서 원래 메시지 항목과 이미지를 계속 렌더링할 수 있습니다.
• 이는 위의 일반적인 캐시 TTL 가지치기와 별개입니다. 이후 턴에서 반복되는 이미지 페이로드나 오래된 미디어 참조로 인해 프롬프트 캐시가 무효화되는 것을 방지합니다.

스마트 기본값

번들 Anthropic Plugin은 Anthropic(또는 Claude CLI) 인증 프로필을 처음 확인할 때 가지치기와 Heartbeat 주기를 자동으로 구성하지만, 아직 명시적으로 설정하지 않은 필드에만 적용합니다.

agents.defaults.contextPruning.mode 또는 agents.defaults.heartbeat.every를 직접 설정하면 OpenClaw는 해당 값을 재정의하지 않습니다. 이 자동 기본값은 Anthropic 계열 인증에만 적용되며, 다른 제공자의 가지치기는 직접 구성하지 않는 한 off로 설정됩니다.

활성화 또는 비활성화

Anthropic 이외 제공자의 가지치기는 기본적으로 꺼져 있습니다. 활성화하려면 다음과 같이 설정합니다.

{  agents: {    defaults: {      contextPruning: { mode: "cache-ttl", ttl: "5m" },    },  },}

비활성화하려면 mode: "off"로 설정합니다.

가지치기와 Compaction 비교

두 기능은 서로 보완합니다. 가지치기는 Compaction 주기 사이에 도구 출력을 간결하게 유지합니다.

추가 자료

• Compaction: 요약 기반 컨텍스트 축소
• Gateway 구성: 모든 가지치기 구성 옵션(contextPruning.*)

관련 항목

• 세션 관리
• 세션 도구
• 컨텍스트 엔진