Context Guardian 🛡️

智能上下文保护插件。自动管理 tool result 大小、监控 context window 压力、在溢出前主动保护。

功能（v3）

🛡️ Context 压力监控 — 实时估算完整上下文的 token 用量（系统提示 + 对话历史 + tool call 结果），到达阈值提示压缩
✂️ 实时微压缩（Micro-compact） — 工具结果超过阈值时自动截断，保留头部+尾部关键信息，减少上下文膨胀
✂️ Exec 输出自动限流 — 对大输出命令自动追加 | head -200，避免意外撑爆上下文
📊 大结果告警 — 超过 maxToolResultChars 的 tool result 会在日志中告警
💬 智能提示注入 — 上下文压力超过 warnThreshold 时，在 system prompt 中加入简化提醒
🧹 Session 自动清理 — 过期无活动的 session state 自动释放，无内存泄漏
🔧 全参数可配置 — 所有阈值和开关都可通过插件配置调整

安装

# 从 ClawHub 安装
openclaw plugins install clawhub:context-guardian

配置

在 openclaw.json 的 plugins.entries.context-guardian.config 中设置：

{
  "plugins": {
    "entries": {
      "context-guardian": {
        "enabled": true,
        "config": {
          "maxToolResultChars": 8000,
          "compactionThreshold": 0.75,
          "warnThreshold": 0.5,
          "effectiveContextWindow": 0,
          "baseOverheadTokens": 15000,
          "perTurnOverheadTokens": 1200,
          "autoLimitExecOutput": true,
          "execMaxLines": 200,
          "microCompactEnabled": true,
          "microCompactMaxChars": 6000,
          "microCompactPreserveHeadRatio": 0.4,
          "microCompactPreserveTailRatio": 0.2,
          "microCompactPreserveEditTools": true,
          "debug": false
        }
      }
    }
  }
}

配置项说明

v2 基础配置

参数	类型	默认值	说明
`maxToolResultChars`	number	8000	单个 tool result 最大字符数，超过则告警
`compactionThreshold`	number	0.75	预估 tokens 达到 effectiveContextWindow 的此比例时提示 /compact
`warnThreshold`	number	0.45	预估 tokens 达到此比例时在 prompt 注入压力提示
`effectiveContextWindow`	number	0	实际上下文窗口。0 表示从运行时 contextTokens 自动读取
`baseOverheadTokens`	number	15000	系统提示 + 工具 schema 等的预估 token 开销
`perTurnOverheadTokens`	number	1200	每轮对话的预估 token 开销
`autoLimitExecOutput`	boolean	true	是否自动限制 exec 输出行数
`execMaxLines`	number	200	exec 命令最大输出行数
`compactionCooldownMs`	number	60000	两次提示压缩之间的最短间隔（毫秒）
`debug`	boolean	false	调试日志

v3 微压缩配置

参数	类型	默认值	说明
`microCompactEnabled`	boolean	true	是否启用实时微压缩
`microCompactMaxChars`	number	6000	工具结果超过此字符数时触发微压缩
`microCompactPreserveHeadRatio`	number	0.4	微压缩时保留开头内容的比例 (0-1)
`microCompactPreserveTailRatio`	number	0.2	微压缩时保留尾部内容的比例 (0-1)
`microCompactPreserveEditTools`	boolean	true	是否保留 edit/write 等修改类工具的完整结果

典型场景

中转服务上下文较小

如果通过中转服务使用模型（如 baotaai），实际上下文可能只有 64K 而非配置的 1M：

{
  "config": {
    "effectiveContextWindow": 64000,
    "compactionThreshold": 0.35
  }
}

这样在本地预估约 22K tokens 时就会提示压缩，避免服务端溢出。

激进微压缩（大量查询场景）

如果经常执行 find、ls 等返回大量结果的查询：

{
  "config": {
    "microCompactMaxChars": 4000,
    "microCompactPreserveHeadRatio": 0.3,
    "microCompactPreserveTailRatio": 0.1
  }
}

工作原理

插件通过三个生命周期钩子工作：

before_tool_call — 拦截 exec 命令，自动追加输出限制
after_tool_call —
- 追踪每次 tool call 的结果大小和 token 开销
- 实时微压缩：超过 microCompactMaxChars 的工具结果自动截断（保留头部+尾部）
- 按工具类型区分策略：查询类（exec/read/find 等）可压缩，修改类（edit/write）默认保留完整
before_prompt_build — 检查当前上下文压力，压力高时注入简化提示

Token 估算公式：baseOverhead + turnCount × perTurnOverhead + Σ(toolName + params + result tokens)

Changelog

v3 — Micro-compact

新增实时微压缩：工具结果超过阈值自动截断，减少上下文膨胀
按工具类型区分压缩策略（查询类可压缩，修改类保留完整）
支持配置保留比例和阈值
修复 6 个 bug（token 估算、内存泄漏、正则误伤等）

v2 — 初始发布

Context 压力监控与自动压缩提示
Exec 输出自动限流
大结果告警

开发

cd context-guardian
npm install
npx tsc

License

MIT

Context Guardian