OpenClaw源码学习 | 上下文剪枝(context pruning)

OpenClaw 的上下文管理遵循“持久化与运行时分离”的原则，将剪枝机制拆分为两个独立的层面——硬剪枝（Hard Pruning） 与 软剪枝（Soft Pruning）。这两类剪枝在触发时机、作用对象和影响范围上有着本质区别，共同构成了从存储到交互的完整上下文管控体系。

🪓 硬剪枝

硬剪枝发生在工具执行结果写入会话文件（.jsonl）之前。它的核心职责是对单条 toolResult 进行大小裁剪，防止单个工具返回的数据量过大导致会话文件膨胀或后续加载失败。这种剪枝是永久性的——一旦写入，原始数据将被截断版本替代，保证了会话历史的一致性和可加载性，但代价是部分信息的丢失。

🌿 软剪枝

与硬剪枝不同，软剪枝发生在构建发送给模型的上下文请求时（即从会话文件读取历史后、发送给API前）。它根据当前模型的上下文窗口限制，对即将送入的 tool_result 等内容进行临时截断或压缩摘要。软剪枝是临时性的——它只影响单次模型调用，不会修改已持久化的会话记录。这种“阅后即焚”的方式，在控制输入体积的同时，完整保留了原始会话数据。

硬剪枝

调用链路如下：

runEmbeddingAttemp
 --> guardSessionManager
   ---> installSessionToolResultGuard
       ---> guardedAppend
        ---> capToolResultSize 

首先，runEmbeddingAttemp通过guardSessionManager包装并注入会话 Guard。

