OpenClaw 的 Context Engine（上下文引擎）是一个可插拔的上下文组装系统，决定每次调用模型时，哪些消息会被包含进去、旧的历史如何被摘要、以及子代理边界之间的上下文如何管理。本文基于官方文档详解其工作原理和插件化架构。
快速了解当前引擎
openclaw doctor
# 或者直接查看配置：
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'OpenClaw 内置了一个 legacy 引擎，同时插件可以注册替代引擎来接管整个上下文引擎生命周期。
四个生命周期钩子
每次 OpenClaw 运行一次模型调用，Context Engine 会在四个关键节点参与：
1. Ingest（摄入）
新消息加入会话时调用。引擎可以把这条消息存储或
索引到自己的数据存储中
2. Assemble（组装）
每次模型运行之前调用。引擎返回一组符合 token 预算的、
有序排列的消息（可选附带 systemPromptAddition）
3. Compact（压缩）
上下文窗口填满时调用，或者用户手动执行 /compact 时调用。
引擎负责把旧的历史摘要化，腾出空间
4. After turn（轮次结束后）
一次运行完成后调用。引擎可以持久化状态、
触发后台压缩，或更新索引
这四个钩子覆盖了一次模型交互从"消息进来"到"交互结束"的完整链路，理解这个生命周期，是理解 OpenClaw 如何管理上下文窗口这个稀缺资源的关键。
可选的子代理生命周期钩子
目前 OpenClaw 只调用一个子代理生命周期钩子：
onSubagentEnded — 当子代理会话完成或被清理时执行清理操作
prepareSubagentSpawn 钩子已经是接口的一部分（为未来使用预留），
但当前运行时尚未调用它
systemPromptAddition：动态注入上下文的关键机制
assemble 方法可以返回一个 systemPromptAddition 字符串，OpenClaw 会把它前置拼接到当次运行的系统提示词中。这个机制让引擎能够动态注入召回指引、检索指令，或者具备上下文感知能力的提示——而不需要依赖静态的工作区文件。
这一点值得展开理解——普通的 AGENTS.md/SOUL.md 这类文件是每次会话都固定注入的静态内容，而 systemPromptAddition 提供的是运行时动态生成的补充内容，可以根据当前会话的具体情况（比如检索到的相关历史记忆）实时变化。
如何安装一个 Context Engine 插件
# 从 npm 安装
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,
// 插件特定配置写在这里（参考插件自己的文档）
},
},
},
}配置完成后需要重启 Gateway 才能生效。如果想切回内置引擎，把 contextEngine 设为 "legacy"，或者直接删除这个配置项——"legacy" 本来就是默认值。
为什么需要一个可插拔的上下文引擎
把这个设计放到实际使用场景里看，价值就很清楚了——不同用户对"上下文该怎么管理"的需求差异很大：有的人希望更激进的压缩策略以节省 token 成本，有的人希望接入向量检索让历史召回更精准，有的人可能需要针对特定领域数据做定制化的索引方式。把 Context Engine 做成可插拔的插件槽位，意味着这些差异化需求不需要 fork 整个 OpenClaw 代码库去改，而是可以作为独立插件开发、分发、按需启用。
实战建议
1. 先用 openclaw doctor 确认当前生效的是哪个引擎，
避免配置了插件却忘记切换 contextEngine 槽位
2. 开发自己的 Context Engine 插件前，先吃透四个生命周期钩子
各自的调用时机，避免在错误的阶段做本该在别处做的事
3. 涉及压缩策略调整时，优先在测试环境验证 Compact 钩子
不会误删关键上下文信息
4. 切换引擎后记得重启 Gateway，配置不会热生效
总结
Context Engine 是 OpenClaw 架构中一个相对底层但决定性的组件——它直接决定了"模型这一轮到底看到了什么"，而这几乎是决定 Agent 表现好坏最核心的变量之一。理解 Ingest/Assemble/Compact/After turn 这四个钩子，对于想要深度定制 OpenClaw 上下文管理策略的开发者，是绕不开的第一课。
来源：Context Engine — OpenClaw 官方文档