컨텍스트 엔진

컨텍스트 엔진은 OpenClaw가 각 실행의 모델 컨텍스트를 구성하는 방식을 제어합니다. 여기에는 포함할 메시지, 이전 기록을 요약하는 방법, 하위 에이전트 경계 간에 컨텍스트를 관리하는 방법이 포함됩니다.

OpenClaw에는 기본 제공 legacy 엔진이 포함되어 있으며 기본적으로 이 엔진을 사용합니다. 다른 구성, Compaction 또는 세션 간 회상 동작이 필요한 경우에만 Plugin 엔진을 설치하고 선택하십시오.

빠른 시작

openclaw doctor# 또는 구성을 직접 확인합니다: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", // Plugin에 등록된 엔진 ID와 일치해야 합니다    },    entries: {      "lossless-claw": {        enabled: true,        // Plugin별 구성은 여기에 입력합니다(Plugin 문서 참조)      },    },  },}

작동 방식

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

엔진은 부트스트랩, 성공적인 턴 또는 Compaction 이후 트랜스크립트 유지 관리(runtimeContext.rewriteTranscriptEntries()를 통한 안전한 재작성)를 위해 선택적 maintain() 메서드도 구현할 수 있습니다. 응답을 차단하지 않고 지연된 작업으로 실행하려면 info.turnMaintenanceMode: "background"를 설정하십시오.

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

하위 에이전트 수명 주기(선택 사항)

OpenClaw는 다음 두 가지 선택적 하위 에이전트 수명 주기 훅을 호출합니다.

시스템 프롬프트 추가 내용

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

legacy 엔진

기본 제공 legacy 엔진은 OpenClaw의 기존 동작을 유지합니다.

• 수집: 아무 작업도 하지 않습니다(세션 관리자가 메시지 영구 저장을 직접 처리합니다).
• 구성: 그대로 전달합니다(런타임의 기존 정리 → 검증 → 제한 파이프라인이 컨텍스트 구성을 처리합니다).
• Compaction: 기본 제공 요약 Compaction에 위임합니다. 이 기능은 이전 메시지를 하나의 요약으로 만들고 최근 메시지는 그대로 유지합니다.
• 턴 이후: 아무 작업도 하지 않습니다.

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 }) {      // 메시지를 데이터 저장소에 저장합니다      return { ingested: true };    },     async assemble({      sessionId,      sessionKey,      messages,      tokenBudget,      availableTools,      citationsMode,    }) {      // 예산에 맞는 메시지를 반환합니다      return {        messages: buildContext(messages, tokenBudget),        estimatedTokens: countTokens(messages),        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),          agentSessionKey: sessionKey,        }),      };    },     async compact({ sessionId, force }) {      // 이전 컨텍스트를 요약합니다      return { ok: true, compacted: true };    },  }));}

팩토리 ctx에는 선택적 config, agentDir, workspaceDir 값이 포함되므로 Plugin은 첫 번째 수명 주기 훅이 실행되기 전에 에이전트별 또는 작업 공간별 상태를 초기화할 수 있습니다.

그런 다음 구성에서 활성화하십시오.

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

ContextEngine 인터페이스

필수 멤버:

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

compact는 CompactResult를 반환합니다. Compaction이 활성 세션 ID를 변경하는 경우 result.sessionTarget(세션 ID와 저장소 범위를 전달하는 형식 지정된 ContextEngineSessionTarget)은 다음 재시도 또는 턴에서 사용해야 하는 후속 세션을 식별하며, result.sessionId는 후속 세션 ID를 반영합니다.

선택적 멤버:

런타임 설정

OpenClaw 내부에서 실행되는 수명 주기 훅은 선택적 runtimeSettings 객체를 받습니다. 이는 버전이 지정된 읽기 전용 내부 생산자/소비자 API 표면입니다. OpenClaw가 선택된 컨텍스트 엔진을 위해 이를 생성하고, 컨텍스트 엔진은 수명 주기 훅 내부에서 이를 소비합니다. 사용자에게 직접 렌더링되지 않으며 전용 보고 표면을 만들지 않습니다.

• schemaVersion: 현재 1
• runtime: OpenClaw 호스트, 런타임 모드(normal, fallback 또는 degraded) 및 선택적 하네스/런타임 ID
• contextEngineSelection: 선택된 컨텍스트 엔진 ID와 선택 출처
• executionHost: 훅을 호출하는 표면의 호스트 ID와 레이블
• model: 요청된 모델, 확인된 모델, 제공자 및 선택적 모델 계열
• limits: 알려진 경우 프롬프트 토큰 예산과 최대 출력 토큰 수
• diagnostics: 알려진 경우 닫힌 폴백 및 성능 저하 이유 코드

알 수 없는 필드는 null로 표현되며, 런타임 모드 및 선택 소스와 같은 판별자 필드는 null을 허용하지 않습니다. 이전 엔진도 계속 호환됩니다. 엄격한 레거시 엔진이 runtimeSettings를 알 수 없는 속성으로 거부하면 OpenClaw는 엔진을 격리하는 대신 해당 속성을 제외하고 수명 주기 호출을 재시도합니다.

호스트 요구 사항

컨텍스트 엔진은 info.hostRequirements에 호스트 기능 요구 사항을 선언할 수 있습니다. OpenClaw는 작업을 시작하기 전에 이러한 요구 사항을 확인하고, 선택한 런타임이 이를 충족할 수 없으면 설명이 포함된 오류와 함께 안전하게 실패합니다.

에이전트 실행에서 엔진이 assemble()을 통해 실제 모델 프롬프트를 제어해야 하는 경우 assemble-before-prompt를 선언하십시오.

info: {  id: "my-context-engine",  name: "My Context Engine",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "네이티브 Codex 또는 OpenClaw 임베디드 런타임을 사용하거나 레거시 컨텍스트 엔진을 선택하십시오.",    },  },}

