【OpenClaw -08】OpenClaw 上下文管理深度实战：从 Context Pruning 到 Token 成本优化

OpenClaw 上下文管理深度实战：从 Context Pruning 到 Token 成本优化

标签 ： OpenClaw | LLM 上下文管理 | Token 优化 | AI Agent 架构

生产环境运行 OpenClaw 一周后，你可能会遭遇这样的噩梦：对话仅 35 条消息，Token 消耗却飙升至 208k，上下文窗口直接撑爆，Agent 开始"失忆"或拒绝响应。这不是模型能力问题，而是上下文管理失控的典型案例。本文基于 OpenClaw 官方文档与 GitHub Issue #2254 深度复盘，拆解 Context Pruning、Compaction、Safeguard 三大核心机制，助你构建成本可控的长会话 Agent 系统。

一、Token 爆炸案例：208k 上下文危机复盘

1.1 问题现象

GitHub Issue #2254 记录了一个典型生产事故 ：

指标	数值	正常范围
对话轮数	35 messages	---
上下文 Token 数	208,467 tokens	< 100k
会话文件大小	2.9 MB	< 500 KB
触发后果	超出 Claude 200k 窗口限制，Agent 无响应	---

根本原因：默认配置下，Tool Results（工具执行结果）会被完整保留在上下文中。一次 exec 命令返回 10KB 日志，十轮对话后就是 100KB 的文本注入，加上历史累积，Token 数量呈指数级膨胀。

1.2 上下文构成解剖

OpenClaw 的每次 LLM 调用都包含以下 Token 消耗项 ：

┌─────────────────────────────────────────────────────────────┐
│                    OpenClaw 上下文构成                        │
├─────────────────────────────────────────────────────────────┤
│  系统提示词 (System Prompt)                                   │
│  ├── 工具列表 + Schema (Tool Definitions)                    │
│  ├── Skill 清单 (仅元数据)                                    │
│  ├── Bootstrap 文件注入 (AGENTS.md, SOUL.md, TOOLS.md...)    │
│  │   └── 受 bootstrapMaxChars (默认 20k) 限制               │
│  └── 运行时元数据 (时间、主机信息)                             │
│                                                              │
│  对话历史 (Conversation History)                              │
│  ├── 用户消息 (User Messages)                                │
│  ├── Assistant 消息                                          │
│  └── Tool Results (工具返回结果) ← 膨胀重灾区                 │
│                                                              │
│  附件与转录 (Images/Audio/Files)                             │
└─────────────────────────────────────────────────────────────┘

关键认知：Tool Results 是唯一会被自动清理的历史组件。User 和 Assistant 消息永远不会被修改，只能通过 Compaction 总结 。

二、Context Pruning：手术刀式 Tool Result 清理

Context Pruning 是 OpenClaw 的"紧急止血"机制，在每次 LLM 调用前，从内存上下文中剪除过期 Tool Results，但保留磁盘上的完整历史记录 。

2.1 工作机制与触发条件

Pruning 仅在以下严格条件下触发 ：

• Provider 限制：仅对 Anthropic API 调用生效（包括 OpenRouter 上的 Anthropic 模型）
• TTL 过期：mode: "cache-ttl" 且距离上次 Anthropic 调用超过 ttl 时间（默认 5 分钟）
• 消息保护：保留最近 keepLastAssistants 条 Assistant 消息（默认 3 条）之后的 Tool Results 不受保护

用户提问 → Gateway 构造 Context → 检查 TTL 是否过期
                                    │
                                    ▼
                              是 → 执行 Pruning
                                    │
                                    ├── Soft Trim: 超大 Tool Result 保留头尾
                                    │              (headChars: 1500 + tailChars: 1500)
                                    │
                                    └── Hard Clear: 旧 Tool Result 替换为占位符
                                                   "[Old tool result content cleared]"
                                    │
                                    ▼
                              重置 TTL 窗口 → 发送 LLM 请求

2.2 两级剪枝策略详解

根据 Tool Result 大小和占比，Pruning 实施差异化处理 ：

策略	触发条件	处理方式	适用场景
Soft Trim	单条 Tool Result > softTrim.maxChars (默认 4k) 且占总上下文 > softTrimRatio (30%)	保留头 1500 字符 + 尾 1500 字符，中间替换为 ... 并标注原始大小	超大日志文件、代码片段
Hard Clear	可清理 Tool Result 总量 > minPrunableToolChars (50k) 且占比 > hardClearRatio (50%)	完全替换为 hardClear.placeholder 文本	过期命令输出、历史工具调用

