> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/06_context_memory/6.2_context_building.md).

# 6.2 上下文构建与窗口预算

本节讲“怎样把信息组装成模型能高效消费的输入”。上下文由工作区、技能、会话历史与工具回执共同组成；重点在注入顺序、预算分配与结构化回注——而裁剪（Pruning）和压缩（Compaction）的具体参数与机制统一收在 [6.4 节](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/06_context_memory/6.4_compaction_pruning.md)。

## 6.2.1 上下文组成：四层信息源

在 OpenClaw 中，工作区是上下文的第一来源。官方记忆机制明确了几个关键文件的用途：系统提示、技能、工作区说明、长期记忆与每日日志。参考：[记忆](https://docs.openclaw.ai/concepts/memory)。

一次模型调用的上下文按注入顺序可分为四层：

| 层级            | 来源                                                                                     | 典型体积         | 生命周期                         |
| ------------- | -------------------------------------------------------------------------------------- | ------------ | ---------------------------- |
| 1. 系统身份与项目上下文 | AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md、紧凑技能清单与运行时元数据 | 1-3K token   | 按当前 gate 与会话状态注入             |
| 2. 工作区知识      | MEMORY.md、每日日志、检索/召回结果                                                                 | 0.5-2K token | 按会话、工具或 active-memory 条件动态注入 |
| 3. 对话历史       | 用户消息与助手回复                                                                              | 随会话增长        | 受裁剪与压缩控制                     |
| 4. 工具回执       | 工具调用的原始返回                                                                              | 单次可达数十K      | 最先被裁剪的对象                     |

上下文的工程挑战并不在“有没有信息”，而在“信息是否以可用形态被注入”。典型反模式是把大量工具原始输出长期堆在会话里，导致成本、时延与注意力稀释一起失控。

## 6.2.2 注入顺序与优先级原则

上下文组装遵循“身份先于知识，知识先于历史，历史先于工具”的优先级。当总预算紧张时，牺牲顺序为：旧工具回执 → 早期对话轮次 → 工作区知识 → 系统身份（不可牺牲）。

工程建议：

* **身份层锁定预算**：AGENTS.md / SOUL.md / TOOLS.md / IDENTITY.md / USER.md / HEARTBEAT.md / BOOTSTRAP.md、运行时元数据和紧凑技能清单的体积应在设计时控制；它们是否注入受当前 gate 与会话状态影响，完整 `SKILL.md` 指令按需读取，不属于默认固定上下文。
* **工具回注结构化**：把关键字段与摘要回注进会话，把全量输出落盘为证据引用。避免将整个 API 响应作为工具结果留在上下文中。
* **检索按需注入**：memory-core 默认更偏向注入工具使用指导；真实召回通常由模型调用 `memory_search` / `memory_get`，或由 active-memory 在满足条件时加入 preprompt。`memory_recall` 只属于 LanceDB 等替代记忆插件的工具面，不要假设每轮 assemble 都会自动执行一次 `memory_search`。

## 6.2.3 窗口预算的实践规则

Token 预算的分配没有万能公式，但以下经验值可作为起点：

* **系统身份**：预留 10-15% 的窗口给固定指令。
* **工作区知识**：预留 5-10%，按相关性排序后截断。
* **对话历史 + 工具回执**：剩余 75-85%，由裁剪（Pruning）和压缩（Compaction）机制动态管理。

当出现“工具已调用但模型忽略结果”时，优先检查工具回注是否被裁剪清除（参见 [6.4.3](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/06_context_memory/6.4_compaction_pruning.md)），而不是直接修改提示词。

## 6.2.4 验证命令：确认上下文组装符合预期

操作示例：观察系统状态与模型侧错误分布，确认上下文组装是否引入异常。

```bash
openclaw status --deep
```

操作示例：统计裁剪相关事件或占位符出现频率，判断是否过度裁剪。日志字段以实际实现为准。

```bash
cat runtime.log | rg "Old tool result content cleared" | wc -l
```

## 6.2.5 可插拔上下文引擎

OpenClaw 的上下文管理已不再是硬编码的单一实现，而是抽象为**上下文引擎**（Context Engine）接口。内置的 `legacy` assemble 路径更接近 pass-through，compact 会委托内建摘要能力；session pruning 仍由会话维护逻辑运行，不应把它理解成 `legacy` 引擎专属能力。插件可以注册自定义引擎来替换上下文的组装、摄入、压缩和子智能体传递逻辑。

上下文引擎的生命周期方法包括：

* **assemble**：在每次模型调用前，将会话历史按 token 预算组装为有序消息列表。引擎可以在此阶段注入检索结果、调整消息顺序或插入系统提示词片段。
* **ingest / ingestBatch**：每轮对话后将新消息摄入引擎存储，供后续 assemble 使用。
* **compact**：当上下文接近预算时压缩历史，可实现摘要、合并或外部向量化等策略。
* **maintain**：在引导、成功轮次或压缩后执行转录维护，通过运行时提供的 `rewriteTranscriptEntries()` 安全地修改会话 DAG。
* **afterTurn**：轮次结束后的持久化和后台决策钩子。

通过 `plugins.slots.contextEngine` 配置项可以将自定义引擎绑定到指定的插件。当引擎声明 `ownsCompaction: true` 时，运行时会将压缩决策完全委托给该引擎，不再触发内置的自动压缩流程。这为需要深度定制上下文策略的场景（如 RAG 增强、长期记忆向量化、领域特定的摘要算法）提供了无侵入的扩展点。