OpenClaw 컨텍스트 엔진 설정: 커스텀 플러그인 연동 가이드

AI 에이전트를 개발하다 보면 가장 골치 아픈 게 바로 컨텍스트 관리죠. 대화가 길어질수록 토큰 제한은 다가오고, 중요한 정보를 놓치지 않으면서도 효율적으로 히스토리를 요약하는 건 정말 까다로운 작업이에요.

OpenClaw의 Context Engine은 이런 고민을 해결해 줍니다. 각 실행마다 모델의 컨텍스트를 어떻게 구성할지 제어하고, 오래된 히스토리를 요약하거나 서브에이전트 간의 컨텍스트를 관리하는 방식을 결정하거든요. 기본적으로 legacy 엔진이 내장되어 있지만, 플러그인을 통해 여러분만의 엔진을 등록해 사용할 수도 있습니다.

빠른 시작

현재 어떤 엔진이 활성화되어 있는지 확인하려면 다음 명령어를 실행해 보세요.

openclaw doctor
# or inspect config directly:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

Context Engine 플러그인 설치하기

Context Engine 플러그인도 다른 OpenClaw 플러그인과 설치 방법은 같아요. 먼저 설치한 다음, 슬롯에서 해당 엔진을 선택하면 됩니다.

# Install from npm
openclaw plugins install @martian-engineering/lossless-claw

# Or install from a local path (for development)
openclaw plugins install -l ./my-context-engine

그 다음 플러그인을 활성화하고 설정 파일에서 사용할 엔진으로 선택해 주세요.

{
  plugins: {
    slots: {
      contextEngine: "lossless-claw", // must match the plugin's registered engine id
    },
    entries: {
      "lossless-claw": {
        enabled: true,
        // Plugin-specific config goes here (see the plugin's docs)
      },
    },
  },
}

설치와 설정을 마쳤다면 Gateway를 다시 시작해 주세요.

다시 내장 엔진으로 돌아가고 싶다면 contextEngine을 "legacy"로 설정하거나 해당 키를 아예 삭제하면 됩니다. ("legacy"가 기본값이에요.)

작동 원리

OpenClaw가 모델 프롬프트를 실행할 때마다 Context Engine은 다음 네 가지 라이프사이클 지점에 관여합니다.

Ingest — 세션에 새로운 메시지가 추가될 때 호출됩니다. 엔진은 이 메시지를 자체 데이터 저장소에 저장하거나 인덱싱할 수 있어요.
Assemble — 각 모델 실행 직전에 호출됩니다. 엔진은 토큰 예산(token budget) 내에 맞는 정렬된 메시지 세트와 선택 사항인 systemPromptAddition을 반환합니다.
Compact — 컨텍스트 윈도우가 가득 차거나 사용자가 /compact를 실행할 때 호출됩니다. 엔진은 공간을 확보하기 위해 오래된 히스토리를 요약합니다.
After turn — 실행이 완료된 후 호출됩니다. 엔진은 상태를 유지하거나, 백그라운드 요약을 트리거하거나, 인덱스를 업데이트할 수 있습니다.

서브에이전트 라이프사이클 (선택 사항)

현재 OpenClaw는 하나의 서브에이전트 라이프사이클 훅을 호출합니다.

onSubagentEnded — 서브에이전트 세션이 완료되거나 정리될 때 리소스를 정리합니다.

prepareSubagentSpawn 훅은 향후 사용을 위해 인터페이스에 포함되어 있지만, 아직 런타임에서 호출되지는 않아요.

System prompt addition

assemble 메서드는 systemPromptAddition 문자열을 반환할 수 있습니다. OpenClaw는 이를 해당 실행의 시스템 프롬프트 맨 앞에 추가해요. 덕분에 엔진은 정적인 워크스페이스 파일 없이도 동적인 회상 가이드, 검색 지침 또는 컨텍스트 관련 힌트를 주입할 수 있습니다.

Legacy 엔진

기본 내장된 legacy 엔진은 OpenClaw의 원래 동작 방식을 그대로 유지합니다.

Ingest: 아무 작업도 하지 않습니다 (세션 매니저가 메시지 영구 저장을 직접 처리합니다).
Assemble: 그대로 통과시킵니다 (런타임에 있는 기존 sanitize → validate → limit 파이프라인이 컨텍스트 조립을 처리합니다).
Compact: 내장된 요약 방식의 Compaction에 위임합니다. 오래된 메시지들은 하나의 요약본으로 만들고 최근 메시지들은 그대로 유지하는 방식이에요.
After turn: 아무 작업도 하지 않습니다.

Legacy 엔진은 별도의 도구를 등록하거나 systemPromptAddition을 제공하지 않아요.

plugins.slots.contextEngine이 설정되지 않았거나 "legacy"로 설정된 경우 이 엔진이 자동으로 사용됩니다.

플러그인 엔진

플러그인 API를 사용하면 직접 Context Engine을 등록할 수 있습니다.

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

    async ingest({ sessionId, message, isHeartbeat }) {
      // Store the message in your data store
      return { ingested: true };
    },

    async assemble({ sessionId, messages, tokenBudget }) {
      // Return messages that fit the budget
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: "Use lcm_grep to search history...",
      };
    },

    async compact({ sessionId, force }) {
      // Summarize older context
      return { ok: true, compacted: true };
    },
  }));
}

그 다음 설정에서 활성화해 주세요.

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

ContextEngine 인터페이스

필수 멤버:

