Compaction

기준일: 2026-07-26
공식 기준: Compaction

Compaction 문서는 OpenClaw 공식 문서(concepts/compaction)를 한국어로 정리한 가이드입니다. How OpenClaw summarizes long conversations to stay within model limits 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

How OpenClaw summarizes long conversations to stay within model limits

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

문서 구성

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

• 동작 방식
• Auto-compaction
• Manual compaction
• 구성
• Using a different model
• Identifier preservation
• Active transcript byte guard
• Successor transcripts
• Compaction notices
• Memory flush
• Pluggable compaction providers
• Compaction vs pruning
• 트러블슈팅
• 관련 문서

상세 내용

본문

Every model has a context window: the maximum number of tokens it can process. When a conversation approaches that limit, OpenClaw compacts older messages into a summary so the chat can continue.

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

동작 방식

1. Older conversation turns are summarized into a compact entry. 2. The summary is saved in the session transcript. 3. Recent messages are kept intact.

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

Auto-compaction

Auto-compaction is on by default. It runs when the session nears the context limit, or when the model returns a context-overflow error (in which case OpenClaw compacts and retries).

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

주요 항목:

• embedded run auto-compaction start / complete in normal Gateway logs.
• 🧹 Auto-compaction complete in verbose mode.
• /status showing 🧹 Compactions: <count>.
• request_too_large
• context length exceeded
• input exceeds the maximum number of tokens
• input token count exceeds the maximum number of input tokens (Bedrock)
• input is too long for the model
• ollama error: context length exceeded

Manual compaction

Type /compact in any chat to force a compaction. Add instructions to guide the summary:

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

/compact Focus on the API design decisions

구성

Configure compaction under agents.defaults.compaction in your openclaw.json. The most common knobs are listed below; for the full reference, see Session management deep dive.

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

Using a different model

By default, compaction uses the agent's primary model. Set agents.defaults.compaction.model to delegate summarization to a more capable or specialized model. The override accepts a provider/model-id string or a bare alias configured under agents.defaults.models:

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

{
  "agents": {
    "defaults": {
      "compaction": {
        "model": "openrouter/anthropic/claude-sonnet-4-6"
      }
    }
  }
}

{
  "agents": {
    "defaults": {
      "compaction": {
        "model": "ollama/llama3.1:8b"
      }
    }
  }
}

Identifier preservation

Compaction summarization preserves opaque identifiers by default (identifierPolicy: "strict"). Override with identifierPolicy: "off" to disable. Custom guidance belongs in a compaction provider's summarize() implementation.

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

Active transcript byte guard

When agents.defaults.compaction.maxActiveTranscriptBytes is set, OpenClaw triggers normal local compaction before a run if transcript history reaches that size. This is useful for long-running sessions where provider-side context management may keep model context healthy while persisted transcript history keeps growing. It does not split raw bytes; it asks the normal compaction pipeline to create a semantic summary.

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

Successor transcripts

When agents.defaults.compaction.truncateAfterCompaction is enabled, OpenClaw does not rewrite the existing transcript in place. It creates a new active successor transcript from the compaction summary, preserved state, and unsummarized tail, then records checkpoint metadata that points branch/restore flows at that compacted successor. Successor transcripts also drop exact duplicate long user turns that arrive inside a short retry window, so channel retry storms are not carried into the next active transcript after compaction.

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

Compaction notices

By default, compaction runs silently. Set notifyUser to show brief status messages when compaction starts and completes, and to surface a degraded notice when a pre-compaction memory flush is exhausted but the reply still continues:

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

{
  agents: {
    defaults: {
      compaction: {
        notifyUser: true,
      },
    },
  },
}

Memory flush

Before compaction, OpenClaw can run a silent memory flush turn to store durable notes to disk. Set agents.defaults.compaction.memoryFlush.model when this housekeeping turn should use a local model instead of the active conversation model:

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

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "model": "ollama/qwen3:8b"
        }
      }
    }
  }
}

Pluggable compaction providers

Plugins can register a custom compaction provider via registerCompactionProvider() on the plugin API. When a provider is registered and configured, OpenClaw delegates summarization to it instead of the built-in LLM pipeline.

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

{
  "agents": {
    "defaults": {
      "compaction": {
        "provider": "my-provider"
      }
    }
  }
}

Compaction vs pruning

Session pruning is a lighter-weight complement that trims tool output without summarizing.

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

	Compaction	Pruning
What it does	Summarizes older conversation	Trims old tool results
Saved?	Yes (in session transcript)	No (in-memory only, per request)
Scope	Entire conversation	Tool results only

트러블슈팅

For advanced configuration (reserve tokens, identifier preservation, custom context engines, OpenAI server-side compaction), see the Session management deep dive.

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

관련 문서

주요 항목:

• Session: session management and lifecycle.
• Session pruning: trimming tool results.
• Context: how context is built for agent turns.
• Hooks: compaction lifecycle hooks (before_compaction, after_compaction).

실습 체크리스트

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

자주 쓰는 명령·설정 예시

/compact Focus on the API design decisions

{
  "agents": {
    "defaults": {
      "compaction": {
        "model": "openrouter/anthropic/claude-sonnet-4-6"
      }
    }
  }
}

{
  "agents": {
    "defaults": {
      "compaction": {
        "model": "ollama/llama3.1:8b"
      }
    }
  }
}

{
  agents: {
    defaults: {
      compaction: {
        notifyUser: true,
      },
    },
  },
}

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "model": "ollama/qwen3:8b"
        }
      }
    }
  }
}

{
  "agents": {
    "defaults": {
      "compaction": {
        "provider": "my-provider"
      }
    }
  }
}

관련 링크

• 공식 원문: concepts/compaction
• OpenClaw 문서 홈

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