6.2 上下文构建与窗口预算

本节讲“怎样把信息组装成模型能高效消费的输入”。上下文由工作区、技能、会话历史与工具回执共同组成；重点在注入顺序、预算分配与结构化回注——而裁剪（Pruning）和压缩（Compaction）的具体参数与机制统一收在 6.4 节。

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

在 OpenClaw 中，工作区是上下文的第一来源。官方记忆机制明确了几个关键文件的用途：系统提示、技能、工作区说明、长期记忆与每日日志。参考：记忆。

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

层级	来源	典型体积	生命周期
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），而不是直接修改提示词。

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

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

openclaw status --deep

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

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 增强、长期记忆向量化、领域特定的摘要算法）提供了无侵入的扩展点。