特殊保护：包含图像块的 Tool Results 永远不会被修剪，这是为了防止视觉信息丢失 。

2.3 生产级配置示例

{
  "agents": {
    "defaults": {
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "5m",
        "keepLastAssistants": 3,
        "softTrimRatio": 0.3,
        "hardClearRatio": 0.5,
        "minPrunableToolChars": 50000,
        "softTrim": {
          "maxChars": 4000,
          "headChars": 1500,
          "tailChars": 1500
        },
        "hardClear": {
          "enabled": true,
          "placeholder": "[Historical tool output cleared - re-run if needed]"
        },
        "tools": {
          "allow": ["exec", "read", "memory_search"],
          "deny": ["browser", "canvas", "*image*"]
        }
      }
    }
  }
}

成本优化原理 ：

• Anthropic Prompt Caching 仅在 TTL 窗口内有效。会话闲置超过 TTL 后，下次请求会触发重新缓存完整上下文
• Pruning 减少了 TTL 过期后首个请求的 cacheWrite Token 数，直接降低 API 成本
• 执行 Pruning 后 TTL 窗口重置，后续请求可复用新缓存，避免反复全量缓存

三、Compaction：上下文压缩与长期记忆持久化

如果说 Pruning 是"临时清理"，Compaction 就是"归档总结"。当上下文接近模型窗口限制时，Compaction 将历史对话总结为 compact summary，并持久化到 Session JSONL 文件中 。

3.1 Compaction 触发机制

自动触发条件 ：

contextTokens > contextWindow - reserveTokensFloor

默认参数：

• reserveTokensFloor: 20,000 tokens（为 bootstrap 注入预留的安全垫）
• contextWindow: 模型定义值（Claude 3.5 Sonnet 为 200k，GPT-4 为 128k）

触发后流程：

• 可选 Memory Flush：如果启用 memoryFlush.enabled，先执行一轮静默写入，将关键信息保存到 memory/YYYY-MM-DD.md
• 总结生成：调用 LLM 对历史消息进行摘要，保留决策、状态变更、关键结论
• 上下文替换：原始历史被替换为 Summary Entry + 最近消息
• 持久化存储：Summary 写入 Session 的 JSONL 文件，跨会话保持

3.2 三种 Compaction 模式对比

模式	策略	适用场景	风险
default	标准单轮总结	常规对话，历史 < 50k tokens	极长历史可能导致总结请求本身超限
safeguard	分块总结（Chunked Summarization）	超长会话（>100k tokens）、代码审查、文档分析	稍高延迟，但避免溢出
aggressive	激进压缩，保留更少细节	成本敏感场景，允许信息损失	可能丢失重要上下文

Safeguard 模式详解 ：

当启用 mode: "safeguard"，OpenClaw 加载 compaction-safeguard 扩展，实施自适应 Token 预算：

• 将超长历史分割为多个 chunks 分别总结
• 包含工具失败和文件操作的专项摘要
• 避免一次性总结请求超出上下文限制

3.3 Memory Flush：压缩前的"数据抢救"

关键配置参数 ：

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000,
          "systemPrompt": "Session nearing compaction. Store durable memories now.",
          "prompt": "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
        }
      }
    }
  }
}

工作机制：

• 在 Compaction 执行前，Gateway 发起一轮"静默对话"（Silent Turn）
• Agent 评估当前会话状态，将关键事实写入 Memory 文件
• 使用 NO_REPLY 约定，该轮不发送可见消息给用户，仅在后台执行
• 写入完成后才执行真正的 Compaction，确保重要信息不会因总结而丢失

四、Bootstrap 文件管理：源头控制上下文膨胀

即使 Pruning 和 Compaction 运行良好，过大的 Bootstrap 文件仍会持续吞噬 Token。OpenClaw 默认注入以下工作区文件 ：

AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md

4.1 截断策略与配置

当 Bootstrap 文件超过限制时，OpenClaw 采用 70/20/10 分割策略 ：

