上下文守护者 🛡️

您的上下文守护者。在错误发生前发出预警。

主动式上下文监控，在上下文使用率达到 60%、70% 和 85% 时提前告警——防止因上下文污染引发错误与幻觉。

为何需要此功能

问题所在：

• 长对话导致上下文污染
• 随着上下文逐渐填满，响应质量悄然下降
• 您无法预知何时应重启会话，往往发现时已为时过晚
• 上下文使用率超过约 70% 后，错误与幻觉显著增加

解决方案：

• 持续监控上下文使用率
• 智能三级告警（⚠️ 60%、🟠 70%、🔴 85%）
• 每级均提供可操作建议
• 避免重复告警

快速开始

面向 Agent：心跳集成

当收到心跳轮询（heartbeat poll）时，请加入如下检查逻辑：

1. 调用 session_status 工具获取当前上下文使用率
2. 从输出中解析上下文使用百分比
3. 与阈值比较：60%（警告）、70%（危险）、85%（严重）
4. 若超出阈值且非重复告警，则显示对应级别的告警消息
5. 更新状态文件以记录告警历史

实现逻辑：

心跳执行期间：
1. 通过 session_status 获取上下文使用率
2. 检查使用率是否 ≥ 60%、70% 或 85%
3. 从 memory/context-guardian-state.json 加载状态
4. 判断是否应发送告警（防止重复）
5. 若需发送，则显示告警并更新状态

面向用户：在 HEARTBEAT.md 中启用

在您的 HEARTBEAT.md 文件中添加以下内容：

## Context Monitoring
- Check context usage
- Alert if thresholds exceeded (60%, 70%, 85%)

Agent 将自动处理其余所有逻辑。

工作原理

监控机制

该技能调用 session_status 工具，获取当前上下文使用率百分比。

告警等级

⚠️ 警告（60%）

⚠️ Context: 60%
上下文即将饱和。建议尽快收尾当前任务，或开启新会话。

🟠 危险（70%）

🟠 Context: 70%
上下文污染风险上升。建议：
• 完成当前任务
• 下一任务使用新会话启动
• 或使用 context-optimizer 压缩上下文

🔴 严重（85%）

🔴 Context: 85% - CRITICAL
错误风险极高。强烈建议：
• 保存当前工作
• 立即启动新会话
• 响应质量很可能已下降

智能防重复机制

该技能追踪告警历史，仅在以下情形触发告警：

1. 首次达到某阈值
2. 告警等级升级（如由 60% → 70% → 85%）
3. 使用率曾低于阈值后再次回升至阈值及以上

配置说明

编辑 config/default.json，或新建 config/user.json：

{
  "enabled": true,
  "checkInterval": "heartbeat",
  "thresholds": {
    "warning": 60,
    "danger": 70,
    "critical": 85
  },
  "alertMethod": "message",
  "alertStyle": "emoji",
  "preventDuplicates": true,
  "trackHistory": true,
  "suggestions": {
    "autoSuggest": true,
    "suggestCompression": true,
    "suggestRestart": true
  }
}

配置项说明

checkInterval：

• "heartbeat" — 在心跳轮询期间检查（默认）
• "cron" — 独立 cron 任务（未来支持）
• number — 每 N 分钟检查一次（未来支持）

thresholds：

• 自定义各告警级别阈值（默认：60、70、85）

alertMethod：

• "message" — 以消息形式发送（默认）
• "log" — 仅记录日志
• "notification" — 系统通知（未来支持）

alertStyle：

• "emoji" — Emoji + 简明文本（默认）
• "text" — 纯文本
• "detailed" — 完整说明

手动检查

您可手动检查上下文状态：

bash {baseDir}/scripts/check.sh

与其他技能的集成

context-optimizer

当上下文使用率达 70% 时，该技能将建议使用 context-optimizer 压缩上下文，而非直接重启会话。

context-recovery

完成上下文恢复后，该技能将自动恢复监控。

Agent 实现指南

分步流程

1. 获取上下文使用率

调用 session_status 工具并解析其输出：

示例输出："Context: 54k/200k (27%)"
提取结果：27

2. 判定告警等级

if (usage >= 85) level = "critical"
else if (usage >= 70) level = "danger"
else if (usage >= 60) level = "warning"
else level = null

3. 加载状态

读取 {workspace}/memory/context-guardian-state.json：

{
  "lastCheck": 1709452800,
  "lastUsage": 54,
  "lastAlertLevel": "warning",
  "lastAlertTime": 1709452500,
  "history": [...]
}

4. 判断是否应告警

防止重复告警：

shouldAlert = false

// 首次达到阈值
if (!lastAlertLevel && level) shouldAlert = true

// 告警等级升级（warning → danger → critical）
if (levelNum[level] > levelNum[lastAlertLevel]) shouldAlert = true

// 使用率曾低于阈值（容差 5%）后再次回升至阈值及以上
if (lastUsage < threshold - 5 && usage >= threshold) shouldAlert = true

5. 发送告警

若 shouldAlert 为真，则显示对应告警消息：

⚠️ Context: 60%
Getting full. Consider wrapping up or starting fresh soon.

6. 更新状态

将新状态写入 memory/context-guardian-state.json：

{
  "lastCheck": ,
  "lastUsage": ,
  "lastAlertLevel": ,
  "lastAlertTime": ,
  "history": [..., {"timestamp": , "usage": }]
}

告警消息模板

警告（60%）：

⚠️ Context: 60%
Getting full. Consider wrapping up or starting fresh soon.

危险（70%）：

🟠 Context: 70%
Pollution risk rising. Recommend:
• Finish current task
• Start new session for next task
• Or compress with context-optimizer

严重（85%）：

🔴 Context: 85% - CRITICAL
High error risk. STRONGLY recommend:
• Save work
• Start new session NOW
• Quality degradation likely

状态管理

状态存储于 {workspace}/memory/context-guardian-state.json：

{
  "lastCheck": 1709452800,
  "lastUsage": 54,
  "lastAlertLevel": null,
  "lastAlertTime": null,
  "history": [
    {"timestamp": 1709452800, "usage": 54}
  ]
}

故障排查

未出现任何告警：

• 确认 HEARTBEAT.md 中已包含上下文监控条目
• 验证心跳机制正在正常运行
• 检查状态文件是否存在格式或权限错误

告警过于频繁：

• 在配置中适当提高阈值
• 确认 preventDuplicates 已启用

告警数值不准确：

• 验证 session_status 工具是否正常工作
• 检查 OpenClaw 版本兼容性（需 2026.2.0+）

示例

心跳集成示例

在 HEARTBEAT.md 中添加：

## Context Monitoring
- Check context usage
- Alert if thresholds exceeded

自定义阈值示例

新建 config/user.json：

{
  "thresholds": {
    "warning": 50,
    "danger": 65,
    "critical": 80
  }
}

技术细节

依赖项：

• OpenClaw 2026.2.0+
• session_status 工具
• Bash

性能表现：

• 零开销（仅在心跳周期内执行检查）
• 状态存储极小（约 1KB）

隐私保障：

• 所有数据本地存储
• 无任何外部网络请求
• 不采集遥测数据

路线图

v1.1.0：

• 历史趋势追踪
• 使用率预测能力
• 独立 cron 模式支持

v1.2.0：

• 自动触发 context-optimizer
• 可视化趋势图表
• 多会话协同监控

参与贡献

发现 Bug？有改进建议？欢迎在 GitHub 上提交 Issue 或 Pull Request。

许可证

MIT