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) |

Symptom	Go to
Every turn is expensive, even simple ones	Fix 1 (bootstrap)
Cost spikes after searches or file reads

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（工具输出） |

症状	操作
每次轮次都很昂贵，即使是简单轮次	修复 1（引导文件）
搜索或文件读取后成本飙升

完整激进一体化配置见 references/aggressive-config.md。
完整命令速查表见 references/commands.md。

context-optimizer上下文优化器