上下文管理

防止上下文耗尽，严格执行子代理（sub-agent）生成纪律，并确保压缩（compaction）过程可恢复。

核心概念

1. 固定基线（Fixed baseline）：通常在任何对话开始前已占用 5–15% 的上下文空间——包括系统提示（system prompt）、工作区文件（workspace files）、技能描述（skill descriptions）、工具定义（tool definitions）。该值随配置而异（技能/文件越多，基线越高）。
2. 60/40 法则（60/40 rule）：已占用上下文中约 60% 来自工具输出，约 40% 来自对话内容。工具输出是节省空间的首要目标。
3. 压缩是有损的（Compaction is lossy）：摘要（summaries）会逐轮累积叠加。每执行一次压缩，上下文“底线”即随之抬高。经过 3 次以上压缩后，仅摘要本身就可能占据 30% 以上的上下文空间。
4. 子代理是可丢弃的上下文（Sub-agents are disposable context）：子代理可在其自身上下文中大量消耗资源用于调查；最终仅需将摘要（约 500 tokens）注入主上下文。

所有百分比均相对于模型的上下文窗口（context window）计算。请运行 session_status 查看实际窗口大小与当前使用量。

操作规程

当上下文压力升高时

每次执行重度调用工具的操作（>5 次工具调用）后，需进行如下评估：

1. 运行 session_status 查看当前使用率
2. 若 低于 50%：正常继续
3. 若 50–70%：对后续仍需重度调用工具的任务（>3 次工具调用）启用子代理
4. 若 70–85%：对任何涉及工具调用的任务（>1 次工具调用）均启用子代理，并向用户发出警告
5. 若 高于 85%：写入检查点（见下文），建议执行 /compact 或 /new

“什么正在吞噬我的上下文？”——估算方法

无法获得各组件精确的用量拆分，可按以下方式估算：

固定基线：         ~5–15%（system prompt + workspace files + skills + tools）
每条用户消息：     ~100–500 tokens
每条助手响应：     ~200–1000 tokens
每次工具调用结果： ~500–5000 tokens（exec/read 类型开销大，search 类型较轻）
压缩摘要：         ~2000–5000 tokens（具有累积性！）

统计近期历史中的消息数与工具调用次数，并乘以中位估值。结果以区间形式呈现，避免虚假精度。如需了解单次操作的具体开销，请查阅 references/operation-costs.md。

生成策略（Spawn Policy）

若工作区根目录存在 .context-policy.yml，则以其为依据设定生成阈值与任务分类；否则采用以下默认规则：

始终生成子代理（Always spawn）（无论当前上下文占用率如何）：

• 测试套件（>3 个测试）
• 多文件审计（>5 个文件）
• 构建/部署流水线（build/deploy pipelines）
• 研究类任务（网络搜索 + 分析）
• 批量文件操作

永不生成子代理（Never spawn）（保留在主会话中）：

• 单条命令
• 对话 / 讨论
• 快速编辑（1–3 个文件）
• 状态检查
• 执行过程中需用户中途输入的任务

依上下文动态决定（Context-dependent）（当上下文占用率超过阈值时生成）：

• 高于 50%：若任务涉及 >5 次工具调用，则生成
• 高于 70%：若任务涉及 >2 次工具调用，则生成

生成子代理时，请提供详尽的任务描述。子代理无任何对话上下文——它仅能感知 task 字段所明确告知的内容。

压缩前检查点（Pre-Compaction Checkpoint）

在执行压缩或 /new 前，请于工作区根目录下创建 .context-checkpoint.md（代理将在压缩完成后读取此文件）：

# 上下文检查点 — {date} {time}

## 当前任务
{你正在执行的操作}

## 关键状态
{当前状态要点列表 — 已完成事项、进行中事项}

## 本会话已做决策
{带理由说明的编号决策列表}

## 已修改文件
{本会话中被修改的文件列表}

## 下一步
{恢复后应执行的操作}

该文件可经受压缩过程保留。在会话启动或压缩完成后，请检查是否存在该文件，并据此恢复上下文。恢复后请立即删除该文件。

