上下文引擎

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.

OpenClaw ships with a built-in legacy engine and uses it by default - most users never need to change this. Install and select a plugin engine only when you want different assembly, compaction, or cross-session recall behavior.

# Quick start

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

# How it works

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

For the bundled non-ACP Codex harness, OpenClaw applies the same lifecycle by projecting assembled context into Codex developer instructions and the current turn prompt. Codex still owns its native thread history and native compactor.

# 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.

The legacy engine does not register tools or provide a systemPromptAddition.

When no plugins.slots.contextEngine is set (or it's set to "legacy"), this engine is used automatically.

# Plugin engines

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

The factory ctx includes optional config, agentDir, and workspaceDir values so plugins can initialize per-agent or per-workspace state before the first lifecycle hook runs.

Then enable it in config:

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

# The ContextEngine interface

Required members:

assemble returns an AssembleResult with:

compact returns a CompactResult. When compaction rotates the active transcript, result.sessionId and result.sessionFile identify the successor session that the next retry or turn must use.

Optional members:

# ownsCompaction

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

That means there are two valid plugin patterns:

A no-op compact() is unsafe for an active non-owning engine because it disables the normal /compact and overflow-recovery compaction path for that engine slot.

# 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

# 提示

• 使用 openclaw doctor 驗證你的引擎是否正確載入。
• 如果切換引擎，現有工作階段會繼續使用其目前的歷史記錄。新引擎會接管未來的執行。
• 引擎錯誤會被記錄並顯示在診斷資訊中。如果 Plugin 引擎無法註冊，或所選的引擎 ID 無法解析，OpenClaw 不會自動回退；執行會失敗，直到你修正 Plugin 或將 plugins.slots.contextEngine 切回 "legacy"。
• 開發時，使用 openclaw plugins install -l ./my-engine 連結本機 Plugin 目錄，而無需複製。

# 相關

• Compaction - 摘要長篇對話
• 內容 - 如何為代理回合建立內容
• Plugin 架構 - 註冊內容引擎 Plugin
• Plugin manifest - Plugin manifest 欄位
• Plugins - Plugin 概觀