// src/agents/pi-embedded-runner/run/attemp.ts
exportasyncfunctionrunEmbeddedAttempt(...){
 ...
 sessionManager = guardSessionManager(SessionManager.open(params.sessionFile)
 ...
}

guardSessionManager内部会通过调用installSessionToolResultGuard方法替换sessionManager的appendMessage方法，在一条工具结果类型消息持久化之前，实施结果截断操作。我们先看看这个函数替换的逻辑。

// src/agents/pi-embedded-runner/run/attemp.ts
exportfunctioninstallSessionToolResultGuard(sessionManager,...){
// 1、把原始的 appendMessage 方法保存到 originalAppend 变量，并把它的 this 绑定到当前 sessionManager 实例上。
const originalAppend = sessionManager.appendMessage.bind(sessionManager);

// 2、新实现的 guardedAppend，执行硬剪枝，在消息写入前执行工具结果关联、验证、清理和持久化等逻辑，确保工具结果的正确性和上下文一致性，
const guardedAppend = (message: AgentMessage) => {
  ...
if (nextRole === "toolResult") { // 如果消息是工具执行结果类型
// 工具名规范化，例如去除前后空格等
const normalizedToolResult = normalizePersistedToolResultName(nextMessage, toolName);
// 持久化前执行硬剪枝
const capped = capToolResultSize(persistMessage(normalizedToolResult));
   ...  
  }
  ...
 }
// 3、用上述新实现版本替换 sessionManager 的 appendMessage 默认实现
 sessionManager.appendMessage = guardedAppend as SessionManager["appendMessage"];

}

真正做硬剪枝的是capToolResultSize函数。这里有一点需要注意，硬剪枝是在单条消息粒度执行的，目的是为了防止在后续调用大模型时，上下文窗口被某条超长工具执行结果所占用。下一节讨论的软剪枝，则是针对当前上下文中所有的工具结果消息一起执行的。capToolResultSize进一步调用了truncateToolResultMessage函数来实现。

// src/agents/session-tool-result-guard.ts
// 如果对工具结果执行了截断，则在消息后添加的提示文本
const TRUNCATION_SUFFIX =
"\n\n⚠️ [Content truncated — original was too large for the model's context window. " +
"The content above is a partial view. If you need more, request specific sections or use " +
"offset/limit parameters to read smaller chunks.]";

functioncapToolResultSize(msg: AgentMessage): AgentMessage{
if ((msg as { role?: string }).role !== "toolResult") {
return msg;
 }
return truncateToolResultMessage(msg, HARD_MAX_TOOL_RESULT_CHARS, {
  suffix: GUARD_TRUNCATION_SUFFIX,
  minKeepChars: 2_000,
 });
}

truncateToolResultMessage函数输入以下三个参数：

• maxChars：工具执行结果文本上限（包含截断后要追加的 suffix）。默认值为HARD_MAX_TOOL_RESULT_CHARS=400000
• suffix：截断后附加到每个工具执行输出末尾的提示文本（默认内容见上一个代码块的TRUNCATION_SUFFIX变量），实现上在计算可保留正文时会把 suffix.length 从 maxChars 中扣除，所以 suffix 的长度会影响正文可用空间。
• minKeepChars：截断时强制每个工具的执行结果至少保留的正文字符数（默认 MIN_KEEP_CHARS，库中为 2000）。也就是说即便 maxChars 很小也会至少保留 minKeepChars 的头部内容（然后再加上 suffix），以保证截断后的片段仍有足够上下文供模型/人类理解。

// src/agents/tool-result-truncation.ts
exportfunctiontruncateToolResultMessage(msg,maxChars,options){
const suffix = options.suffix ?? TRUNCATION_SUFFIX;
const minKeepChars = options.minKeepChars ?? MIN_KEEP_CHARS;
const content = (msg as { content?: unknown }).content;
// 1、计算当前消息的工具结果部分字符数，小于 maxChars 的不用截断
const totalTextChars = getToolResultTextLength(msg);
if (totalTextChars <= maxChars) {
return msg;
 }
// 2、content 是一个数组类型，下面的实现是把预算分配到内一个块，对每个块单独截断
const newContent = content.map((block: unknown) => {
// 2.1 按照块大小占整个消息内容大小比例分配截断预算
const blockShare = textBlock.text.length / totalTextChars;
const blockBudget = Math.max(minKeepChars + suffix.length, Math.floor(maxChars * blockShare));
return {
   ...textBlock,
// 2.2 按照分配给当前块的预算执行截断
   text: truncateToolResultText(textBlock.text, blockBudget, { suffix, minKeepChars }),
  };
 }
}

truncateToolResultText函数是对单个块（一条工具执行结果）执行截断。对某个文本块，它会先通过一些规则检查消息尾部是否有重要内容。如果尾部有重要内容，则实施head + tail 策略则分配0.3的预算给尾部，剩余的分配给头部。默认是保留head的消息为主。 阶段算法的流程如下：

算法：truncateToolResultText(text, maxChars, {suffix, minKeepChars})

输入：
- text：原始字符串
- maxChars：目标最大字符数（包含 suffix）
- suffix：截断后追加的提示（默认 TRUNCATION_SUFFIX）
- minKeepChars：至少保留的正文字符数（默认 2000）

步骤：
1. 若 |text| ≤ maxChars，则返回 text（不变）。
2. 计算正文预算：
   B = max(minKeepChars, maxChars - |suffix|)
3. 若尾部可能包含重要信息（hasImportantTail(text) 为真）且 B > 2 * minKeepChars，则使用 head+tail 策略：
   - T = min(floor(0.3 * B), 4000)  // 尾部预算
   - H = B - T - |MIDDLE_OMISSION_MARKER|  // 头部预算
   - 若 H > minKeepChars：
     - 在头部取截断点 h（优先选择靠近 H 的换行，否则 h = H）
     - 在尾部取起点 s（默认 |text|-T，若靠近换行则调整到换行后）
     - 返回 text[0:h) + MIDDLE_OMISSION_MARKER + text[s:] + suffix
4. 否则只保留头部：
   - 令 c = B，若在 ≤B 范围内存在靠近 B 的换行 n（n > 0.8*B），则 c = n
   - 返回 text[0:c) + suffix
5. 复杂度：O(n) 时间（n = |text|），常数额外空间（返回新字符串视为输出成本）

代码如下：

// arc/agents/pi-embedded-runner/tool-result-truncation.ts
exportfunctiontruncateToolResultText(
 text: string,
 maxChars: number,
 options: ToolResultTruncationOptions = {},
): string{
const suffix = options.suffix ?? TRUNCATION_SUFFIX;
const minKeepChars = options.minKeepChars ?? MIN_KEEP_CHARS;
if (text.length <= maxChars) {
return text;
 }
const budget = Math.max(minKeepChars, maxChars - suffix.length);

// If tail looks important, split budget between head and tail
if (hasImportantTail(text) && budget > minKeepChars * 2) {
const tailBudget = Math.min(Math.floor(budget * 0.3), 4_000);
const headBudget = budget - tailBudget - MIDDLE_OMISSION_MARKER.length;
if (headBudget > minKeepChars) {
// Find clean cut points at newline boundaries
let headCut = headBudget;
const headNewline = text.lastIndexOf("\n", headBudget);
if (headNewline > headBudget * 0.8) {
   headCut = headNewline;
  }
let tailStart = text.length - tailBudget;
const tailNewline = text.indexOf("\n", tailStart);
if (tailNewline !== -1 && tailNewline < tailStart + tailBudget * 0.2) {
   tailStart = tailNewline + 1;
  }
return text.slice(0, headCut) + MIDDLE_OMISSION_MARKER + text.slice(tailStart) + suffix;
  }
 }

// Default: keep the beginning
let cutPoint = budget;
const lastNewline = text.lastIndexOf("\n", budget);
if (lastNewline > budget * 0.8) {
  cutPoint = lastNewline;
 }
return text.slice(0, cutPoint) + suffix;
}

判断一条工具执行结果消息的尾部是否重要的算法也很简单，取消息尾部2000条结果，然后检查其中是否包含一些指示出错的关键词（error, exception,exit code），或者是否包含一些跟总结有关的关键词（total,summary,complete ）。

// arc/agents/pi-embedded-runner/tool-result-truncation.ts
functionhasImportantTail(text: string): boolean{
// Check last ~2000 chars for error-like patterns
const tail = text.slice(-2000).toLowerCase();
return (
/\b(error|exception|failed|fatal|traceback|panic|stack trace|errno|exit code)\b/.test(tail) ||
// JSON closing — if the output is JSON, the tail has closing structure
  /\}\s*$/.test(tail.trim()) ||
// Summary/result lines often appear at the end
  /\b(total|summary|result|complete|finished|done)\b/.test(tail)
 );
}

截断的内容则会使用一个占位符内容表示。

// arc/agents/pi-embedded-runner/tool-result-truncation.ts
/**
* Marker inserted between head and tail when using head+tail truncation.
*/
const MIDDLE_OMISSION_MARKER =
"\n\n⚠️ [... middle content omitted — showing head and tail ...]\n\n";

软剪枝

上下文的软剪枝会在调用大模型之前对工具调用结果进行压缩，但是这不会影响工具调用结果的持久化。

installToolResultContextGuard在运行时替换 agent.transformContext，对发送到模型的上下文执行临时截断/压缩。 先看看installToolResultContextGuard的行为： 调用链路如下：

runEmbeddingAttemp 
   --> installToolResultContextGuard 
     ---> enforceToolResultContextBudgetInPlace

// src/agents/pi-embedded-runner/tool-result-context-guard.ts
exportfunctioninstallToolResultContextGuard(params: {
 agent: GuardableAgent;
 contextWindowTokens: number;
}): () => void{
const contextWindowTokens = Math.max(1, Math.floor(params.contextWindowTokens));
const contextBudgetChars = Math.max(1_024,Math.floor(contextWindowTokens * CHARS_PER_TOKEN_ESTIMATE * CONTEXT_INPUT_HEADROOM_RATIO),);
//单条工具最大的输出结果字符
const maxSingleToolResultChars = Math.max(1_024,Math.floor(contextWindowTokens * TOOL_RESULT_CHARS_PER_TOKEN_ESTIMATE *SINGLE_TOOL_RESULT_CONTEXT_SHARE,),);

const mutableAgent = params.agent as GuardableAgentRecord;
// agent 原始的 transformContext
const originalTransformContext = mutableAgent.transformContext;
// 以下做运行时临时拦截
 mutableAgent.transformContext = (async (messages: AgentMessage[], signal: AbortSignal) => {
const transformed = originalTransformContext? await originalTransformContext.call(mutableAgent, messages, signal): messages;
const contextMessages = Array.isArray(transformed) ? transformed : messages;
// 这里根据配置和预算实施 工具调用结果 软剪枝
  enforceToolResultContextBudgetInPlace({
   messages: contextMessages,
   contextBudgetChars,
   maxSingleToolResultChars,
  }); 
return contextMessages;
 }) asGuardableTransformContext;
 // 返回恢复 默认 transformContext 的函数
return() => {
  mutableAgent.transformContext = originalTransformContext;
 };
}

在上面的代码中，enforceToolResultContextBudgetInPlace负责真正的软剪枝。对agent的transformContext函数的临时拦截的恢复操作以函数形式返回，在runEmbeddedAttemp中保存为变量removeToolResultContextGuard。在runEmbeddedAttemp的finally模块会运行这个拦截卸载工作。

// src/agents/pi-embedded-runner/run/attemp.ts
exportasyncfunctionrunEmbeddedAttempt(...){
try{
  ...
// 临时拦截 agent.transformContex函数，增加工具执行结果软剪枝逻辑
  removeToolResultContextGuard = installToolResultContextGuard({
   agent: activeSession.agent,
   contextWindowTokens: Math.max(1,Math.floor(params.model.contextWindow ?? params.model.maxTokens ?? DEFAULT_CONTEXT_TOKENS,),),});
   ...
  } finally {
// 卸载拦截 agent.transformContex函数
   removeToolResultContextGuard?.();
  } 
}

下面我们先看看，在agent调用大模型之前是如何感知这个操作的，然后再看看enforceToolResultContextBudgetInPlace函数的实现。给大模型发送请求的函数位于pi-mono项目的packages/agent/src/agent-loop.ts中的streamAssistantResponse函数，这个函数在发送大模型调用前会先调用transformContext对消息进行转换操作，而在上面openclaw的注入拦截操作中，我们已经增加了工具执行结果的剪枝了，因此大模型收到的消息已经是剪枝后的结果了。代码如下：

// packages/agent/src/agent-loop.ts
asyncfunctionstreamAssistantResponse(...){
// Apply context transform if configured (AgentMessage[] → AgentMessage[])
let messages = context.messages;
if (config.transformContext) {
// 下面的 transformContext 会执行我们之前拦截注入的工具结果剪枝
  messages = await config.transformContext(messages, signal);
 }
// 消息格式转换
const llmMessages = await config.convertToLlm(messages); 
// 构建 LLM 上下文
const llmContext: Context = {
  systemPrompt: context.systemPrompt,
  messages: llmMessages,  // 这个已经值剪枝后的消息了
  tools: context.tools,
 };
// 下面真正调用大模型
const streamFunction = streamFn || streamSimple;
const response = await streamFunction(config.model, llmContext, ...}
  ...
}

下面看看上下文软剪枝实现的核心函数enforceToolResultContextBudgetInPlace。它会从当前agent上下文所有消息中筛选出toolresult类型的消息，然后对每条toolresult消息实施截断操作。如果这一步截断还不满足约束。则进一步会对消息列表中较早的toolresult消息进行压缩操作。

// src/agents/pi-embedded-runner/tool-result-context-guard.ts
functionenforceToolResultContextBudgetInPlace(params: {
 messages: AgentMessage[];
 contextBudgetChars: number;
 maxSingleToolResultChars: number;
}): void{
// 读取上下文软剪枝的设置 maxSingleToolResultChars 为单条工具结果消息最大字符数，contextBudgetChars为估算的给所有工具结果的总预算
const { messages, contextBudgetChars, maxSingleToolResultChars } = params;
const estimateCache = createMessageCharEstimateCache();
// 对每一条工具结果消息实施截断
for (const message of messages) {
if (!isToolResultMessage(message)) {
continue;
  }
const truncated = truncateToolResultToChars(message, maxSingleToolResultChars, estimateCache);
  applyMessageMutationInPlace(message, truncated, estimateCache);
 }

let currentChars = estimateContextChars(messages, estimateCache);
if (currentChars <= contextBudgetChars) {
return;
 }
// 如果还不满足约束，则从最老的工具结果消息开始实施压缩，直到满足约束为止
 compactExistingToolResultsInPlace({
  messages,
  charsNeeded: currentChars - contextBudgetChars,
  cache: estimateCache,
 });

}

对于单条工具结果，跟上一节的硬剪枝可能采用head+tail策略不同，这里只使用了head策略。真正实现的函数为truncateTextToBudget。调用链路为truncateToolResultToChars-->truncateTextToBudget。这个函数的实现要点：

• 只做“头部截断”（不做 head+tail 或复杂保留尾部）；适合在上下文预算紧张时快速保留前文线索。
• 优先在接近预算末尾的换行处断开（阈值 0.7）以避免在行中间生硬截断。
• 当预算极小或被后缀耗尽时，函数会放弃正文并返回统一的截断提示字符串，避免产生空或无意义输出。

// src/agents/pi-embedded-runner/tool-result-context-guard.ts
functiontruncateTextToBudget(text: string, maxChars: number): string{

if (text.length <= maxChars) {
return text;
 }

if (maxChars <= 0) {
return CONTEXT_LIMIT_TRUNCATION_NOTICE;
 }

const bodyBudget = Math.max(0, maxChars - CONTEXT_LIMIT_TRUNCATION_SUFFIX.length);
// 当预算极小或被后缀耗尽时，函数会放弃正文并返回统一的截断提示字符串
if (bodyBudget <= 0) {
return CONTEXT_LIMIT_TRUNCATION_NOTICE;
 }
// 优先在接近预算末尾的换行处断开
let cutPoint = bodyBudget;
const newline = text.lastIndexOf("\n", bodyBudget);
if (newline > bodyBudget * 0.7) {
  cutPoint = newline;
 }

return text.slice(0, cutPoint) + CONTEXT_LIMIT_TRUNCATION_SUFFIX;
}