컨텍스트 엔진

context engine은 각 실행에서 OpenClaw가 모델 컨텍스트를 구성하는 방식을 제어합니다. 포함할 메시지, 이전 기록을 요약하는 방식, subagent 경계 전반에서 컨텍스트를 관리하는 방식을 결정합니다.

OpenClaw에는 기본 제공 legacy 엔진이 포함되어 있으며 기본적으로 이를 사용합니다. 대부분의 사용자는 이를 변경할 필요가 없습니다. 다른 조립, Compaction 또는 세션 간 회상 동작이 필요할 때만 Plugin 엔진을 설치하고 선택하세요.

# 빠른 시작

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

openclaw plugins install @martian-engineering/lossless-claw

openclaw plugins install -l ./my-context-engine

// openclaw.json
{
  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)
      },
    },
  },
}

# 작동 방식

OpenClaw가 모델 프롬프트를 실행할 때마다 컨텍스트 엔진은 네 가지 수명 주기 지점에 참여합니다.

번들로 제공되는 비 ACP Codex 하네스의 경우, OpenClaw는 조립된 컨텍스트를 Codex 개발자 지침과 현재 턴 프롬프트에 투영하여 동일한 수명 주기를 적용합니다. Codex는 여전히 자체 네이티브 스레드 기록과 네이티브 컴팩터를 소유합니다.

# Subagent 수명 주기(선택 사항)

OpenClaw는 두 가지 선택적 subagent 수명 주기 훅을 호출합니다.

# 시스템 프롬프트 추가

assemble 메서드는 systemPromptAddition 문자열을 반환할 수 있습니다. OpenClaw는 이를 해당 실행의 시스템 프롬프트 앞에 붙입니다. 이를 통해 엔진은 정적 workspace 파일 없이도 동적 회상 가이드, 검색 지침 또는 컨텍스트 인식 힌트를 삽입할 수 있습니다.

# legacy 엔진

기본 제공 legacy 엔진은 OpenClaw의 원래 동작을 보존합니다.

• 수집: no-op입니다. 세션 관리자가 메시지 지속성을 직접 처리합니다.
• 조립: pass-through입니다. 런타임의 기존 sanitize → validate → limit 파이프라인이 컨텍스트 조립을 처리합니다.
• 압축: 기본 제공 요약 Compaction에 위임합니다. 이는 이전 메시지의 단일 요약을 만들고 최근 메시지는 그대로 유지합니다.
• 턴 이후: no-op입니다.

legacy 엔진은 도구를 등록하거나 systemPromptAddition을 제공하지 않습니다.

plugins.slots.contextEngine이 설정되어 있지 않거나 "legacy"로 설정되어 있으면 이 엔진이 자동으로 사용됩니다.

# Plugin 엔진

Plugin은 Plugin API를 사용해 컨텍스트 엔진을 등록할 수 있습니다.

export default function register(api) {
  api.registerContextEngine("my-engine", (ctx) => ({
    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, availableTools, citationsMode }) {
      // Return messages that fit the budget
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },

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

팩터리 ctx에는 선택적 config, agentDir, workspaceDir 값이 포함되어 있어 Plugin이 첫 번째 수명 주기 훅이 실행되기 전에 agent별 또는 workspace별 상태를 초기화할 수 있습니다.

그런 다음 구성에서 활성화하세요.

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

# ContextEngine 인터페이스

필수 멤버:

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

compact는 CompactResult를 반환합니다. Compaction이 활성 transcript를 회전시키면 result.sessionId와 result.sessionFile은 다음 재시도 또는 턴에서 사용해야 할 후속 세션을 식별합니다.

선택적 멤버:

# ownsCompaction

ownsCompaction은 해당 실행에서 Pi의 기본 제공 시도 중 자동 Compaction이 계속 활성화되는지를 제어합니다.

즉, 유효한 Plugin 패턴은 두 가지입니다.

no-op compact()는 활성 비소유 엔진에 안전하지 않습니다. 해당 엔진 slot의 일반 /compact 및 overflow 복구 Compaction 경로를 비활성화하기 때문입니다.

# 구성 참조

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

# Compaction 및 memory와의 관계

# 팁

• 엔진이 올바르게 로드되는지 확인하려면 openclaw doctor를 사용하세요.
• 엔진을 전환해도 기존 세션은 현재 기록으로 계속 진행됩니다. 새 엔진은 향후 실행부터 담당합니다.
• 엔진 오류는 기록되고 진단에 표시됩니다. Plugin 엔진 등록에 실패하거나 선택한 엔진 ID를 확인할 수 없으면 OpenClaw는 자동으로 대체 동작으로 전환하지 않습니다. Plugin을 수정하거나 plugins.slots.contextEngine을 "legacy"로 되돌릴 때까지 실행이 실패합니다.
• 개발 중에는 openclaw plugins install -l ./my-engine를 사용해 로컬 Plugin 디렉터리를 복사하지 않고 연결하세요.

# 관련 항목

• Compaction - 긴 대화 요약
• 컨텍스트 - 에이전트 턴에 맞게 컨텍스트가 구성되는 방식
• Plugin 아키텍처 - 컨텍스트 엔진 Plugin 등록
• Plugin 매니페스트 - Plugin 매니페스트 필드
• Plugin - Plugin 개요