컨텍스트 엔진

컨텍스트 엔진은 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", // 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는 여전히 자체 네이티브 스레드 기록과 네이티브 compactor를 소유합니다.

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

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

시스템 프롬프트 추가

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

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이 첫 번째 수명 주기 훅이 실행되기 전에 에이전트별 또는 작업 공간별 상태를 초기화할 수 있습니다.

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

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

ContextEngine 인터페이스

필수 멤버:

assemble은 다음이 포함된 AssembleResult를 반환합니다.

compact는 CompactResult를 반환합니다. compaction이 활성 트랜스크립트를 회전하면, result.sessionId와 result.sessionFile은 다음 재시도 또는 턴이 사용해야 하는 후속 세션을 식별합니다.

선택적 멤버:

런타임 설정

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

• schemaVersion: 현재 1
• runtime: OpenClaw 호스트, 런타임 모드(normal, fallback 또는 degraded), 선택적 하니스/런타임 ID
• contextEngineSelection: 선택된 컨텍스트 엔진 ID 및 선택 소스
• executionHost: 훅을 호출하는 표면의 호스트 ID 및 레이블
• model: 요청된 모델, 확인된 모델, 공급자, 선택적 모델 패밀리
• limits: 알려진 경우 프롬프트 토큰 예산 및 최대 출력 토큰
• diagnostics: 알려진 경우 닫힌 fallback 및 degraded 사유 코드

알 수 없는 필드는 null로 표현됩니다. 런타임 모드와 선택 소스 같은 판별자 필드는 null을 허용하지 않습니다. 이전 엔진은 계속 호환됩니다. 엄격한 legacy 엔진이 알 수 없는 속성이라는 이유로 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:        "Use the native Codex or OpenClaw embedded runtime, or select the legacy context engine.",    },  },}

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

실패 격리

OpenClaw는 선택된 Plugin 엔진을 핵심 응답 경로에서 격리합니다. 레거시가 아닌 엔진이 누락되었거나, 계약 검증에 실패했거나, 팩토리 생성 중 예외를 던지거나, 수명 주기 메서드에서 예외를 던지면, OpenClaw는 현재 Gateway 프로세스에서 해당 엔진을 격리하고 컨텍스트 엔진 작업을 내장 legacy 엔진으로 다운그레이드합니다. 오류는 실패한 작업과 함께 기록되므로 운영자는 에이전트가 응답을 멈추지 않게 하면서 Plugin을 복구, 업데이트 또는 비활성화할 수 있습니다.

호스트 요구 사항 실패는 다릅니다. 엔진이 런타임에 필요한 기능이 없다고 선언하면 OpenClaw는 실행을 시작하기 전에 폐쇄형으로 실패합니다. 이렇게 하면 지원되지 않는 호스트에서 실행될 경우 상태를 손상시킬 수 있는 엔진을 보호할 수 있습니다.

ownsCompaction

ownsCompaction은 실행 중 OpenClaw 런타임의 내장 시도 내 자동 Compaction을 계속 활성화할지 여부를 제어합니다.

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

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

구성 참조

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

Compaction 및 메모리와의 관계

팁

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

관련 항목

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