上下文引擎

概述

上下文引擎控制 OpenClaw 如何为每次运行构建模型上下文：包含哪些消息、如何摘要旧历史、如何跨子 Agent 管理上下文。默认使用内置 legacy 引擎，大多数用户无需更改。

核心要点

四个生命周期钩子：

Ingest：新消息加入 Session 时调用，引擎可存储/索引消息
Assemble：每次模型运行前调用，返回适合 token 预算的有序消息集合
Compact：上下文窗口满或用户执行 /compact 时调用，摘要旧历史
After turn：运行完成后调用，可持久化状态或触发后台压缩

Assemble 返回值：

messages：发给模型的有序消息
estimatedTokens：引擎估算的 token 数（用于压缩阈值决策）
systemPromptAddition：前置到系统提示的动态内容（可选）

ownsCompaction 标志：

true：引擎自己负责压缩，OpenClaw 禁用 PI 内置自动压缩
false：PI 内置自动压缩仍可运行，但 /compact 和溢出恢复仍调用引擎的 compact()

Legacy 引擎行为：

Ingest/After turn：无操作
Assemble：直通（由运行时的 sanitize → validate → limit 管道处理）
Compact：委托给内置摘要压缩

插件引擎注册：

api.registerContextEngine("my-engine", (ctx) => ({
  info: { id: "my-engine", ownsCompaction: true },
  async ingest({ sessionId, message }) { ... },
  async assemble({ sessionId, messages, tokenBudget }) { ... },
  async compact({ sessionId, force }) { ... }
}));

注意：插件卸载时，plugins.slots.contextEngine 自动重置为 legacy。

配置/使用

{
  plugins: {
    slots: {
      contextEngine: "lossless-claw"  // 或 "legacy"（默认）
    },
    entries: {
      "lossless-claw": { enabled: true }
    }
  }
}

安装插件引擎：

openclaw plugins install @martian-engineering/lossless-claw

相关页面

context — 上下文概念与诊断
memory — 记忆插件与上下文引擎的关系
agent-loop — 上下文引擎在执行循环中的位置