세션 프루닝

세션 프루닝은 각 LLM 호출 직전에 인메모리 컨텍스트에서 오래된 도구 결과를 트리밍합니다. 디스크의 세션 히스토리(*.jsonl)는 수정하지 않습니다.

실행 시점

mode: "cache-ttl"이 활성화되어 있고 해당 세션의 마지막 Anthropic 호출이 ttl보다 오래된 경우에 실행됩니다.
해당 요청에서 모델로 전송되는 메시지에만 영향을 미칩니다.
Anthropic API 호출(및 OpenRouter Anthropic 모델)에서만 활성화됩니다.
최적의 결과를 위해 ttl을 모델의 cacheRetention 정책에 맞추세요 (short = 5분, long = 1시간).
프루닝 후 TTL 윈도우가 리셋되므로 후속 요청은 ttl이 다시 만료될 때까지 캐시를 유지합니다.

스마트 기본값 (Anthropic)

OAuth 또는 setup-token 프로필: cache-ttl 프루닝을 활성화하고 하트비트를 1h로 설정합니다.
API 키 프로필: cache-ttl 프루닝을 활성화하고 하트비트를 30m으로 설정하며, Anthropic 모델에서 cacheRetention: "short"를 기본값으로 사용합니다.
이러한 값을 명시적으로 설정하면 OpenClaw이 덮어쓰지 않습니다.

개선되는 점 (비용 + 캐시 동작)

프루닝의 필요성: Anthropic 프롬프트 캐싱은 TTL 내에서만 적용됩니다. 세션이 TTL을 넘겨 유휴 상태가 되면, 다음 요청에서 먼저 트리밍하지 않으면 전체 프롬프트를 다시 캐싱합니다.
비용 절감 효과: 프루닝은 TTL 만료 후 첫 번째 요청의 cacheWrite 크기를 줄입니다.
TTL 리셋의 의미: 프루닝이 실행되면 캐시 윈도우가 리셋되어 후속 요청이 전체 히스토리를 다시 캐싱하는 대신 새로 캐싱된 프롬프트를 재사용할 수 있습니다.
하지 않는 것: 프루닝은 토큰을 추가하거나 비용을 “이중”으로 만들지 않습니다. TTL 만료 후 첫 번째 요청에서 캐싱되는 내용만 변경합니다.

프루닝 가능한 대상

toolResult 메시지만 해당됩니다.
사용자 + 어시스턴트 메시지는 절대 수정되지 않습니다.
마지막 keepLastAssistants개의 어시스턴트 메시지가 보호되며, 그 이후의 도구 결과는 프루닝되지 않습니다.
어시스턴트 메시지가 충분하지 않아 컷오프를 설정할 수 없으면 프루닝을 건너뜁니다.
이미지 블록을 포함하는 도구 결과는 건너뜁니다(트리밍/삭제되지 않음).

컨텍스트 윈도우 추정

프루닝은 추정된 컨텍스트 윈도우(문자 수 = 토큰 수 x 4)를 사용합니다. 기본 윈도우는 다음 순서로 결정됩니다:

models.providers.*.models[].contextWindow 오버라이드.
모델 정의 contextWindow (모델 레지스트리에서).
기본값 200000 토큰.

agents.defaults.contextTokens가 설정된 경우 결정된 윈도우의 상한(최소값)으로 적용됩니다.

모드

cache-ttl

마지막 Anthropic 호출이 ttl(기본값 5m)보다 오래된 경우에만 프루닝이 실행됩니다.
실행 시: 기존과 동일한 소프트 트림 + 하드 클리어 동작.

소프트 vs 하드 프루닝

소프트 트림: 과대 도구 결과에만 적용.
- 앞부분 + 뒷부분을 유지하고 ...를 삽입하며 원본 크기를 나타내는 메모를 추가합니다.
- 이미지 블록이 있는 결과는 건너뜁니다.
하드 클리어: 전체 도구 결과를 hardClear.placeholder로 대체합니다.

도구 선택

tools.allow / tools.deny는 * 와일드카드를 지원합니다.
deny가 우선합니다.
매칭은 대소문자를 구분하지 않습니다.
allow 목록이 비어 있으면 => 모든 도구 허용.

다른 제한과의 상호작용

내장 도구는 이미 자체 출력을 잘라내며, 세션 프루닝은 장기 실행 대화에서 모델 컨텍스트에 너무 많은 도구 출력이 누적되는 것을 방지하는 추가 레이어입니다.
압축(Compaction)은 별도입니다: 압축은 요약하여 영구 저장하고, 프루닝은 요청별로 일시적입니다. /concepts/compaction을 참고하세요.

기본값 (활성화 시)

ttl: "5m"
keepLastAssistants: 3
softTrimRatio: 0.3
hardClearRatio: 0.5
minPrunableToolChars: 50000
softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }
hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }

예시

기본값 (비활성화):

{
  agents: { defaults: { contextPruning: { mode: "off" } } },
}

TTL 기반 프루닝 활성화:

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

특정 도구로 프루닝 제한:

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl",
        tools: { allow: ["exec", "read"], deny: ["*image*"] },
      },
    },
  },
}

설정 참조: 게이트웨이 구성