Context engine

Context engine 문서는 OpenClaw 공식 문서(concepts/context-engine)를 한국어로 정리한 가이드입니다. Context engine: pluggable context assembly, compaction, and subagent lifecycle 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Context engine: pluggable context assembly, compaction, and subagent lifecycle

한국어 가이드 범위: concepts/context-engine 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

빠른 시작
동작 방식
Subagent lifecycle (optional)
System prompt addition
The legacy engine
Plugin engines
The ContextEngine interface
Runtime settings
Host requirements
Failure isolation
ownsCompaction
Configuration reference
Relationship to compaction and memory
Tips
관련 문서

상세 내용

본문

A context engine controls how OpenClaw builds model context for each run: which messages to include, how to summarize older history, and how to manage context across subagent boundaries.

빠른 시작

Context engine plugins are installed like any other OpenClaw 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)
          },
        },
      },
    }

동작 방식

Every time OpenClaw runs a model prompt, the context engine participates at four lifecycle points:

Subagent lifecycle (optional)

OpenClaw calls two optional subagent lifecycle hooks:

System prompt addition

The assemble method can return a systemPromptAddition string. OpenClaw prepends this to the system prompt for the run. This lets engines inject dynamic recall guidance, retrieval instructions, or context-aware hints without requiring static workspace files.

The legacy engine

The built-in legacy engine preserves OpenClaw's original behavior:

주요 항목:

Ingest: no-op (the session manager handles message persistence directly).
Assemble: pass-through (the existing sanitize → validate → limit pipeline in the runtime handles context assembly).
Compact: delegates to the built-in summarization compaction, which creates a single summary of older messages and keeps recent messages intact.
After turn: no-op.

Plugin engines

A plugin can register a context engine using the plugin 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,
      sessionKey,
      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,
          agentSessionKey: sessionKey,
        }),
      };
    },

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

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

The ContextEngine interface

assemble returns an AssembleResult with:

Member	Kind	Purpose
`info`	Property	Engine id, name, version, and whether it owns compaction
`ingest(params)`	Method	Store a single message
`assemble(params)`	Method	Build context for a model run (returns `AssembleResult`)
`compact(params)`	Method	Summarize/reduce context

Member	Kind	Purpose
`bootstrap(params)`	Method	Initialize engine state for a session. Called once when the engine first sees a session (e.g., import history).
`maintain(params)`	Method	Transcript maintenance after bootstrap, a successful turn, or compaction. Use `runtimeContext.rewriteTranscriptEntries()` for safe rewrites.
`ingestBatch(params)`	Method	Ingest a completed turn as a batch. Called after a run completes, with all messages from that turn at once.
`afterTurn(params)`	Method	Post-run lifecycle work (persist state, trigger background compaction).
`prepareSubagentSpawn(params)`	Method	Set up shared state for a child session before it starts.
`onSubagentEnded(params)`	Method	Clean up after a subagent ends.
`dispose()`	Method	Release resources. Called during gateway shutdown or plugin reload - not per-session.

Runtime settings

Lifecycle hooks that run inside OpenClaw receive an optional runtimeSettings object. It is a versioned, read-only internal producer/consumer API surface: OpenClaw produces it for the selected context engine, and the context engine consumes it inside lifecycle hooks. It is not rendered directly to users and does not create a dedicated reporting surface.

주요 항목:

schemaVersion: currently 1
runtime: OpenClaw host, runtime mode (normal, fallback, or
contextEngineSelection: selected context engine id and selection source
executionHost: host id and label for the surface invoking the hook
model: requested model, resolved model, provider, and optional model family
limits: prompt token budget and max output tokens when known
diagnostics: closed fallback and degraded reason codes when known

Host requirements

Context engines can declare host capability requirements on info.hostRequirements. OpenClaw checks these requirements before starting the operation and fails closed with a descriptive error when the selected runtime cannot satisfy them.

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.",
    },
  },
}

Failure isolation

OpenClaw isolates the selected plugin engine from the core reply path. If a non-legacy engine is missing, fails contract validation, throws during factory creation, or throws from a lifecycle method, OpenClaw quarantines that engine for the current Gateway process and downgrades context-engine work to the built-in legacy engine. The error is logged with the failed operation so the operator can repair, update, or disable the plugin without the agent going silent.

ownsCompaction

ownsCompaction controls whether OpenClaw runtime's built-in in-attempt auto-compaction stays enabled for the run:

Configuration reference

The slot is exclusive at run time - only one registered context engine is resolved for a given run or compaction operation. Other enabled kind: "context-engine" plugins can still load and run their registration code; plugins.slots.contextEngine only selects which registered engine id OpenClaw resolves when it needs a context engine.

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

Relationship to compaction and memory

Compaction is one responsibility of the context engine. The legacy engine delegates to OpenClaw's built-in summarization. Plugin engines can implement any compaction strategy (DAG summaries, vector retrieval, etc.).

Tips

주요 항목:

