#context-guardian #token #compaction #context-window

Context Guardian

智能上下文保护插件：主动管理 tool result 大小、监控 context window 压力、自动触发压缩

Install

openclaw plugins install clawhub:openclaw-context-guardian

Context Guardian 🛡️

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

功能（v5）

🛡️ Context 压力监控 — 实时估算完整上下文的 token 用量（系统提示 + 对话历史 + tool call 结果），到达阈值自动触发压缩
✂️ 实时微压缩（Micro-compact） — 根据上下文压力级别自动调整：
- low（低压） — 不压缩，保留完整 tool result
- warn（警戒） — 超过 microCompactMaxChars × 2.5 时截断
- critical（临界） — 超过 microCompactMaxChars 时截断保留头部 + 尾部关键信息，截断处插入明确提示
✂️ Exec 输出自动限流 — 对大输出命令自动追加 | head -200，避免意外撑爆上下文
📊 大结果告警 — 超过 maxToolResultChars 的 tool result 会在日志中告警

安装

bash

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

配置

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

json

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

配置项说明

v5 基础配置

参数	类型	默认值	说明
`maxToolResultChars`	number	8000	单个 tool result 最大字符数，超过则告警
`compactionThreshold`	number	0.45	预估 tokens 达到 effectiveContextWindow 的此比例时触发 /compact
`warnThreshold`	number	0.40	预估 tokens 达到此比例时进入 warn 压力级别
`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	调试日志

v5 微压缩配置

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

典型场景

中转服务上下文较小

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

json

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

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

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

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

json

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

工作原理

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

before_tool_call — 拦截 exec 命令，自动追加输出限制
after_tool_call —
- 追踪每次 tool call 的结果大小和 token 开销
- 实时微压缩：根据当前上下文压力级别决定是否压缩
  - low 压力：不压缩
  - warn 压力：超过 microCompactMaxChars × 2.5 时截断
  - critical 压力：超过 microCompactMaxChars 时截断
- 按工具类型区分策略：查询类（exec/read/find 等）可压缩，修改类（edit/write）默认保留完整
- 截断处自动插入「📝 [信息被截断...]」提示语
before_prompt_build — 检查当前上下文压力，压力高时注入简化提示

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

Changelog

v5 — 压力分档微压缩 + 默认值优化

微压缩改按压力级别分档：
- low 压力不压缩，保留完整结果
- warn 压力阈值提升至 microCompactMaxChars × 2.5
- critical 压力阈值保持 microCompactMaxChars
截断处插入明确提示语（「📝 [信息被截断...]」）
优化默认值：compactionThreshold 0.75→0.45，warnThreshold 0.45→0.40，microCompactMaxChars 6000→10000

v3 — Micro-compact

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

v2 — 初始发布

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

开发

bash

cd context-guardian
npm install
npx tsc

License

MIT