context-compactor

Context Compactor 是专为 OpenClaw 设计的上下文管理插件，旨在解决本地大语言模型（如 Ollama、llama.cpp、MLX）因不报告 Token 限制而导致的上下文截断、内容丢失等问题。与云 API 不同，本地模型往往会在超出上下文窗口时静默截断或返回乱码，而该插件通过客户端 Token 估算机制，在达到模型限制前主动对历史消息进行智能压缩，确保长对话的连贯性。

使用上，用户可通过 npx jasper-context-compactor setup 一键安装，插件会自动配置到 OpenClaw 的插件目录。核心配置包括 maxTokens（触发压缩的阈值）、keepRecentTokens（保留的近期消息 Token 数）和 charsPerToken（字符与 Token 比例，默认 4）。安装后，系统会在每次消息到达时自动估算上下文长度，当超过阈值时，将旧消息总结为摘要并与近期消息合并，形成新的上下文。用户还可通过 /compact-now 强制刷新压缩，或使用 /context-stats 查看当前 Token 使用状况。

该插件的显著优点在于其预防性设计：不同于依赖模型报错的后处理方案，它能在问题发生前主动干预，特别适合本地模型用户。此外，它支持灵活调参，可适配从 4K 到 32K 不同规模的上下文窗口，且提供缓存机制避免重复总结。然而，其局限性也值得注意：压缩后的摘要不会持久化保存（仅会话级），且基于字符数的 Token 估算（尤其是 CJK 语言）可能存在偏差，需要用户根据实际模型调整 charsPerToken 参数。

适合使用该技能的目标群体主要包括：使用 Ollama、LM Studio、MLX 等本地推理框架的开发者；需要处理长文档或多轮复杂对话的 AI 应用用户；以及对数据隐私敏感、希望完全本地运行而不依赖云 API 的人群。对于仅使用 Anthropic、OpenAI 等云 API 的用户，由于这些服务会明确报告上下文溢出错误，OpenClaw 内置的压缩机制已足够，无需额外安装此插件。

常规风险方面，该插件会修改用户的 OpenClaw 配置文件（~/.openclaw/openclaw.json）并在用户主目录创建备份和插件文件。虽然插件具备自动备份和交互式确认机制，但用户仍需注意配置文件的正确性，避免因配置错误导致 OpenClaw 启动失败。此外，过度激进的压缩参数（如过小的 keepRecentTokens）可能导致关键上下文信息丢失，影响对话质量。建议用户通过 /context-stats 监控使用情况，并根据模型实际表现逐步调优参数。

核心用法

Context Compactor 是 OpenClaw 生态的插件，专为本地大模型场景设计。安装后通过 npx jasper-context-compactor setup 一键配置，自动集成到 ~/.openclaw/extensions/。核心流程：在 before_agent_start 钩子触发时，估算当前会话 Token 数，若超过 maxTokens 阈值，则将较旧消息拆分并生成摘要，最终向 Agent 呈现「摘要 + 近期消息 + 新消息」的结构。

用户可通过 /context-stats 实时查看 Token 占用率，用 /compact-now 强制刷新摘要缓存。配置项支持灵活调参：针对 8K 模型的 MLX 建议 maxTokens: 6000，32K 大上下文可设 28000，4K 小模型则压至 3000。

显著优点

• 解决本地模型痛点：与云端 API 不同，MLX、llama.cpp、Ollama 常静默截断或返回乱码，此插件通过客户端估算提前介入，避免对话崩坏。
• 零依赖纯净架构：仅使用 Node.js 内置模块（fs、path、os、readline），无第三方依赖，彻底杜绝供应链攻击。
• 完全本地运行：无外部网络请求，数据不离开用户设备，隐私风险极低。
• 智能缓存机制：摘要结果以 Map 内存缓存（上限 100 条），避免重复调用 LLM 生成摘要，降低成本。
• 自动备份与授权：CLI 安装时主动询问用户同意，并自动备份原有 openclaw.json 配置，尊重用户控制权。

潜在局限

• 摘要质量依赖模型：若配置的 summaryModel 能力弱或不可用，将回退到截断式摘要，可能丢失关键信息。
• Token 估算非精确：默认按 4 字符/Token 估算，CJK 语言需调至 3，技术内容可能需 5，估算误差可能导致过早或延迟压缩。
• 会话级摘要：与 OpenClaw 内置压缩不同，本插件摘要不持久化到对话记录，刷新后需重新生成。
• 配置门槛：需用户根据模型上下文窗口手动调参，对新手有一定学习成本。

适合人群

• 使用 MLX、llama.cpp、Ollama 等本地推理框架的开发者与高级用户
• 对数据隐私敏感、不愿将对话上传云端的企业或个人
• 需要长对话连贯性、厌烦上下文截断导致「失忆」的 AI 助手重度用户

常规风险

• 文件系统操作：需读写 ~/.openclaw/ 下的配置与扩展目录，虽经路径限制与备份保护，但仍属敏感操作。
• LLM Runtime 调用：生成摘要时通过 OpenClaw 的 LLM Runtime 调用模型，若配置不当或模型服务异常，可能失败。
• 缓存隐私：摘要缓存在内存中，虽不持久化，但多用户共享同一进程时存在理论上的信息残留风险（单用户场景可忽略）。