上下文引擎

上下文引擎控制 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 引擎

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

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

legacy 引擎不会注册工具，也不提供 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,          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),          agentSessionKey: sessionKey,        }),      };    },     async compact({ sessionId, force }) {      // 总结较早的上下文      return { ok: true, compacted: true };    },  }));}

工厂函数的 ctx 包含可选的 config、agentDir 和 workspaceDir 值，以便插件在第一个生命周期钩子运行前初始化每个智能体或每个工作区的状态。

然后在配置中启用它：

{  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 链接本地插件目录，而无需复制。

相关内容

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