Context Optimizer
Goal: cut input tokens to the minimum that preserves task quality.
Principle: diagnose → apply the single highest-impact fix → re-measure → repeat.
Fast path — use the script
Use the bundled script to audit and apply defaults quickly:
CODEBLOCK0
The script auto-detects config path, validates after writing, and rolls back on failure. Use --config <path> for a specific file.
After running, verify with /status and /usage tokens.
Step 1 — Diagnose (manual path)
If script use is not enough or unavailable, run:
CODEBLOCK1
Identify the dominant sink: bootstrap, tool output, memory retrieval, or long-session buildup.
Step 2 — Apply fixes in impact order
Work top-down and stop when usage is acceptable.
Fix 1: Shrink bootstrap files
Trim AGENTS.md, SOUL.md, TOOLS.md, USER.md, MEMORY.md, and heavy skill files. Remove filler and move rarely-needed detail into references read on demand.
Set smaller bootstrap/image limits and related defaults. See references/configs.md for full config examples.
Fix 2: Throttle tool output
Reduce web search/fetch payloads and prefer targeted reads (line ranges/excerpts) over full dumps.
See references/configs.md for full config examples.
Fix 3: Prune stale tool results
Enable context pruning so older, large tool payloads expire automatically while recent turns stay intact.
See references/configs.md for full config examples.
Fix 4: Tighten memory retrieval
Lower recall volume and raise relevance thresholds; keep deduplication and recency bias enabled. Narrow memorySearch.extraPaths if too broad.
See references/configs.md for full config examples.
Fix 5: Session hygiene
Use /compact mid-session, /new for topic shifts, /reset when recovery is unlikely. Enable automatic compaction for sessions that routinely run long.
See references/configs.md for full config examples.
Step 3 — Validate
After each change:
- 1. Run
openclaw config validate. - Restart gateway if prompted.
- Re-check
/status and /usage tokens. - Spot-check recall on a representative task.
- If quality drops, loosen the most recent change one notch.
Quick-reference: symptom → fix
| Symptom | Go to |
|---|
| Every turn is expensive, even simple ones | Fix 1 (bootstrap) |
| Cost spikes after searches or file reads |
Fix 2 (tool output) |
| Long sessions get slow/truncated | Fix 3 (pruning) + Fix 5 (session hygiene) |
| Memory results feel noisy or irrelevant | Fix 4 (memory retrieval) |
| Screenshots are costly | Fix 1, set
imageMaxDimensionPx: 512 |
| "Context too large" / truncation errors | Fix 5 (
/compact or
/new), then Fix 3 |
See references/aggressive-config.md for the full aggressive all-in-one config.
See references/commands.md for the full commands cheat sheet.
上下文优化器
目标：将输入令牌削减至保持任务质量所需的最小值。
原则：诊断 → 应用单一最高影响修复 → 重新测量 → 重复。
快速路径——使用脚本
使用捆绑脚本快速审计并应用默认设置：
bash
python scripts/context_optimizer.py
python scripts/context_optimizer.py --apply
python scripts/context_optimizer.py --apply --aggressive
该脚本自动检测配置路径，写入后验证，失败时回滚。使用 --config <路径> 指定特定文件。
运行后，通过 /status 和 /usage tokens 验证。
步骤 1——诊断（手动路径）
如果脚本使用不足或不可用，请运行：
/status
/context detail
/usage tokens
识别主要消耗源：引导文件、工具输出、记忆检索或长会话累积。
步骤 2——按影响顺序应用修复
从上到下操作，当使用量可接受时停止。
修复 1：缩小引导文件
精简 AGENTS.md、SOUL.md、TOOLS.md、USER.md、MEMORY.md 和大型技能文件。删除填充内容，将很少需要的细节移至按需读取的参考资料中。
设置更小的引导/图像限制及相关默认值。完整配置示例见 references/configs.md。
修复 2：限制工具输出
减少网络搜索/获取负载，优先使用定向读取（行范围/摘录）而非完整转储。
完整配置示例见 references/configs.md。
修复 3：清理过时工具结果
启用上下文修剪，使较旧的大型工具负载自动过期，同时保持近期轮次完整。
完整配置示例见 references/configs.md。
修复 4：收紧记忆检索
降低召回量并提高相关性阈值；保持去重和近期偏差启用。如果 memorySearch.extraPaths 过于宽泛，则缩小范围。
完整配置示例见 references/configs.md。
修复 5：会话卫生
在会话中使用 /compact，主题切换时使用 /new，恢复无望时使用 /reset。为经常运行较长的会话启用自动压缩。
完整配置示例见 references/configs.md。
步骤 3——验证
每次更改后：
- 1. 运行 openclaw config validate。
- 如果提示，重启网关。
- 重新检查 /status 和 /usage tokens。
- 在代表性任务上抽查召回效果。
- 如果质量下降，将最近的更改回调一级。
快速参考：症状 → 修复
| 症状 | 操作 |
|---|
| 每次轮次都很昂贵，即使是简单轮次 | 修复 1（引导文件） |
| 搜索或文件读取后成本飙升 |
修复 2（工具输出） |
| 长会话变慢/被截断 | 修复 3（修剪）+ 修复 5（会话卫生） |
| 记忆结果感觉嘈杂或不相关 | 修复 4（记忆检索） |
| 截图成本高昂 | 修复 1，设置 imageMaxDimensionPx: 512 |
| 上下文过大/截断错误 | 修复 5（/compact 或 /new），然后修复 3 |
完整激进一体化配置见 references/aggressive-config.md。
完整命令速查表见 references/commands.md。
