Context Guardian 🛡️
Your context guardian. Alerts before errors happen.
Proactive context monitoring that warns you at 60%, 70%, and 85% usage — before context pollution causes errors and hallucinations.
Why You Need This
The Problem:
- - Long conversations lead to context pollution
- Quality degrades silently as context fills up
- You don't know when to restart until it's too late
- Errors and hallucinations increase after ~70% usage
The Solution:
- - Continuous monitoring of context usage
- Smart 3-level alerts (⚠️ 60%, 🟠 70%, 🔴 85%)
- Actionable suggestions at each level
- Prevents duplicate alerts
Quick Start
For Agents: Heartbeat Integration
When you receive a heartbeat poll, include this check:
- 1. Call
session_status tool to get current context usage - Parse the context percentage from the output
- Compare against thresholds: 60% (warning), 70% (danger), 85% (critical)
- If threshold exceeded and not a duplicate alert, display the appropriate alert message
- Update state file to track alert history
Implementation:
CODEBLOCK0
For Users: Enable in HEARTBEAT.md
Add to your HEARTBEAT.md:
CODEBLOCK1
The agent will automatically handle the rest.
How It Works
Monitoring
The skill calls session_status to check your current context usage percentage.
Alert Levels
⚠️ Warning (60%)
CODEBLOCK2
🟠 Danger (70%)
CODEBLOCK3
🔴 Critical (85%)
CODEBLOCK4
Smart Duplicate Prevention
The skill tracks alert history and only alerts when:
- 1. First time reaching a threshold
- Alert level upgrades (60% → 70% → 85%)
- Usage drops below threshold then rises again
Configuration
Edit config/default.json or create config/user.json:
CODEBLOCK5
Options
checkInterval:
- -
"heartbeat" - Check during heartbeat polls (default) - INLINECODE6 - Independent cron job (future)
- INLINECODE7 - Check every N minutes (future)
thresholds:
- - Customize alert levels (default: 60, 70, 85)
alertMethod:
- -
"message" - Send as message (default) - INLINECODE9 - Log only
- INLINECODE10 - System notification (future)
alertStyle:
- -
"emoji" - Emoji + concise text (default) - INLINECODE12 - Plain text
- INLINECODE13 - Full explanation
Manual Check
You can manually check context status:
CODEBLOCK6
Integration with Other Skills
context-optimizer
When you reach 70%, the skill suggests using context-optimizer to compress your context instead of restarting.
context-recovery
After context recovery, the skill automatically resumes monitoring.
Implementation Guide for Agents
Step-by-Step Process
1. Get Context Usage
Call session_status tool and parse the output:
CODEBLOCK7
2. Determine Alert Level
CODEBLOCK8
3. Load State
Read {workspace}/memory/context-guardian-state.json:
CODEBLOCK9
4. Check if Should Alert
Prevent duplicate alerts:
CODEBLOCK10
5. Send Alert
If shouldAlert, display the appropriate message:
CODEBLOCK11
6. Update State
Save new state to memory/context-guardian-state.json:
CODEBLOCK12
Alert Messages
Warning (60%):
CODEBLOCK13
Danger (70%):
CODEBLOCK14
Critical (85%):
🔴 Context: 85% - CRITICAL
High error risk. STRONGLY recommend:
• Save work
• Start new session NOW
• Quality degradation likely
State Management
State is stored in {workspace}/memory/context-guardian-state.json:
CODEBLOCK16
Troubleshooting
No alerts appearing:
- - Check that
HEARTBEAT.md includes context monitoring - Verify heartbeat is running
- Check state file for errors
Too many alerts:
- - Increase thresholds in config
- Check
preventDuplicates is enabled
Alerts not accurate:
- - Verify
session_status is working - Check OpenClaw version compatibility
Examples
Heartbeat Integration
Add to HEARTBEAT.md:
CODEBLOCK17
Custom Thresholds
Create config/user.json:
CODEBLOCK18
Technical Details
Dependencies:
- - OpenClaw 2026.2.0+
- INLINECODE25 tool
- Bash
Performance:
- - Zero overhead (only checks during heartbeat)
- Minimal state storage (~1KB)
Privacy:
- - All data stored locally
- No external calls
- No telemetry
Roadmap
v1.1.0:
- - Historical trend tracking
- Usage prediction
- Independent cron mode
v1.2.0:
- - Auto-trigger context-optimizer
- Visual trend graphs
- Multi-session monitoring
Contributing
Found a bug? Have a suggestion? Open an issue or PR on GitHub.
License
MIT
上下文守护者 🛡️
您的上下文守护者。在错误发生前发出警报。
主动式上下文监控，在上下文使用率达到60%、70%和85%时发出警告——在上下文污染导致错误和幻觉之前。
为什么需要它
问题：
- - 长对话导致上下文污染
- 随着上下文填满，质量悄然下降
- 您不知道何时该重新开始，直到为时已晚
- 使用率超过70%后，错误和幻觉增加
解决方案：
- - 持续监控上下文使用率
- 智能三级警报（⚠️ 60%、🟠 70%、🔴 85%）
- 每个级别提供可操作建议
- 防止重复警报
快速开始
对于智能体：心跳集成
当您收到心跳轮询时，包含此检查：
- 1. 调用 session_status 工具获取当前上下文使用率
- 从输出中解析上下文百分比
- 与阈值比较：60%（警告）、70%（危险）、85%（严重）
- 如果超过阈值且不是重复警报，显示相应的警报消息
- 更新状态文件以跟踪警报历史
实现：
心跳期间：
- 1. 从 session_status 获取上下文使用率
- 检查使用率是否 >= 60%、70% 或 85%
- 从 memory/context-guardian-state.json 加载状态
- 确定是否应发送警报（防止重复）
- 如果是，显示警报并更新状态
对于用户：在 HEARTBEAT.md 中启用
添加到您的 HEARTBEAT.md：
markdown
上下文监控
- - 检查上下文使用率
- 如果超过阈值（60%、70%、85%）则发出警报
智能体将自动处理其余部分。
工作原理
监控
该技能调用 session_status 来检查您当前的上下文使用率百分比。
警报级别
⚠️ 警告（60%）
⚠️ 上下文：60%
即将填满。建议尽快收尾或重新开始。
🟠 危险（70%）
🟠 上下文：70%
污染风险上升。建议：
• 完成当前任务
• 为下一个任务开始新会话
• 或使用 context-optimizer 进行压缩
🔴 严重（85%）
🔴 上下文：85% - 严重
错误风险高。强烈建议：
• 保存工作
• 立即开始新会话
• 质量可能下降
智能重复预防
该技能跟踪警报历史，仅在以下情况发出警报：
- 1. 首次达到阈值
- 警报级别升级（60% → 70% → 85%）
- 使用率降至阈值以下后再次上升
配置
编辑 config/default.json 或创建 config/user.json：
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 - 独立定时任务（未来）
- number - 每N分钟检查一次（未来）
thresholds：
alertMethod：
- - message - 作为消息发送（默认）
- log - 仅记录日志
- notification - 系统通知（未来）
alertStyle：
- - emoji - 表情符号 + 简洁文本（默认）
- text - 纯文本
- detailed - 完整说明
手动检查
您可以手动检查上下文状态：
bash
bash {baseDir}/scripts/check.sh
与其他技能的集成
context-optimizer
当您达到70%时，该技能建议使用 context-optimizer 压缩上下文，而不是重新开始。
context-recovery
上下文恢复后，该技能自动恢复监控。
智能体实现指南
分步流程
1. 获取上下文使用率
调用 session_status 工具并解析输出：
示例输出：Context: 54k/200k (27%)
提取：27
2. 确定警报级别
javascript
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：
json
{
lastCheck: 1709452800,
lastUsage: 54,
lastAlertLevel: warning,
lastAlertTime: 1709452500,
history: [...]
}
4. 检查是否应发出警报
防止重复警报：
javascript
shouldAlert = false
// 首次达到阈值
if (!lastAlertLevel && level) shouldAlert = true
// 级别升级（warning → danger → critical）
if (levelNum[level] > levelNum[lastAlertLevel]) shouldAlert = true
// 使用率降至阈值以下后再次上升
if (lastUsage < threshold - 5 && usage >= threshold) shouldAlert = true
5. 发送警报
如果 shouldAlert，显示相应的消息：
⚠️ 上下文：60%
即将填满。建议尽快收尾或重新开始。
6. 更新状态
将新状态保存到 memory/context-guardian-state.json：
json
{
lastCheck: ,
lastUsage: ,
lastAlertLevel: ifalerted>,
lastAlertTime: ifalerted>,
history: [..., {timestamp: , usage: }]
}
警报消息
警告（60%）：
⚠️ 上下文：60%
即将填满。建议尽快收尾或重新开始。
危险（70%）：
🟠 上下文：70%
污染风险上升。建议：
• 完成当前任务
• 为下一个任务开始新会话
• 或使用 context-optimizer 进行压缩
严重（85%）：
🔴 上下文：85% - 严重
错误风险高。强烈建议：
• 保存工作
• 立即开始新会话
• 质量可能下降
状态管理
状态存储在 {workspace}/memory/context-guardian-state.json：
json
{
lastCheck: 1709452800,
lastUsage: 54,
lastAlertLevel: null,
lastAlertTime: null,
history: [
{timestamp: 1709452800, usage: 54}
]
}
故障排除
没有出现警报：
- - 检查 HEARTBEAT.md 是否包含上下文监控
- 验证心跳是否正在运行
- 检查状态文件是否有错误
警报过多：
- - 在配置中提高阈值
- 检查 preventDuplicates 是否启用
警报不准确：
- - 验证 session_status 是否正常工作
- 检查 OpenClaw 版本兼容性
示例
心跳集成
添加到 HEARTBEAT.md：
markdown
上下文监控
自定义阈值
创建 config/user.json：
json
{
thresholds: {
warning: 50,
danger: 65,
critical: 80
}
}
技术细节
依赖项：
- - OpenClaw 2026.2.0+
- session_status 工具
- Bash
性能：
- - 零开销（仅在心跳期间检查）
- 最小状态存储（约1KB）
隐私：
路线图
v1.1.0：
v1.2.0：
- - 自动触发 context-optimizer
- 可视化趋势图
- 多会话监控
贡献
发现错误？有建议？在 GitHub 上提交 issue 或 PR。
许可证
MIT
