OpenClaw:上下文(Context)控制机制 -- 拒绝频繁“钳”断

@ 目录

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`	在剩余指定值时，提示总结上下文并保存（比压缩早一些，如10k）
`systemPrompt`	自定义	提示模型归档重要信息
`prompt`	自定义	指导模型写入 memory/YYYY-MM-DD.md

工作机制：

上下文增长 → 剩 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// 保留条目增加}}// ... 其他配置项省略 ...}

声明：资源可能存在第三方来源，若有侵权请联系删除！