Use openclaw doctor to verify your engine is loading correctly.
If switching engines, existing sessions continue with their current history. The new engine takes over for future runs.
Engine errors are logged and the selected plugin engine is quarantined for the current Gateway process. OpenClaw falls back to legacy for user turns so replies can continue, but you should still repair, update, disable, or uninstall the broken plugin.
For development, use openclaw plugins install -l ./my-engine to link a local plugin directory without copying.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/context-engine
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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)
          },
        },
      },
    }

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,
      sessionKey,
      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,
          agentSessionKey: sessionKey,
        }),
      };
    },

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

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

Context engine

핵심 요약

Context engine: pluggable context assembly, compaction, and subagent lifecycle

한국어 가이드 범위: concepts/context-engine 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

빠른 시작
동작 방식
Subagent lifecycle (optional)
System prompt addition
The legacy engine
Plugin engines
The ContextEngine interface
Runtime settings
Host requirements
Failure isolation
ownsCompaction
Configuration reference
Relationship to compaction and memory
Tips
관련 문서

상세 내용

본문

A context engine controls how OpenClaw builds model context for each run: which messages to include, how to summarize older history, and how to manage context across subagent boundaries.

빠른 시작

Context engine plugins are installed like any other OpenClaw 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)
          },
        },
      },
    }

동작 방식

Every time OpenClaw runs a model prompt, the context engine participates at four lifecycle points:

Subagent lifecycle (optional)

OpenClaw calls two optional subagent lifecycle hooks:

System prompt addition

The legacy engine

The built-in legacy engine preserves OpenClaw's original behavior:

주요 항목:

Ingest: no-op (the session manager handles message persistence directly).
Assemble: pass-through (the existing sanitize → validate → limit pipeline in the runtime handles context assembly).
Compact: delegates to the built-in summarization compaction, which creates a single summary of older messages and keeps recent messages intact.
After turn: no-op.

Plugin engines

A plugin can register a context engine using the plugin 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,
      sessionKey,
      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,
          agentSessionKey: sessionKey,
        }),
      };
    },

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

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

The ContextEngine interface

assemble returns an AssembleResult with:

Member	Kind	Purpose
`info`	Property	Engine id, name, version, and whether it owns compaction
`ingest(params)`	Method	Store a single message
`assemble(params)`	Method	Build context for a model run (returns `AssembleResult`)
`compact(params)`	Method	Summarize/reduce context

Member	Kind	Purpose
`bootstrap(params)`	Method	Initialize engine state for a session. Called once when the engine first sees a session (e.g., import history).
`maintain(params)`	Method	Transcript maintenance after bootstrap, a successful turn, or compaction. Use `runtimeContext.rewriteTranscriptEntries()` for safe rewrites.
`ingestBatch(params)`	Method	Ingest a completed turn as a batch. Called after a run completes, with all messages from that turn at once.
`afterTurn(params)`	Method	Post-run lifecycle work (persist state, trigger background compaction).
`prepareSubagentSpawn(params)`	Method	Set up shared state for a child session before it starts.
`onSubagentEnded(params)`	Method	Clean up after a subagent ends.
`dispose()`	Method	Release resources. Called during gateway shutdown or plugin reload - not per-session.

Runtime settings

주요 항목:

schemaVersion: currently 1
runtime: OpenClaw host, runtime mode (normal, fallback, or
contextEngineSelection: selected context engine id and selection source
executionHost: host id and label for the surface invoking the hook
model: requested model, resolved model, provider, and optional model family
limits: prompt token budget and max output tokens when known
diagnostics: closed fallback and degraded reason codes when known

Host requirements

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.",
    },
  },
}

Failure isolation

ownsCompaction

ownsCompaction controls whether OpenClaw runtime's built-in in-attempt auto-compaction stays enabled for the run:

Configuration reference

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

Relationship to compaction and memory

Tips

주요 항목:

Use openclaw doctor to verify your engine is loading correctly.
If switching engines, existing sessions continue with their current history. The new engine takes over for future runs.
Engine errors are logged and the selected plugin engine is quarantined for the current Gateway process. OpenClaw falls back to legacy for user turns so replies can continue, but you should still repair, update, disable, or uninstall the broken plugin.
For development, use openclaw plugins install -l ./my-engine to link a local plugin directory without copying.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/context-engine
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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)
          },
        },
      },
    }

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,
      sessionKey,
      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,
          agentSessionKey: sessionKey,
        }),
      };
    },

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

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

Context engine

핵심 요약

문서 구성

상세 내용

본문

빠른 시작

동작 방식

Subagent lifecycle (optional)

System prompt addition

The legacy engine

Plugin engines

The ContextEngine interface

Runtime settings

Host requirements

Failure isolation

ownsCompaction

Configuration reference

Relationship to compaction and memory

Tips

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Context engine

핵심 요약

문서 구성

상세 내용

본문

빠른 시작

동작 방식

Subagent lifecycle (optional)

System prompt addition

The legacy engine

Plugin engines

The ContextEngine interface

Runtime settings

Host requirements

Failure isolation

ownsCompaction

Configuration reference

Relationship to compaction and memory

Tips

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드