• 70% 保留文件头部（通常包含核心指令）
• 20% 保留文件尾部（通常包含最新变更）
• 10% 用于截断标记 [...truncated...]
  关键配置参数 ：

{
  "agents": {
    "defaults": {
      "bootstrapMaxChars": 20000,      // 单文件上限，默认 20k 字符
      "bootstrapTotalMaxChars": 150000, // 所有文件总计上限，默认 150k 字符
      "bootstrapPromptTruncationWarning": "once"  // 截断警告显示策略
    }
  }
}

诊断命令：

/context list      # 查看各文件原始 vs 注入大小
/context detail    # 查看 Tool Schema 等隐藏消耗

常见陷阱：TOOLS.md 容易膨胀至 50k+ 字符，建议拆分为多个文件或仅保留当前项目相关工具 。

五、Token 监控与成本优化实战

5.1 实时监控手段

命令/配置	功能	使用场景
/status	查看当前会话 Token 使用、压缩次数、模型状态	日常健康检查
/context list	查看 Bootstrap 文件注入情况、是否被截断	诊断上下文膨胀
/context detail	详细分解 Tool Schema、Skill 列表的 Token 消耗	优化系统提示词
openclaw report --type token-usage	生成 Token 使用报告	周期性成本审计

5.2 成本优化策略矩阵

基于社区最佳实践与官方建议，整理以下优化路径 ：

阶段一：快速止血（立省 70% Token）

• 启用 aggressive pruning：

"contextPruning": { "mode": "cache-ttl", "ttl": "3m" }

• 精简 Bootstrap 文件：

  将 TOOLS.md 从 50k 字符压缩至 5k 以内

  删除 SOUL.md 中的冗长角色设定

• Skill 按需加载：

  • 禁用非必要 Skill，减少系统提示词中的 Skill 清单长度
  • 每个 Skill 仅注入名称+描述，详细指令在首次调用时 read

阶段二：架构优化（再省 20%）

• 多 Agent 分工：

"agents": {
  "list": [
    { "id": "coder", "skills": ["code"], "maxContextTokens": 16000 },
    { "id": "writer", "skills": ["docs"], "maxContextTokens": 8000 }
  ]
}

• 模型降级策略：

  • 常规任务使用 google/gemini-3-flash-preview（$0.15/1M tokens）
  • 复杂推理才启用 claude-opus-4（$15/1M tokens）

• Session 生命周期管理：

"session": {
  "maintenance": {
    "mode": "enforce",
    "pruneAfter": "30d",
    "maxEntries": 500
  }
}

阶段三：治理与监控

{
  "costControl": {
    "dailyBudgetUSD": 5.0,
    "maxTokensPerSession": 50000,
    "warnAtPercentage": 80,
    "autoStopAtPercentage": 95
  }
}

六、生产环境配置 checklist

基于本文内容，整理生产级部署的核查清单：

检查项	推荐配置	风险等级
Context Pruning 启用	mode: "cache-ttl", ttl: "5m"	高（未启用将导致 Token 爆炸）
Compaction 模式	mode: "safeguard"（长会话）或 "aggressive"（成本敏感）	高
Memory Flush	enabled: true, softThresholdTokens: 4000	中（防止压缩丢数据）
Bootstrap 限制	bootstrapMaxChars: 20000, bootstrapTotalMaxChars: 150000	中
Tool 白名单	通过 tools.allow/deny 限制注入的工具数量	中
Session 隔离	session.dmScope: "per-channel-peer"（多用户场景）	高
Token 监控	配置 Heartbeat 每 30m 检查 /status	低

七、总结：上下文管理的三层防御体系

OpenClaw 的上下文管理是"分层防御"架构的典范：

• 源头控制（Bootstrap 截断）：通过 bootstrapMaxChars 防止工作区文件过度膨胀
• 运行时清理（Context Pruning）：通过 cache-ttl 机制定期清理过期 Tool Results，解决 208k Token 爆炸问题
• 危机处理（Compaction + Safeguard）：当窗口即将耗尽时，通过分块总结和 Memory Flush 实现 graceful degradation

理解这三层机制的协同关系，是构建生产级 Agent 系统的关键。记住：Token 就是成本，上下文就是记忆。在 OpenClaw 中，这两者通过精细的工程化手段实现了平衡。

本文章基于OpenClaw官方文档学习撰写。仅供学习参考，请勿用于商业用途。