컨텍스트 엔진

개요

컨텍스트 엔진은 각 에이전트 실행(run)에서 모델 컨텍스트 구성을 담당한다. 대화 히스토리, 시스템 프롬프트, 도구 결과 등을 토큰 예산 내에서 최적으로 조합하여 모델에 전달한다.

4단계 생명주기

컨텍스트 엔진은 4개의 생명주기 포인트에서 동작한다.

1. Ingest (수집)

새로운 메시지를 처리하는 단계이다.

• 사용자 메시지, 도구 결과 등 새로 들어온 데이터 수집
• 메시지 형식 정규화
• 메타데이터 부착 (타임스탬프, 소스 등)

2. Assemble (조립)

토큰 예산에 맞게 메시지 세트를 구성하는 단계이다.

• 순서에 맞게 메시지 정렬
• 토큰 예산 계산
• 예산 초과 시 오래된 메시지부터 제외
• 시스템 프롬프트, 부트스트랩 파일, 사용자 메시지, 도구 결과 등을 합산

┌─────────────────────────────────────────┐
│            토큰 예산                      │
│                                          │
│  [시스템 프롬프트] ← 항상 포함              │
│  [부트스트랩 파일] ← 첫 턴에 포함           │
│  [요약된 히스토리] ← 압축된 과거 대화        │
│  [최근 대화]      ← 가능한 많이 포함        │
│  [새 메시지]      ← 항상 포함              │
│                                          │
└─────────────────────────────────────────┘

3. Compact (압축)

오래된 히스토리를 요약하는 단계이다.

• 토큰 예산을 초과하는 과거 대화를 자동 요약
• 요약본을 컨텍스트에 포함하여 장기 대화 지원
• 메모리 플러싱(flushing)이 압축 전에 자동 실행됨

4. After Turn (턴 이후)

에이전트 실행이 완료된 후 처리하는 단계이다.

• 세션 데이터 업데이트
• 메모리 파일 업데이트 (필요한 경우)
• 통계 기록

내장 엔진: Legacy

OpenClaw에는 **“legacy”**라는 내장 컨텍스트 엔진이 기본 제공된다.

• 기본적인 토큰 카운팅과 히스토리 잘라내기
• 자동 요약(compaction) 지원
• 대부분의 사용 사례에 충분

플러그인 엔진

더 고급 컨텍스트 관리가 필요한 경우 플러그인 엔진을 설치할 수 있다.

openclaw plugins install <engine-name>

주의사항

• 한 번에 하나의 엔진만 활성화 가능하다
• 플러그인 엔진을 설정하면 내장 legacy 엔진 대신 사용됨
• 에이전트별로 다른 엔진을 지정할 수 있음

엔진 설정 예시

설정 파일에서 컨텍스트 엔진을 지정한다:

{
  "agents": {
    "default": {
      "contextEngine": "legacy"  // 또는 플러그인 엔진 이름
    }
  }
}

토큰 예산 관리

컨텍스트 엔진의 핵심 역할은 모델의 컨텍스트 윈도우 크기 내에서 최대한 유용한 정보를 포함하는 것이다.

자동 압축이 실행되면 오래된 메시지가 요약문으로 대체되어 토큰을 절약한다.