夜雨聆风@ 目录
1.概述 1）认识上下文（Context） 2.openclaw.json控制上下文 1）contextWindow（模型输入上下文限制） 2）contextTokens（Agent输入上下文限制） 3）compaction（压缩上下文） 4）contextPruning（裁剪） 5）bootstrapMaxChars（控制注入文件大小） 3.其他上下文控制 1）Skills：注入内容和按需加载的内容 2）Tools：有两种成本 4.诊断和优化上下文 5.openclaw.json配置示例 1）修改前`openclaw.json` 2）修改后`openclaw.json`
1.概述
当对话过长或skills/tools返回大量输出时，OpenClaw 可能会超出 LLM 提供商的最大上下文窗口。这会导致类似如下等等问题：
• 报错1：上下文长度超出限制（context_length_exceeded） • 报错2：输入token超出最大限制（maximum context length is X tokens, but input is Y tokens.） • 报错3：模型运行崩溃或重新加载（model crashed / model reload）
那么我们就需要确保上下文长度在合理范围内。真正控制上下文（Context）的方法有：
• 减少输入源：tools / skills / files • 压缩历史：compaction • 缩短生命周期：pruning
.
1）认识上下文（Context）
上下文（Context）是指 OpenClaw 在一次运行中发送给模型的所有内容。OpenClaw本质是每次请求重新构建一个完整 prompt。
Context ≠ memory：
• Context：当前请求发送给模型的全部内容； • Memory：磁盘存储，可重新加载
Context 组成：
• System prompt：系统提示词。 • Conversation history：对话历史。 • Tool calls + tool results：工具调用 + 工具返回结果。 • Attachments/transcripts：附件/转录（图像/音频/文件）。 • Compaction summaries and pruning artifacts：压缩摘要和修剪产物。 • Provider“wrappers”or hidden headers：提供商“包装器”或隐藏标头（不可见，但仍计入）。
重点：不只有“聊天记录”在吃 token。工具调用和返回以及文件注入是最大隐形开销。
.
2.openclaw.json控制上下文
OpenClaw 不提供“精确裁剪上下文”的配置能力。因为Context 构建是在 Gateway runtime 内部完成，不是简单 config。
OpenClaw 不能做到的：
• 限制“只保留最近n条消息” • 控制“只发送部分历史” • 精确控制 prompt 拼接
OpenClaw 能做的：间接控制（Indirect Control）
• 限制上下文窗口（contextWindow） • 限制总预算（contextTokens） • 触发压缩（compaction） • 删除非核心内容（pruning）
.
1）contextWindow（模型输入上下文限制）
models.providers.*.models[].contextWindow参数：
• 本质是告诉 OpenClaw“模型最多只能吃这么多 token”； • 需要确保该参数数值，小于等于模型支持最高上下文长度。
.
2）contextTokens（Agent输入上下文限制）
agents.defaults.contextTokens参数：
• 限制最大输入 token • 超过 → 触发 compaction / pruning
本质：“提前刹车”，不是“减少内容”
.
3）compaction（压缩上下文）
agents.defaults.compaction配置块，这里介绍以下参数
• reserveTokensFloor：触发压缩动作的阈值
• memoryFlush子配置：
enabled | true | |
softThresholdTokens | 需要大于reserveTokensFloor | |
systemPrompt | ||
prompt |
工作机制：
上下文增长 → 剩 softThresholdTokens 达到 contextWindow 时 → 触发 memoryFlush → 模型保存关键记忆 → 继续增长 → 剩 reserveTokensFloor 达到 contextWindow 时 → 触发 compaction → 压缩旧对话 → 上下文释放.
4）contextPruning（裁剪）
contextPruning:{ mode:"cache-ttl", ttl:"30m"}作用
• 删除 tool results 或 大输出缓存； • 不影响核心对话历史
.
5）bootstrapMaxChars（控制注入文件大小）
大文件按文件使用 agents.defaults.bootstrapMaxChars（默认 20000 字符）截断。
默认情况下，OpenClaw 注入一组固定的工作区文件（如果存在）：
• AGENTS.md• SOUL.md• TOOLS.md• IDENTITY.md• USER.md• HEARTBEAT.md• BOOTSTRAP.md（仅首次运行）
/context 显示原始 vs 注入大小以及是否发生了截断。
.
3.其他上下文控制
1）Skills：注入内容和按需加载的内容
注入内容：系统提示词包含一个紧凑的 Skills 列表（名称 + 描述 + 位置）。此列表有实际开销。
按需加载的内容：Skill 指令默认不包含。模型应该仅在需要时read Skill 的 SKILL.md。
.
2）Tools：有两种成本
工具以两种方式影响上下文：
• 系统提示词中的工具列表文本（你看到的”Tooling”）。 • 工具 schema（JSON）。这些发送给模型以便它可以调用工具。它们计入上下文，即使你看不到它们作为纯文本。
/context detail 分解最大的工具 schema，以便你可以看到什么占主导。
.
4.诊断和优化上下文
常用命令：诊断上下文占用
/status # 当前占用/context list # 谁占空间/context detail # 精细分析/usage tokens # 在正常回复后附加每次回复的使用量页脚。# 诊断推荐流程：/context list → 找最大项 → 对应优化优化优先级：
• 减少 Tool schemas • 控制 workspace 文件注入大小（bootstrap） • 开启压缩（compaction） • 设置合适的上下文限制（contextWindow、contextTokens） • 修剪（pruning）
.
5.openclaw.json配置示例
1）修改前openclaw.json
该配置缺乏主动管理机制，很容易导致上下文无限增长直至撑爆模型。
{"models":{"mode":"merge","providers":{"local-provider":{"baseUrl":"http://127.0.0.1:1234/v1","apiKey":"local","api":"openai-completions","models":[{"id":"local-model","name":"Local Model","contextWindow":128000,"maxTokens":4096}]}}},"agents":{"defaults":{"model":{"primary":"local-provider/local-model"},"workspace":"~/.openclaw/workspace"}},"session":{"maintenance":{"mode":"enforce","pruneAfter":"7d","maxEntries":200}}// ... 其他配置项省略 ...}.
2）修改后openclaw.json
此配置引入了三层上下文防护机制：
• 硬限制对齐：让 OpenClaw 知道模型的真实服务能力。 • 软预算控制：预留安全缓冲区，避免边缘溢出。 • 主动压缩：在达到上限前自动瘦身，保证对话可持续。
配置中使用了 <PLACEHOLDER> 占位符格式的参数，请根据实际情况替换。
{"models":{"mode":"merge","providers":{"local-provider":{"baseUrl":"http://127.0.0.1:1234/v1","apiKey":"local","api":"openai-completions","models":[{"id":"local-model","name":"Local Model",// [修改 1] 核心修正：将此值设为本地推理服务实际的 KV Cache 大小或小于// 说明：这是解决崩溃的根本。如果 LM Studio/Ollama 只开了 8k 上下文，// 这里填 128000 就会导致崩溃。必须保持一致。"contextWindow": <YOUR_BACKEND_N_CTX>,// 例如: 8192, 32768, 65536"maxTokens":4096}]}}},"agents":{"defaults":{"model":{"primary":"local-provider/local-model"},"workspace":"~/.openclaw/workspace",// [修改 2] 新增：有效上下文预算上限// 说明：建议设为 contextWindow 的 75% - 85%。// 预留空间给系统提示词、工具定义等“隐形”token。"contextTokens": <YOUR_SAFE_TOKEN_LIMIT>,// 例如: 6000, 24000, 50000// [修改 3] 新增：上下文压缩与管理策略// 说明：启用主动管理，防止上下文无限增长。"compaction":{// 触发压缩的阈值。当剩余空间少于此值时开始压缩。// 建议值：contextTokens 的 15% - 20%，或至少保留 2000-4000 tokens。"reserveTokensFloor": <YOUR_RESERVE_TOKENS>,// 例如: 2000, 8000"memoryFlush":{"enabled":true,// 提前警告阈值。在即将压缩前提醒模型保存记忆。// 建议值：比 reserveTokensFloor 略高，例如高出 10000 tokens。"softThresholdTokens": <YOUR_FLUSH_THRESHOLD>,"systemPrompt":"Session context is filling up. Please archive important information to memory files.","prompt":"Write key information to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."}},"subagents":{"maxConcurrent":2,"model":"local-provider/local-model"}}},"session":{"maintenance":{// [修改 4] 放宽磁盘清理策略// 说明：避免过早删除会话文件。上下文管理交给 compaction 处理。"mode":"warn",// 从 "enforce" 改为 "warn""pruneAfter":"30d",// 保留时间延长"maxEntries":500// 保留条目增加}}// ... 其他配置项省略 ...}.
声明：资源可能存在第三方来源，若有侵权请联系删除！