네이티브 Codex 및 OpenClaw 임베디드 에이전트 실행은 assemble-before-prompt를 충족합니다. 일반 CLI 백엔드는 이를 충족하지 않으므로, 이 기능이 필요한 엔진은 CLI 프로세스가 시작되기 전에 거부됩니다.

장애 격리

OpenClaw는 선택한 Plugin 엔진을 핵심 응답 경로에서 격리합니다. 비레거시 엔진이 없거나, 계약 검증에 실패하거나, 팩토리 생성 중 예외를 발생시키거나, 수명 주기 메서드에서 예외를 발생시키면 OpenClaw는 현재 Gateway 프로세스에서 해당 엔진을 격리하고 컨텍스트 엔진 작업을 기본 제공 legacy 엔진으로 다운그레이드합니다. 운영자가 에이전트의 응답이 중단되지 않은 상태에서 Plugin을 복구, 업데이트 또는 비활성화할 수 있도록 실패한 작업과 함께 오류가 기록됩니다.

호스트 요구 사항 실패는 다르게 처리됩니다. 엔진이 런타임에 필수 기능이 없다고 선언하면 OpenClaw는 실행을 시작하기 전에 안전하게 실패합니다. 이렇게 하면 지원되지 않는 호스트에서 실행될 경우 상태를 손상시킬 수 있는 엔진을 보호합니다.

ownsCompaction

ownsCompaction은 OpenClaw 런타임에 기본 제공되는 시도 중 자동 Compaction을 해당 실행에서 계속 활성화할지 제어합니다.

따라서 다음과 같은 두 가지 유효한 Plugin 패턴이 있습니다.

아무 작업도 수행하지 않는 compact()는 활성 비소유 엔진에 안전하지 않습니다. 해당 엔진 슬롯의 일반적인 /compact 및 오버플로 복구 Compaction 경로가 비활성화되기 때문입니다.

구성 참조

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

Compaction 및 메모리와의 관계

팁

• 엔진이 올바르게 로드되는지 확인하려면 openclaw doctor를 사용하십시오.
• 엔진을 전환해도 기존 세션은 현재 기록으로 계속 진행됩니다. 새 엔진은 이후 실행부터 적용됩니다.
• 엔진 오류가 기록되고 선택한 Plugin 엔진은 현재 Gateway 프로세스에서 격리됩니다. 응답이 계속될 수 있도록 OpenClaw는 사용자 턴에 legacy를 대체 엔진으로 사용하지만, 손상된 Plugin을 복구, 업데이트, 비활성화 또는 제거해야 합니다.
• 개발 시 로컬 Plugin 디렉터리를 복사하지 않고 연결하려면 openclaw plugins install -l ./my-engine을 사용하십시오.

관련 항목

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