与 OpenClaw memoryFlush 协同说明：OpenClaw 可能触发自身的预压缩刷新（memoryFlush），将数据写入每日日志（daily log）。本检查点机制作为补充：memoryFlush 将数据存入每日日志，而检查点保存结构化的可恢复状态。二者应共存。若 memoryFlush 先被触发，压缩可能已处于进行中。对于关键会话，建议在上下文达 75% 时即主动写入检查点，切勿等到 85%。

scripts/context-checkpoint.sh 脚本支持基础的写入/读取/清除功能。如需完整五段式检查点，请直接手动编写该文件——多行内容在此场景下更易维护。

压缩后恢复流程（Post-Compaction Recovery）

压缩或执行 /new 后：

1. 若存在 .context-checkpoint.md，请先读取
2. 若工作区存在当日日志（例如 memory/{today}.md），请一并读取
3. 根据检查点中“下一步”（Next Steps）继续执行
4. 恢复上下文后，立即删除检查点文件

主动预警模板（Proactive Warning Template）

当上下文占用率超过 65% 时，发出如下警告：

⚠️ 上下文：{pct}%（{used}k/{total}k）。预计剩余容量：约 {remaining_calls} 次工具调用。{recommendation}

不同层级的推荐语：

• 65%：“将为后续重度工具调用任务启用子代理。”
• 75%：“建议尽快执行压缩。正在写入检查点。”
• 85%：“上下文已达临界状态。立即写入检查点。建议执行 /compact 或 /new。”

会话性能分析与配置建议

在完成大量工作后（或应用户请求），对当前会话进行性能分析，并提出配置优化建议。

步骤 1：识别会话模式

运行 session_status，粗略统计工具调用次数与消息交互轮数，归类如下：

步骤 2：配置建议

有四个关键配置项。向用户解释时，务必说明它们在实际使用中的效果，而非仅罗列参数名：

1. 何时压缩对话历史（reserveTokensFloor） 指上下文填充至何种程度时，代理自动对历史进行摘要与压缩。数值越大，压缩触发越早——生成的摘要越短，后续剩余空间越多。

• 30000 —— 等待几乎填满才压缩。风险：摘要体积巨大，压缩后剩余空间极小。
• 50000 —— 在约 75% 占用率时压缩。平衡性最佳。
• 60000 —— 在约 70% 占用率时提前压缩。预留空间最充裕。

2. 工具输出清理速度（pruning TTL） 在用户停止交互达此时间后，代理将从内存中清除旧的命令输出、文件读取结果与搜索结果。数值越小，清理越激进。

• 5m —— 需静默 5 分钟才触发清理。活跃工作中极少触发。
• 2m —— 静默 2 分钟即清理。适用于大多数工作流。
• 1m —— 极度激进。清理迅速，但可能导致需重复读取文件。

3. 受保护的最近交互轮数（keepLastAssistants） 执行工具输出清理时，保留最近的若干轮用户-助手交互不被清除。

• 3 —— 保留更多历史可见性，适合对话型任务。
• 2 —— 中等保护力度。
• 1 —— 仅最后 1 轮交互受保护。清理最彻底。

4. 工具输出裁剪的最小尺寸（minPrunableToolChars） 仅当工具输出长度（字符数）超过此值时，才允许被裁剪。数值越小，可清理的内容越多。

• 50000（默认）—— 仅裁剪极大输出（如超长文件读取、海量命令输出）。
• 10000 —— 同时裁剪中等规模输出，覆盖更广。
• 5000 —— 极度激进。绝大多数工具输出均符合条件。

按工作风格推荐的组合配置：

其他提示：

• 含浏览器/画布（browser/canvas）操作的会话：请确保相关工具在配置中被排除在清理范围之外
• 长时间运行的会话（>2 小时）：建议提高压缩触发阈值，以支撑多轮压缩周期

步骤 3：报告格式

采用紧凑列表格式——表格在移动端及窄聊天窗口中渲染效果差。对每个配置项，仅当当前值与推荐值不同时才展示对比；当前值已符合推荐时则跳过该条目。

📊 当前会话画像：{pattern}
上下文：{pct}%（{used}k/{total}k）· 已压缩次数：{c}

✅ 压缩触发时机 — {current_description}。适配当前工作风格。
✅ 清理旧输出延迟 — {current_description}。无需调整。
⚠️ 保护最近交互轮数 — 当前为 {current}，建议设为 {recommended}。{why}
✅ 裁剪输出阈值 — {current_description}。无需调整。

