上下文引擎

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

OpenClaw 内置 legacy 引擎并默认使用它 - 大多数用户无需更改此设置。只有当你需要不同的组装、压缩或跨会话召回行为时，才安装并选择插件引擎。

# 快速开始

openclaw doctor
# or inspect config directly:
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", // must match the plugin's registered engine id
    },
    entries: {
      "lossless-claw": {
        enabled: true,
        // Plugin-specific config goes here (see the plugin's docs)
      },
    },
  },
}

# 工作原理

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

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

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

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

# 系统提示附加内容

assemble 方法可以返回 systemPromptAddition 字符串。OpenClaw 会将它前置到本次运行的系统提示中。这让引擎能够注入动态召回指导、检索指令或上下文感知提示，而无需依赖静态工作区文件。

# legacy 引擎

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

• 摄取：无操作（会话管理器直接处理消息持久化）。
• 组装：透传（运行时中的现有 sanitize → validate → limit 管线处理上下文组装）。
• 压缩：委托给内置总结压缩，它会为较早的消息创建单个摘要，并保持最近消息不变。
• 轮次后：无操作。

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 }) {
      // Store the message in your data store
      return { ingested: true };
    },

    async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) {
      // Return messages that fit the budget
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },

    async compact({ sessionId, force }) {
      // Summarize older context
      return { ok: true, compacted: true };
    },
  }));
}

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

然后在配置中启用它：

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

# ContextEngine 接口

必需成员：

assemble 返回包含以下内容的 AssembleResult：

compact 返回 CompactResult。当压缩轮换活动 transcript 时，result.sessionId 和 result.sessionFile 会标识下一次重试或轮次必须使用的后继会话。

可选成员：

# ownsCompaction

ownsCompaction 控制 Pi 的内置尝试中自动压缩是否在本次运行中保持启用：

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

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

# 配置参考

{
  plugins: {
    slots: {
      // Select the active context engine. Default: "legacy".
      // Set to a plugin id to use a plugin engine.
      contextEngine: "legacy",
    },
  },
}

# 与压缩和记忆的关系

# 提示

• 使用 openclaw doctor 验证你的引擎是否正确加载。
• 如果切换引擎，现有会话会继续使用其当前历史记录。新引擎会接管未来的运行。
• 引擎错误会被记录并在诊断中显示。如果插件引擎注册失败，或无法解析所选引擎 ID，OpenClaw 不会自动回退；在你修复插件或将 plugins.slots.contextEngine 切回 "legacy" 之前，运行会失败。
• 开发时，使用 openclaw plugins install -l ./my-engine 链接本地插件目录，无需复制。

# 相关

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