上下文引擎

上下文引擎控制 OpenClaw 如何为每次运行构建模型上下文：包含哪些消息、如何总结较早的历史记录，以及如何跨子智能体边界管理上下文。

OpenClaw 内置 legacy 引擎并默认使用它。仅当需要不同的组装、压缩或跨会话回忆行为时，才安装并选择插件引擎。

快速开始

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", // 必须与插件注册的引擎 id 匹配    },    entries: {      "lossless-claw": {        enabled: true,        // 在此填写插件特有的配置（请参阅插件文档）      },    },  },}

工作原理

每当 OpenClaw 运行模型提示词时，上下文引擎都会参与四个生命周期阶段：

引擎还可以实现可选的 maintain() 方法，用于在引导启动、轮次成功完成或压缩后维护对话记录（通过 runtimeContext.rewriteTranscriptEntries() 安全重写）。设置 info.turnMaintenanceMode: "background" 可将其作为延迟任务运行，而不是阻塞回复。

对于内置的非 ACP Codex harness，OpenClaw 通过将组装后的上下文投影到 Codex 开发者指令和当前轮次提示词中，应用相同的生命周期。Codex 仍负责管理其原生线程历史记录和原生压缩器。

子智能体生命周期（可选）

OpenClaw 会调用两个可选的子智能体生命周期钩子：

系统提示词附加内容

assemble 方法可以返回 systemPromptAddition 字符串。OpenClaw 会将其添加到本次运行的系统提示词之前。这样，引擎无需静态工作区文件，即可注入动态回忆指导、检索指令或上下文感知提示。

旧版引擎

内置的 legacy 引擎保留 OpenClaw 的原始行为：

• 摄取：不执行任何操作（会话管理器直接处理消息持久化）。
• 组装：直接传递（运行时中现有的清理 → 验证 → 限制流水线负责上下文组装）。
• 压缩：委托给内置的总结压缩机制，该机制会为较早的消息生成一份摘要，并完整保留近期消息。
• 轮次结束后：不执行任何操作。

旧版引擎不会注册工具，也不提供 systemPromptAddition。

未设置 plugins.slots.contextEngine（或将其设置为 "legacy"）时，会自动使用此引擎。

插件引擎

插件可以使用插件 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,          agentSessionKey: sessionKey,        }),      };    },     async compact({ sessionId, force }) {      // 总结较早的上下文      return { ok: true, compacted: true };    },  }));}

工厂 ctx 包含可选的 config、agentDir 和 workspaceDir 值，使插件能够在首次调用生命周期钩子前初始化每个智能体或每个工作区的状态。在调用非旧版的 assemble() 前，宿主会完成已注册的异步记忆提示词准备。同步的 buildMemorySystemPromptAddition(...) 辅助函数会读取该不可变的运行快照；请原样传递所提供的工具、引用、智能体和会话上下文。

然后在配置中启用它：

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

ContextEngine 接口

必需成员：

assemble 返回一个 AssembleResult，其中包含：

compact 返回一个 CompactResult。当压缩更改活动会话标识时，result.sessionTarget（携带会话标识和存储作用域的类型化 ContextEngineSessionTarget）会标识下一次重试或轮次必须使用的后继会话；result.sessionId 对应后继会话 id。

可选成员：

运行时设置

在 OpenClaw 内运行的生命周期钩子会接收一个可选的 runtimeSettings 对象。它是一个带版本号的只读内部生产者/消费者 API 表面：OpenClaw 为所选上下文引擎生成该对象，上下文引擎则在生命周期钩子中使用它。它不会直接呈现给用户，也不会创建专用的报告界面。

• schemaVersion：当前为 1
• runtime：OpenClaw 主机、运行时模式（normal、fallback 或 degraded），以及可选的 harness/运行时 ID
• contextEngineSelection：所选上下文引擎 ID 和选择来源
• executionHost：调用该钩子的界面对应的主机 ID 和标签
• model：请求的模型、解析后的模型、提供商，以及可选的模型系列
• limits：已知时的提示词 token 预算和最大输出 token 数
• 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 将所选插件引擎与核心回复路径隔离。如果非旧版引擎缺失、 未通过契约验证、在创建工厂时抛出异常，或从生命周期方法中抛出异常， OpenClaw 会在当前 Gateway 网关进程中隔离该引擎，并将上下文引擎工作 降级到内置的 legacy 引擎。系统会连同失败的操作记录该错误， 以便操作员修复、更新或禁用插件，而不会导致智能体无响应。

主机要求失败则有所不同：当引擎声明某个运行时缺少必需能力时， OpenClaw 会在开始运行前执行封闭式失败。这样可以保护那些在不受支持的主机中运行时 会破坏状态的引擎。

ownsCompaction

ownsCompaction 控制 OpenClaw 运行时内置的单次尝试内自动压缩功能是否在该次运行中保持启用：

这意味着插件有两种有效模式：

对于活动的非自主管理引擎，无操作的 compact() 并不安全，因为它会禁用该引擎槽位的正常 /compact 和溢出恢复压缩路径。

配置参考

{  plugins: {    slots: {      // 选择活动的上下文引擎。默认值："legacy"。      // 设置为插件 ID 以使用插件引擎。      contextEngine: "legacy",    },  },}

与压缩和记忆的关系

提示

• 使用 openclaw doctor 验证引擎是否正确加载。
• 切换引擎时，现有会话会继续保留其当前历史记录。新引擎将接管后续运行。
• 系统会记录引擎错误，并在当前 Gateway 网关进程中隔离所选插件引擎。OpenClaw 会在用户轮次中回退到 legacy，以便继续回复，但你仍应修复、更新、禁用或卸载损坏的插件。
• 在开发过程中，使用 openclaw plugins install -l ./my-engine 链接本地插件目录，无需复制。

相关内容

• 压缩 - 对长对话进行摘要
• 上下文 - 如何为智能体轮次构建上下文
• 插件架构 - 注册上下文引擎插件
• 插件清单 - 插件清单字段
• 插件 - 插件概览