预计剩余容量：约 {time_or_calls} 后触发下次压缩。

优先列出已正确的配置（建立信任感），再突出需调整项及其原因。保持简洁——用户需要的是明确结论，而非长篇大论。

若建议修改配置，请在征求用户同意前，一次性完整告知全部信息：

1. 被修改的确切文件（完整路径——通过 gateway config.get 获取）
2. 确切的修改内容（参数名、当前值、新值）
3. 执行后果（网关重启，约 2–3 秒暂停，自动重连）
4. 安全兜底措施（首先备份配置文件，并将回滚文档写入临时目录）

示例结尾：

建议一项变更：
  文件：{config_path}
  修改：{setting_name}：{old_value} → {new_value}
  
执行操作意味着：我将先备份配置文件，再将回滚文档写入 {temp_path}，随后重启 OpenClaw 网关（约 2–3 秒暂停以重新加载）。是否继续？

若有多项变更，请逐条列出。切勿概括为“4 项变更”——必须明确写出每一项。

切勿在未向用户展示确切文件路径、确切参数值与确切影响的前提下，仅问“是否应用？”。用户须基于完整信息决策，而非盲目信任。

若用户同意，请严格遵循下方完整流程执行。

步骤 4：持续学习

提供建议后，请将本次会话模式与最终结果记录至每日日志（若工作区启用了该功能）。经多次会话积累，规律将逐渐显现——用户的典型工作风格将清晰浮现，从而可永久优化默认配置。

应用配置变更——强制规程

提出配置变更建议时，必须严格遵循以下顺序。严禁跳步或简化。

1. 定位配置文件

运行 gateway config.get 获取配置文件路径与当前值。切勿假设路径——其因安装方式而异。

2. 首先备份

cp  .backup-$(date +%Y%m%d-%H%M%S)

3. 编写回滚文档

将回滚文档写入用户可访问的位置（非代理工作区——用户可能无权访问该路径）。使用系统临时目录（Linux/macOS 下为 /tmp/，或系统默认临时目录）。内容包含：

# 上下文配置回滚 — {date}

## 变更内容
| 设置项 | 变更前 | 变更后 | 文件 |
|--------|--------|--------|------|
| {setting} | {old} | {new} | {config_path} |

## 备份位置
{config_path}.backup-{timestamp}

## 回滚方法
cp {backup_path} {config_path}

## 重启网关方法
取决于本地环境，请确认适用方式：
- CLI（最常见）：openclaw gateway restart
- systemd 服务：sudo systemctl restart 
- 手动进程：kill 网关进程后执行 openclaw gateway start

## 健康检查方法
- 进程是否运行：检查进程列表中是否存在 openclaw
- 网关是否响应：curl http://localhost:/health
- 日志查看：依据本地配置查看系统日志或终端输出

## 若网关无法启动的处理步骤
1. 恢复备份（执行上方 cp 命令）
2. 重启网关
3. 查看日志，定位配置解析错误

请明确告知用户该文件所在路径。

4. 应用前向用户说明

需向用户明确说明：

• 被修改的文件（完整路径——由 gateway config.get 获取）
• 变更的值（变更前 → 变更后表格）
• “重启”的含义——指 OpenClaw 网关进程重启（非整机重启，亦不影响其他服务）。短暂暂停 2–3 秒后，会话将自动重连。
• 备份文件位置（完整路径）
• 回滚文档位置（完整路径）
• 异常排查方法

5. 使用 gateway config.patch 应用变更

通过 gateway 工具调用 action: config.patch。务必提供清晰的 note 参数——该消息将在网关重启后送达用户。

6. 重启后确认（强制要求）

网关重启且会话重连后，必须立即向用户确认：

✅ 网关已恢复。配置变更已成功应用。

变更内容：
- {setting}：{old} → {new}（{通俗解释}）
- [等等]

回滚文档：{path}
备份文件：{path}

一切运行正常。可继续工作。

重启后绝不可沉默。用户必须明确知晓以下四点：

1. 我们已恢复在线
2. 变更已生效
3. 回滚文档存放位置
4. 我们已准备就绪，可继续工作

参考文档

详细配置选项与配置画像说明：references/config-guide.md 各操作开销估算：references/operation-costs.md