Session Pruning

Session pruning은 각 LLM 호출 직전에 인메모리 컨텍스트에서 오래된 tool 결과를 트리밍합니다. 디스크의 session 기록(*.jsonl)을 다시 작성하지는 않습니다.

실행 시점

  • mode: "cache-ttl"이 활성화되고 session에 대한 마지막 Anthropic 호출이 ttl보다 오래된 경우.
  • 해당 요청에 대해 model에 전송되는 메시지에만 영향을 줍니다.
  • Anthropic API 호출(및 OpenRouter Anthropic model)에만 활성화됩니다.
  • 최상의 결과를 위해 ttl을 model cacheControlTtl과 일치시키세요.
  • Prune 후 TTL 윈도우가 재설정되므로 후속 요청은 ttl이 다시 만료될 때까지 캐시를 유지합니다.

스마트 기본값 (Anthropic)

  • OAuth 또는 setup-token 프로필: cache-ttl pruning을 활성화하고 heartbeat을 1h로 설정합니다.
  • API key 프로필: cache-ttl pruning을 활성화하고, heartbeat을 30m로 설정하며, Anthropic model의 cacheControlTtl 기본값을 1h로 설정합니다.
  • 이러한 값을 명시적으로 설정하면 OpenClaw는 재정의하지 않습니다.

이것이 개선하는 것 (비용 + 캐시 동작)

  • Pruning 이유: Anthropic prompt caching은 TTL 내에서만 적용됩니다. Session이 TTL을 지나 유휴 상태가 되면 먼저 트리밍하지 않는 한 다음 요청은 전체 프롬프트를 다시 캐시합니다.
  • 저렴해지는 것: pruning은 TTL 만료 후 첫 번째 요청의 cacheWrite 크기를 줄입니다.
  • TTL 재설정이 중요한 이유: pruning이 실행되면 캐시 윈도우가 재설정되므로 후속 요청은 전체 기록을 다시 캐시하는 대신 새로 캐시된 프롬프트를 재사용할 수 있습니다.
  • 하지 않는 것: pruning은 토큰을 추가하거나 비용을 "이중"으로 만들지 않으며, TTL 이후 첫 번째 요청에서 캐시되는 내용만 변경합니다.

Prune 가능한 것

  • toolResult 메시지만 가능합니다.
  • 사용자 + assistant 메시지는 절대 수정되지 않습니다.
  • 마지막 keepLastAssistants assistant 메시지는 보호됩니다. 해당 cutoff 이후의 tool 결과는 prune되지 않습니다.
  • Cutoff를 설정하기에 충분한 assistant 메시지가 없으면 pruning을 건너뜁니다.
  • 이미지 블록을 포함하는 tool 결과는 건너뜁니다(절대 트리밍/지워지지 않음).

컨텍스트 윈도우 추정

Pruning은 추정된 컨텍스트 윈도우(문자 ≈ 토큰 × 4)를 사용합니다. 윈도우 크기는 다음 순서로 해결됩니다:

  1. Model 정의 contextWindow (model 레지스트리에서).
  2. models.providers.*.models[].contextWindow 재정의.
  3. agents.defaults.contextTokens.
  4. 기본값 200000 토큰.

모드

cache-ttl

  • Pruning은 마지막 Anthropic 호출이 ttl(기본값 5m)보다 오래된 경우에만 실행됩니다.
  • 실행 시: 이전과 동일한 soft-trim + hard-clear 동작.

Soft vs hard pruning

  • Soft-trim: 과도하게 큰 tool 결과에만 적용됩니다.
    • 헤드 + 테일을 유지하고 ...를 삽입하며 원래 크기가 포함된 노트를 추가합니다.
    • 이미지 블록이 있는 결과는 건너뜁니다.
  • Hard-clear: 전체 tool 결과를 hardClear.placeholder로 대체합니다.

Tool 선택

  • tools.allow / tools.deny는 * 와일드카드를 지원합니다.
  • Deny가 우선합니다.
  • 매칭은 대소문자를 구분하지 않습니다.
  • 빈 allow 목록 => 모든 tool 허용.

다른 제한과의 상호작용

  • 내장 tool은 이미 자체 출력을 잘라냅니다. Session pruning은 장기 실행 채팅이 model 컨텍스트에 너무 많은 tool 출력을 축적하는 것을 방지하는 추가 레이어입니다.
  • Compaction은 별도입니다: compaction은 요약하고 유지하며, pruning은 요청당 일시적입니다. /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]" }

예시

기본값 (비활성화):

{
  agent: {
    contextPruning: { mode: "off" }
  }
}

TTL 인식 pruning 활성화:

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

특정 tool로 pruning 제한:

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

config 참조 참조: Gateway Configuration

← 문서로 돌아가기