멤버	종류	용도
`info`	속성	엔진 ID, 이름, 버전 및 Compaction 소유 여부
`ingest(params)`	메서드	단일 메시지 저장
`assemble(params)`	메서드	모델 실행을 위한 컨텍스트 구축 (`AssembleResult` 반환)
`compact(params)`	메서드	컨텍스트 요약/축소

assemble은 다음을 포함한 AssembleResult를 반환합니다.

messages — 모델에 보낼 정렬된 메시지들.
estimatedTokens (필수, number) — 조립된 컨텍스트의 총 토큰 수 추정치. OpenClaw는 이를 Compaction 임계값 결정 및 진단 보고에 사용합니다.
systemPromptAddition (선택 사항, string) — 시스템 프롬프트 앞에 추가될 내용.

선택 멤버:

멤버	종류	용도
`bootstrap(params)`	메서드	세션의 엔진 상태 초기화. 엔진이 세션을 처음 볼 때(예: 히스토리 가져오기) 한 번 호출됩니다.
`ingestBatch(params)`	메서드	완료된 턴을 배치로 수집. 실행이 끝난 후 해당 턴의 모든 메시지를 한꺼번에 전달받습니다.
`afterTurn(params)`	메서드	실행 후 라이프사이클 작업 (상태 저장, 백그라운드 요약 트리거 등).
`prepareSubagentSpawn(params)`	메서드	자식 세션을 위한 공유 상태 설정.
`onSubagentEnded(params)`	메서드	서브에이전트 종료 후 정리 작업.
`dispose()`	메서드	리소스 해제. Gateway 종료 또는 플러그인 다시 로드 시 호출되며, 세션별로 호출되지 않습니다.

ownsCompaction

ownsCompaction은 실행 중에 Pi의 내장 자동 Compaction 기능을 활성화해 둘지 여부를 제어합니다.

true — 엔진이 Compaction 동작을 직접 소유합니다. OpenClaw는 해당 실행에 대해 Pi의 내장 자동 Compaction을 비활성화하며, 엔진의 compact() 구현이 /compact, 오버플로 복구 요약, afterTurn()에서의 선제적 요약 등을 책임집니다.
false 또는 미설정 — 프롬프트 실행 중에 Pi의 내장 자동 Compaction이 여전히 실행될 수 있습니다. 하지만 /compact나 오버플로 복구 시에는 여전히 활성 엔진의 compact() 메서드가 호출됩니다.

ownsCompaction: false라고 해서 OpenClaw가 자동으로 Legacy 엔진의 Compaction 경로로 되돌아가는 것은 아닙니다.

따라서 두 가지 유효한 플러그인 패턴이 존재합니다.

소유 모드(Owning mode) — 직접 Compaction 알고리즘을 구현하고 ownsCompaction: true로 설정합니다.
위임 모드(Delegating mode) — ownsCompaction: false로 설정하고, compact() 내부에서 openclaw/plugin-sdk/core의 delegateCompactionToRuntime(...)을 호출하여 OpenClaw의 내장 Compaction 동작을 사용합니다.

활성화된 비소유 엔진에서 compact()를 아무 작업도 하지 않게(no-op) 두는 것은 위험합니다. 해당 엔진 슬롯에 대한 일반적인 /compact 및 오버플로 복구 경로가 비활성화되기 때문이에요.

설정 참조

{
  plugins: {
    slots: {
      // Select the active context engine. Default: "legacy".
      // Set to a plugin id to use a plugin engine.
      contextEngine: "legacy",
    },
  },
}

이 슬롯은 런타임에 독점적으로 사용됩니다. 특정 실행이나 Compaction 작업 시에는 등록된 엔진 중 하나만 선택되어 작동해요. kind: "context-engine"인 다른 플러그인들도 로드되어 등록 코드를 실행할 수는 있지만, plugins.slots.contextEngine은 OpenClaw가 엔진이 필요할 때 어떤 ID를 찾아 사용할지만 결정합니다.

Compaction 및 Memory와의 관계

Compaction은 Context Engine의 책임 중 하나입니다. Legacy 엔진은 OpenClaw의 내장 요약 기능에 위임하며, 플러그인 엔진은 DAG 요약이나 벡터 검색 등 어떤 전략이든 구현할 수 있습니다.
Memory 플러그인(plugins.slots.memory)은 Context Engine과 별개입니다. Memory 플러그인은 검색 및 조회를 제공하고, Context Engine은 모델에게 무엇을 보여줄지 제어합니다. 이 둘은 함께 작동할 수 있는데, 예를 들어 Context Engine이 조립 과정에서 Memory 플러그인의 데이터를 사용할 수 있습니다.
세션 프루닝(Session pruning) (메모리 내의 오래된 도구 결과 정리)은 어떤 Context Engine이 활성화되어 있든 상관없이 항상 실행됩니다.

팁

openclaw doctor를 사용해 엔진이 제대로 로드되는지 확인해 보세요.
엔진을 교체하더라도 기존 세션은 현재 히스토리를 유지하며 계속 진행됩니다. 새 엔진은 이후의 실행부터 제어권을 갖게 됩니다.
엔진 오류는 로그에 기록되고 진단 결과에 표시됩니다. 플러그인 엔진 등록에 실패하거나 선택한 엔진 ID를 찾을 수 없는 경우, OpenClaw는 자동으로 복구되지 않습니다. 플러그인을 수정하거나 contextEngine 설정을 다시 "legacy"로 바꿀 때까지 실행이 실패하게 됩니다.
개발 중에는 openclaw plugins install -l ./my-engine을 사용해 복사 없이 로컬 플러그인 디렉토리를 연결해 보세요.

더 자세한 내용은 Compaction, Context, Plugins, Plugin manifest 문서를 참고해 주세요.

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.