​

컨텍스트 엔진

​

빠른 시작

openclaw doctor
# 또는 config를 직접 확인:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

​

컨텍스트 엔진 plugin 설치하기

# npm에서 설치
openclaw plugins install @martian-engineering/lossless-claw

# 또는 로컬 경로에서 설치 (개발용)
openclaw plugins install -l ./my-context-engine

// openclaw.json
{
  plugins: {
    slots: {
      contextEngine: "lossless-claw", // plugin에 등록된 엔진 id와 일치해야 합니다
    },
    entries: {
      "lossless-claw": {
        enabled: true,
        // plugin별 config는 여기에 입력합니다 (plugin 문서 참고)
      },
    },
  },
}

​

작동 방식

1. Ingest — 새 메시지가 세션에 추가될 때 호출됩니다. 엔진은 자체 데이터 저장소에 메시지를 저장하거나 인덱싱할 수 있습니다.
2. Assemble — 각 모델 실행 전에 호출됩니다. 엔진은 토큰 예산 안에 들어가는 정렬된 메시지 집합과 선택적인 systemPromptAddition을 반환합니다.
3. Compact — 컨텍스트 창이 가득 찼을 때 또는 사용자가 /compact를 실행할 때 호출됩니다. 엔진은 공간을 확보하기 위해 오래된 기록을 요약합니다.
4. After turn — 실행이 완료된 뒤 호출됩니다. 엔진은 상태를 유지하거나, 백그라운드 압축을 트리거하거나, 인덱스를 업데이트할 수 있습니다.

​

서브에이전트 수명 주기(선택 사항)

• onSubagentEnded — 서브에이전트 세션이 완료되거나 정리될 때 정리 작업을 수행합니다.

​

시스템 프롬프트 추가

​

legacy 엔진

• Ingest: no-op(세션 관리자가 메시지 영속성을 직접 처리).
• Assemble: pass-through(런타임의 기존 sanitize → validate → limit 파이프라인이 컨텍스트 조합을 처리).
• Compact: 내장 요약 압축에 위임하며, 이 과정에서 오래된 메시지의 단일 요약을 만들고 최근 메시지는 그대로 유지합니다.
• After turn: no-op.

​

plugin 엔진

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function register(api) {
  api.registerContextEngine("my-engine", () => ({
    info: {
      id: "my-engine",
      name: "My Context Engine",
      ownsCompaction: true,
    },

    async ingest({ sessionId, message, isHeartbeat }) {
      // 메시지를 데이터 저장소에 저장
      return { ingested: true };
    },

    async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) {
      // 예산에 맞는 메시지 반환
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },

    async compact({ sessionId, force }) {
      // 오래된 컨텍스트 요약
      return { ok: true, compacted: true };
    },
  }));
}

{
  plugins: {
    slots: {
      contextEngine: "my-engine",
    },
    entries: {
      "my-engine": {
        enabled: true,
      },
    },
  },
}

​

ContextEngine 인터페이스

• messages — 모델에 보낼 정렬된 메시지입니다.
• estimatedTokens (필수, number) — 조합된 컨텍스트 전체 토큰 수에 대한 엔진의 추정치입니다. OpenClaw는 이를 압축 임계값 판단과 진단 보고에 사용합니다.
• systemPromptAddition (선택 사항, string) — 시스템 프롬프트 앞에 추가됩니다.

​

ownsCompaction

• true — 엔진이 압축 동작을 소유합니다. OpenClaw는 해당 실행에서 Pi의 내장 자동 압축을 비활성화하며, 엔진의 compact() 구현이 /compact, 오버플로 복구 압축, 그리고 afterTurn()에서 수행하려는 모든 선제적 압축을 책임집니다.
• false 또는 미설정 — 프롬프트 실행 중 Pi의 내장 자동 압축은 여전히 실행될 수 있지만, 활성 엔진의 compact() 메서드는 /compact 및 오버플로 복구 시에도 계속 호출됩니다.

• 소유 모드 — 자체 압축 알고리즘을 구현하고 ownsCompaction: true로 설정합니다.
• 위임 모드 — ownsCompaction: false로 설정하고 compact()가 openclaw/plugin-sdk/core의 delegateCompactionToRuntime(...)를 호출해 OpenClaw의 내장 압축 동작을 사용하도록 합니다.

​

구성 참조

{
  plugins: {
    slots: {
      // 활성 컨텍스트 엔진을 선택합니다. 기본값: "legacy".
      // plugin id로 설정하면 plugin 엔진을 사용합니다.
      contextEngine: "legacy",
    },
  },
}

​

압축 및 메모리와의 관계

• 압축은 컨텍스트 엔진의 한 가지 책임입니다. legacy 엔진은 OpenClaw의 내장 요약 기능에 위임합니다. Plugin 엔진은 어떤 압축 전략이든 구현할 수 있습니다(DAG 요약, 벡터 검색 등).
• 메모리 plugins (plugins.slots.memory)는 컨텍스트 엔진과 별개입니다. 메모리 plugins는 검색/조회 기능을 제공하고, 컨텍스트 엔진은 모델이 무엇을 볼지 제어합니다. 둘은 함께 동작할 수 있습니다 — 컨텍스트 엔진이 조합 중에 메모리 plugin 데이터를 사용할 수도 있습니다. 활성 메모리 프롬프트 경로를 사용하려는 plugin 엔진은 openclaw/plugin-sdk/core의 buildMemorySystemPromptAddition(...)을 우선 사용하는 것이 좋습니다. 이 함수는 활성 메모리 프롬프트 섹션을 바로 앞에 붙일 수 있는 systemPromptAddition으로 변환합니다. 엔진에 더 낮은 수준의 제어가 필요하다면, 여전히 openclaw/plugin-sdk/memory-host-core의 buildActiveMemoryPromptSection(...)을 통해 원시 라인을 가져올 수 있습니다.
• 세션 정리(Session pruning)(메모리 내 오래된 도구 결과 잘라내기)는 어떤 컨텍스트 엔진이 활성 상태이든 계속 실행됩니다.

​

팁

• openclaw doctor를 사용해 엔진이 올바르게 로드되는지 확인하세요.
• 엔진을 전환하더라도 기존 세션은 현재 기록을 유지한 채 계속됩니다. 새 엔진은 이후 실행부터 적용됩니다.
• 엔진 오류는 로그에 기록되고 진단에도 표시됩니다. plugin 엔진이 등록에 실패하거나 선택한 엔진 id를 해석할 수 없으면 OpenClaw는 자동으로 폴백하지 않으며, plugin을 수정하거나 plugins.slots.contextEngine을 "legacy"로 다시 전환할 때까지 실행이 실패합니다.
• 개발 시에는 openclaw plugins install -l ./my-engine를 사용해 로컬 plugin 디렉터리를 복사하지 않고 연결할 수 있습니다.

​

관련 항목

• 컨텍스트 — 에이전트 턴을 위한 컨텍스트가 빌드되는 방식
• Plugin Architecture — 컨텍스트 엔진 plugins 등록
• 압축 — 긴 대화 요약하기