Session pruning

기준일: 2026-07-26
공식 기준: Session pruning

Session pruning 문서는 OpenClaw 공식 문서(concepts/session-pruning)를 한국어로 정리한 가이드입니다. Trimming old tool results to keep context lean and caching efficient 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Trimming old tool results to keep context lean and caching efficient

한국어 가이드 범위: concepts/session-pruning 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Why it matters
• 동작 방식
• Legacy image cleanup
• Smart defaults
• Enable or disable
• Pruning vs compaction
• Further reading
• 관련 문서

상세 내용

본문

Session pruning trims old tool results from the context before each LLM call. It reduces context bloat from accumulated tool outputs (exec results, file reads, search results) without rewriting normal conversation text.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Why it matters

Long sessions accumulate tool output that inflates the context window. This increases cost and can force compaction sooner than necessary.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

동작 방식

Pruning runs in cache-ttl mode, gated on both a time check and a context-size check:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Legacy image cleanup

OpenClaw also builds a separate idempotent replay view for sessions that persist raw image blocks or prompt-hydration media markers in history.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• It preserves the 3 most recent completed turns byte-for-byte so prompt cache prefixes for recent follow-ups stay stable. This count includes all completed turns, not just image-bearing ones, so text-only turns consume the window too.
• In the replay view, older already-processed image blocks from user or toolResult history are replaced with [image data removed - already processed by model].
• Older textual media references such as [media attached: ...], [Image: source: ...], and media://inbound/... are replaced with [media reference removed - already processed by model]. Current-turn attachment markers stay intact so vision models can still hydrate fresh images.
• The raw session transcript is not rewritten, so history viewers can still render the original message entries and their images.
• This is separate from normal cache-TTL pruning above. It exists to stop repeated image payloads or stale media refs from busting prompt caches on later turns.

Smart defaults

The bundled Anthropic plugin auto-configures pruning and heartbeat cadence the first time it resolves an Anthropic (or Claude CLI) auth profile, but only for fields you have not already set explicitly:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Auth mode	contextPruning.mode	contextPruning.ttl	heartbeat.every
OAuth/token (including Claude CLI reuse)	cache-ttl	1h	1h
API key	cache-ttl	1h	30m

Enable or disable

Pruning is off by default for non-Anthropic providers. To enable:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

Pruning vs compaction

They complement each other -- pruning keeps tool output lean between compaction cycles.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

	Pruning	Compaction
What	Trims tool results	Summarizes conversation
Saved?	No (per-request)	Yes (in transcript)
Scope	Tool results only	Entire conversation

Further reading

주요 항목:

• Compaction: summarization-based context reduction
• Gateway Configuration: all pruning config knobs (contextPruning.*)

관련 문서

주요 항목:

• Session management
• Session tools
• Context engine

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/session-pruning
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

관련 링크

• 공식 원문: concepts/session-pruning
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.