1. OpenClaw 长会话上下文溢出：context_length_exceeded 报错到底怎么来的
如果你用 OpenClaw 跑过稍微长一点的会话，尤其是那种带一堆工具调用、还挂了几个 Skill 的场景，大概率见过下面这几种报错：
Error: context_length_exceeded Error: maximum context length is 32768 tokens, but input is 41230 tokens Error: model crashed / model reload第一次看到的时候我也懵，明明对话才几十轮，怎么 token 就爆了。后来把/context detail打开一看才明白：真正吃 token 的根本不是聊天记录，而是工具 schema、Skill 列表、workspace 文件注入这些东西。它们平时看不见，但每次请求都会重新拼进 prompt 里。
OpenClaw 的 Context 控制机制，核心就是三条线：contextWindow 定硬上限、compaction 压缩历史、contextPruning 裁剪缓存。这篇就围绕这三条线，把配置片段和验证动作都写清楚，你在本地能直接复现。
先说清楚 Context 是什么。OpenClaw 本质上是每次请求重新构建一个完整 prompt，这个 prompt 包含：
- System prompt（系统提示词）
- Conversation history（对话历史）
- Tool calls + tool results（工具调用和返回）
- Attachments / transcripts（附件、转录）
- Compaction summaries 和 pruning artifacts（压缩摘要、裁剪产物）
- Provider 的隐藏 wrapper（不可见但计入）
注意最后一条，很多 provider 会在请求里塞一些你看不到的包装内容，它们照样占 token。所以 Context ≠ memory，memory 是磁盘上的东西，可以重新加载；Context 是这一次请求实际发出去的全部内容。
适合谁看这篇：本地跑 OpenClaw、接了 LM Studio / Ollama 这类本地推理服务、或者用云端模型但会话一长就崩的人。下面所有配置都基于openclaw.json，路径和字段名跟官方文档保持一致。
2. TaoToken 前置准备：给 OpenClaw 配一个稳定的模型入口
在动 Context 配置之前，得先保证模型入口是通的。我本地测试的时候，模型侧用的是 TaoToken 的 API，原因是它的 Base URL 和 OpenAI 兼容格式一致，OpenClaw 里api: "openai-completions"直接就能对接，不用改协议。
你需要准备三样东西：Base URL、API Key、Model ID。这三件套在 OpenClaw 的 provider 配置里缺一不可。
Base URL 填https://taotoken.net/api，注意这里不加任何 UTM 参数，就是纯 API 地址。API Key 去控制台生成，路径是 API Keys 管理页，生成后复制出来，别截图存微信，直接贴进配置文件。
Model ID 这块要注意，OpenClaw 的models[].id必须和 provider 侧实际可用的模型名一致，写错了会在请求阶段直接 404 或者 model not found。你可以先在 模型对话页 里手动发一条消息，确认模型能正常返回，再去配 OpenClaw。
如果你打算长期跑编码类 Agent 任务，会话轮次多、工具调用密集，建议直接上 Coding Plan，额度模型对长会话更友好，不会跑一半因为配额问题中断，导致 compaction 做到一半失败。
配好之后，OpenClaw 的 provider 段落大概长这样，先别急着加 compaction，我们一步步来：
{ "models": { "mode": "merge", "providers": { "taotoken": { "baseUrl": "https://taotoken.net/api", "apiKey": "<YOUR_TAOTOKEN_API_KEY>", "api": "openai-completions", "models": [ { "id": "<YOUR_MODEL_ID>", "name": "TaoToken Model", "contextWindow": 128000, "maxTokens": 4096 } ] } } } }这里contextWindow先填 128000 是假设你用的模型支持这个长度。但如果你本地是 LM Studio 或者 Ollama，实际 KV Cache 只开了 8k，这里填 128000 就会直接崩，下一节详细说这个坑。
3. openclaw.json 可复制配置：contextWindow、compaction、contextPruning 三件套
这一节是核心，直接给可复制的配置片段。先说清楚 OpenClaw 能做什么、不能做什么，避免你抱错期望。
OpenClaw不能精确控制 prompt 拼接，不能"只保留最近 n 条消息"，也不能指定"只发送部分历史"。因为 Context 构建是在 Gateway runtime 内部完成的，不是简单 config 能干预的。
OpenClaw能做的是间接控制：限制 contextWindow、限制 contextTokens 总预算、触发 compaction 压缩、用 contextPruning 删缓存。这四件事组合起来，就能把上下文控制在安全范围内。
3.1 contextWindow：硬上限必须和推理服务对齐
models.providers.*.models[].contextWindow这个参数，本质是告诉 OpenClaw"这个模型最多能吃多少 token"。关键点：它必须小于等于模型实际支持的最大上下文长度。
本地推理最容易踩的坑就在这。比如你在 LM Studio 里加载模型时n_ctx设的是 8192，但openclaw.json里contextWindow写了 128000，OpenClaw 就会按 128000 去拼 prompt，结果发过去直接超出后端 KV Cache，模型崩溃或者 reload。
所以第一步永远是：确认后端实际上下文大小，然后把这个值填进contextWindow。
"contextWindow": 8192如果你用的是云端模型，比如通过 TaoToken 接入的模型，就填模型官方标称的上下文长度，比如 128000 或 200000。填之前去 接入文档 确认一下当前模型的上下文规格，别凭记忆填。
3.2 contextTokens：Agent 层的软预算
agents.defaults.contextTokens是 Agent 输入上下文的总预算。它和 contextWindow 的区别是：contextWindow 是模型能力上限，contextTokens 是你主动设的安全线。
建议设成 contextWindow 的 75% 到 85%。为什么留这么多？因为系统提示词、工具 schema、Skill 列表这些"隐形"内容也要占空间，你按 100% 设，实际请求一拼就超。
"contextTokens": 6000上面这个 6000 是配合 8192 的 contextWindow 用的，留了约 27% 的缓冲。如果你 contextWindow 是 128000，contextTokens 可以设 100000 左右。
超过 contextTokens 会触发 compaction 或 pruning，所以它本质是"提前刹车"，不是"减少内容"。
3.3 compaction：压缩历史，防止无限增长
agents.defaults.compaction是主动管理机制。核心参数是reserveTokensFloor，定义触发压缩的剩余空间阈值。当上下文剩余空间小于这个值时，自动把旧对话总结成摘要条目，释放空间。
"compaction": { "reserveTokensFloor": 2000, "memoryFlush": { "enabled": true, "softThresholdTokens": 12000, "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." } }工作机制是这样的：上下文增长 → 剩余空间到softThresholdTokens→ 触发 memoryFlush，模型把关键信息写进 memory 文件 → 继续增长 → 剩余空间到reserveTokensFloor→ 触发 compaction，压缩旧对话 → 空间释放。
注意softThresholdTokens必须大于reserveTokensFloor，一般高出 10000 左右。上面例子里 soft 是 12000，floor 是 2000，差 10000，符合建议。
reserveTokensFloor建议设成 contextTokens 的 15% 到 20%，或者至少保留 2000 到 4000 token。设太小会导致压缩操作本身没空间执行，出现"压缩失败 → 崩溃"的循环。
3.4 contextPruning：裁剪工具缓存
contextPruning用来删除 tool results 或大输出缓存，不影响核心对话历史。配置很简单：
"contextPruning": { "mode": "cache-ttl", "ttl": "30m" }mode: "cache-ttl"表示按 TTL 过期清理，ttl: "30m"是 30 分钟。工具返回的大块内容，比如读了一个大文件、跑了一次长命令，30 分钟后就从上下文里清掉，但对话历史保留。
3.5 bootstrapMaxChars：控制文件注入大小
agents.defaults.bootstrapMaxChars默认 20000 字符，控制 workspace 文件注入时的截断阈值。OpenClaw 默认会注入这些文件（如果存在）：AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md（仅首次运行）。
这些文件如果写得很大，注入时就会吃掉大量 token。用/context命令能看到原始大小 vs 注入大小，以及是否发生截断。
"bootstrapMaxChars": 20000如果你发现 workspace 文件注入占比很高，要么精简文件内容，要么调小这个值。
3.6 完整配置示例
把上面几块拼起来，一个带三层防护的openclaw.json大概是这样：
{ "models": { "mode": "merge", "providers": { "taotoken": { "baseUrl": "https://taotoken.net/api", "apiKey": "<YOUR_TAOTOKEN_API_KEY>", "api": "openai-completions", "models": [ { "id": "<YOUR_MODEL_ID>", "name": "TaoToken Model", "contextWindow": 128000, "maxTokens": 4096 } ] } } }, "agents": { "defaults": { "model": { "primary": "taotoken/<YOUR_MODEL_ID>" }, "workspace": "~/.openclaw/workspace", "contextTokens": 100000, "bootstrapMaxChars": 20000, "compaction": { "reserveTokensFloor": 16000, "memoryFlush": { "enabled": true, "softThresholdTokens": 26000, "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." } }, "contextPruning": { "mode": "cache-ttl", "ttl": "30m" }, "subagents": { "maxConcurrent": 2, "model": "taotoken/<YOUR_MODEL_ID>" } } }, "session": { "maintenance": { "mode": "warn", "pruneAfter": "30d", "maxEntries": 500 } } }注意session.maintenance.mode从enforce改成warn，pruneAfter从 7d 放宽到 30d。原因是磁盘上的会话文件清理交给 compaction 处理更合理，过早删文件反而丢历史。
4. 验证请求与成功结果：用 /context 和 /usage 确认机制生效
配置写完不算完，得验证。OpenClaw 提供了几个诊断命令，我平时用这几个：
/status # 当前上下文占用 /context list # 谁在占空间 /context detail # 精细分析，分解最大的工具 schema /usage tokens # 正常回复后附加每次回复的 token 使用量推荐流程是/context list找最大项，然后针对性优化。
4.1 观察窗口占用
先跑/status，看当前上下文占了多少。然后跑/context list，它会列出各个来源的占用，比如 system prompt、conversation、tool schemas、skills、workspace files。
我第一次跑的时候发现 tool schemas 占了将近 40%，比我预想的高很多。因为每个工具的 JSON schema 都要发给模型，工具越多，这块越大。
4.2 触发压缩阈值
想验证 compaction 是否生效，可以故意把contextTokens设小一点，比如设成 3000，然后连续对话几轮，观察是否触发压缩。
触发时你会看到类似日志：
[compaction] reserve tokens below floor, starting compaction [compaction] summarized 12 messages into 1 summary entry [memoryFlush] archived key info to memory/2025-01-15.md如果没看到，检查reserveTokensFloor是不是设得比实际剩余空间还小，那样永远不会触发。
4.3 裁剪前后行为对比
验证 contextPruning，可以跑一个返回大输出的工具，比如读一个大文件，然后等 TTL 过期（上面配的是 30m，测试时可以临时改成 1m），再跑/context list，看 tool results 那块是不是变小了。
对比前后两次/context detail的输出，能明显看到大输出缓存被清掉，但对话历史还在。
4.4 成功结果长什么样
配置正确、机制生效的情况下，长会话跑下来应该是这样：
/status显示的占用稳定在 contextTokens 以下，不会无限增长- 触发 compaction 后，占用明显下降，对话能继续
- 不再出现 context_length_exceeded 报错
- 模型不会因为上下文超限崩溃或 reload
如果这几点都满足，说明三层防护都起作用了。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
配置过程中最容易撞的几个报错，逐个说。
5.1 401 Unauthorized
Error: 401 Unauthorized这个基本就是 API Key 问题。检查apiKey字段是不是填对了，有没有多余空格，是不是复制的时候漏了字符。如果用的是 TaoToken，去 API Keys 页 重新生成一个，贴进去再试。
还有一种情况是 Base URL 写错了，比如多加了斜杠或者少了/v1。TaoToken 的 Base URL 是https://taotoken.net/api，OpenClaw 会自动补全路径，别自己加/v1。
5.2 local proxy failed
Error: local proxy failed这个通常出现在本地推理服务没启动，或者端口不对。检查baseUrl里的端口，比如http://127.0.0.1:1234/v1，确认 LM Studio 或 Ollama 确实在 1234 端口监听。
如果本地服务正常，但 OpenClaw 还是报这个，检查是不是防火墙拦了本地回环请求。
5.3 reading choices 报错
Error: reading 'choices'这个一般是 provider 返回的响应格式和 OpenClaw 预期的不一致。常见原因是api字段填错了，比如填了openai-completions但实际服务返回的是另一种格式。
确认api字段和 provider 实际协议匹配。TaoToken 用openai-completions就行。
5.4 OAuth 相关报错
Error: OAuth token expired Error: OAuth flow failed如果你用的是需要 OAuth 的 provider，token 过期会报这个。重新走一遍授权流程，或者换成 API Key 方式接入。
5.5 上下文还是溢出
如果配置都对了，还是溢出，按这个优先级排查：
- 先看
/context detail，找最大的项 - 如果是 tool schemas 占大头，减少工具数量，或者禁用不用的工具
- 如果是 workspace 文件注入占大头，精简文件或调小
bootstrapMaxChars - 确认 compaction 真的触发了，看日志有没有
[compaction]输出 - 确认
contextWindow和后端实际上下文一致，这是最常见的坑
优化优先级建议：减少 Tool schemas → 控制 workspace 文件注入 → 开启 compaction → 设置合适的 contextWindow 和 contextTokens → 最后才是 pruning。
6. 把 Context 控制跑通之后：几个实用技巧
配置跑通之后，有几个我平时用的技巧。
第一，/context detail要养成习惯定期跑。工具 schema 的占用会随着你装新工具变化，隔一段时间看一眼，能提前发现膨胀。
第二，compaction 的reserveTokensFloor别设太小。我试过设 500，结果压缩操作本身没空间执行，直接崩。后来改成 contextTokens 的 15%，稳定多了。
第三，memoryFlush 的softThresholdTokens和reserveTokensFloor的差值保持在 10000 左右。差值太小，memory 还没写完就触发压缩；差值太大，memory 写入太早，浪费空间。
第四，本地推理的contextWindow一定要和后端n_ctx对齐。这个坑我踩过不止一次，症状是模型跑着跑着突然 reload，日志里啥也没有，就是上下文超了后端 KV Cache。
第五，如果你要长期跑 Agent 任务，会话轮次多，建议用 Coding Plan，避免跑到一半配额不够，compaction 做到一半中断，反而丢历史。
最后，所有配置改完记得重启 OpenClaw Gateway，openclaw.json不是热加载的。重启后先跑/status确认配置生效，再开始长会话测试。
