OpenClaw 3.7 ContextEngine 插件接口源码拆解：AI Agent 上下文管理

问题不在于触发方式不够多，而在于——你无法通过插件替换这些策略。想自定义'什么时候该压缩'的判断逻辑？只能改核心代码。

2.4 痛点总结

三、ContextEngine 的核心思路：把'做什么'和'怎么做'分开

OpenClaw 3.7 的 ContextEngine 接口（PR #22201，44 个文件改动），解决方案其实很经典——定义一组接口，让核心运行时只关心'要做什么'，具体'怎么做'交给可替换的引擎。

翻译成人话：以后换个上下文处理算法，像换插件一样简单。

3.1 七个生命周期钩子

ContextEngine 定义了 7 个钩子，覆盖了上下文的完整生命周期：

会话开始 → ① bootstrap() — 初始化引擎状态 → ② ingest() — 每条消息摄入 → ③ assemble() — 组装模型上下文 → 调用模型 → ④ afterTurn() — 回合后处理 → ⑤ compact() — 需要压缩时执行
子 Agent 场景： → ⑥ prepareSubagentSpawn() — 准备子 Agent 上下文 → ⑦ onSubagentEnded() — 清理子 Agent 上下文

3.2 接口定义（精简版）

interface ContextEngine {
    readonly info: ContextEngineInfo;
    // 3 个必选 = 上下文管理的三件核心事
    ingest(params: { sessionId, message }): Promise<IngestResult>;
    assemble(params: { sessionId, messages, tokenBudget? }): Promise<AssembleResult>;
    compact(params: { sessionId, sessionFile, tokenBudget?, ... }): Promise<CompactResult>;
    // 4 个可选 = 增强能力
    bootstrap?(params): Promise<BootstrapResult>;
    afterTurn?(params): Promise<void>;
    prepareSubagentSpawn?(params): Promise<SubagentSpawnPreparation | undefined>;
    onSubagentEnded?(params): Promise<void>;
}

3 个必选方法覆盖了上下文管理最本质的三件事：消息怎么存、上下文怎么组、太多了怎么压。4 个可选方法提供增强能力，不实现也不影响基本运转。

四、向后兼容的艺术：LegacyContextEngine 与绞杀者模式

引入新接口最怕什么？Breaking change。

OpenClaw 用了一个经典的架构模式——Strangler Fig（绞杀者模式）：在旧系统外面包一层新接口，旧逻辑原封不动跑在新接口里。

LegacyContextEngine 就是这个包装器：

结果：不配置任何 context engine 插件时，系统行为和升级前 100% 一致。零风险升级。

五、注册与解析机制：怎么做到'换插件一样简单'？

5.1 进程全局注册表

// 通过 Symbol.for() 挂在 globalThis 上
// 为什么？monorepo 构建可能把模块打包成多份拷贝
// Symbol.for() 确保不管有几份 js 文件，注册表只有一个
const REGISTRY = Symbol.for("openclaw.contextEngineRegistryState");
registerContextEngine(id, factory);
getContextEngineFactory(id);
listContextEngineIds();

5.2 Slot 机制

{
  "memory": "memory-core",
  "contextEngine": "legacy"
}

一个坑位只能站一个人。两个插件都声明 kind: "context-engine"，只有被配置选中的那个加载。

5.3 一行配置搞定切换

{
  "plugins": {
    "slots": {
      "contextEngine": "lossless-claw"
    }
  }
}

不配这一行 → 默认 "legacy" → 行为不变。

这就是'像换插件一样简单'的实现原理。

六、实战：10 分钟写一个自定义 Context Engine

这不是空谈，看代码：

export default function register(api) {
    api.registerContextEngine("my-rag-context", () => ({
        info: {
            id: "my-rag-context",
            name: "RAG Context",
            ownsCompaction: true
        },
        async ingest({ sessionId, message }) {
            // 每条消息写入向量数据库
            await vectorDb.insert(sessionId, message);
            return { ingested: true };
        },
        async assemble({ sessionId, messages, tokenBudget }) {
            // 不是暴力截断，而是 RAG 检索最相关的历史消息
            const relevant = await vectorDb.search(sessionId, latestQuery, tokenBudget);
            return { messages: relevant, estimatedTokens: countTokens(relevant) };
        },
        async compact({ sessionId }) {
            // RAG 模式下不需要压缩——assemble 时按需检索
            return { ok: true, compacted: false };
        },
    }));
}

三个核心方法，加起来不到 20 行。但效果是什么？你把上下文管理从'暴力截断'变成了'语义检索'，而且没有改动 OpenClaw 的任何核心代码。

七、ContextEngine ≠ 记忆系统，别搞混了

很多人会混淆这两个概念。简单区分：

它们之间的桥梁是 Memory Flush——在 ContextEngine 执行压缩之前，先触发一个静默 Agent 回合，提醒 Agent 把值得保留的对话内容写入记忆文件。

上下文管理决定'模型这次能看到什么'，记忆系统决定'Agent 下周还记得什么'。两者协同但独立。

八、从 ContextEngine 学到的架构思维

不管你用不用 OpenClaw，这次的 ContextEngine 设计有几个通用的工程模式值得带走：

8.1 绞杀者模式（Strangler Fig）

新接口包装旧逻辑，渐进式替换。不一口气重写，而是让新旧共存，逐步迁移。这在任何大型系统的重构中都适用。

8.2 接口 + 注册表 + 配置驱动

定义接口 → 工厂函数注册到全局注册表 → 配置文件选择用哪个引擎 → 运行时动态解析。这套模式在 Java 的 SPI、Python 的 entry_points、Rust 的 trait 中都有对应。

8.3 Best-effort 回调

子 Agent 生命周期回调失败只记日志不阻断主流程。在分布式系统中，'让非关键路径的失败不影响主路径'是基本原则。

8.4 必选 + 可选方法分离

3 个必选方法保证核心能力，4 个可选方法扩展增强能力。实现者可以从最简开始，逐步增加功能。

九、行业背景与对比

当前开源社区对主流 AI Agent 框架的记忆系统进行了广泛分析，涵盖了多种设计哲学：

从 2 个 Markdown 文件到 10 种存储后端、从暴力截断到 9 阶段检索管线——4 种完全不同的设计哲学，让你一次看透 AI Agent 记忆系统的全貌。

适合以下人群参考：

• 正在构建 AI Agent 的工程师：直接参考已经验证过的架构
• 想理解'记忆'到底怎么实现的研究者：源码级拆解，不是概念堆砌
• 想在 LangGraph / LangChain / 自研框架中做上下文管理的开发者：每个框架都有复刻指南

十、总结

OpenClaw 3.7 的 ContextEngine 接口，核心价值用一句话概括：

以后换个上下文处理算法，像换插件一样简单，不用再担心改一处崩全程。

它不是一个'多了个功能'的小更新，而是一次架构层面的升级——把 AI Agent 中最头疼的上下文管理问题，从'硬编码在核心代码里'变成了'可插拔的标准接口'。

7 个生命周期钩子、绞杀者模式的向后兼容、全局注册表 + Slot 机制的引擎管理——这些设计模式不仅适用于 OpenClaw，同样适用于你正在做的任何 AI Agent 系统。

不论你用什么技术栈，上下文管理的核心问题是一样的。理解它、借鉴它、在你的项目中用好它。