Headroom插件生态指南：agent-hooks、openclaw与hermes插件开发入门

Headroom插件生态指南agent-hooks、openclaw与hermes插件开发入门【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroomHeadroom 是一个上下文压缩context compression项目在工具输出、日志、JSON 到达 LLM 之前先做压缩为编码 Agent 节省约 20% token对 JSON 内容可节省 60%–95%且答案质量不变。除了核心的代理proxy、库和 MCP 服务外Headroom 还自带一套插件生态——本文带你快速看懂agent-hooks、hermes、openclaw三个插件各自解决什么问题以及它们如何基于同一套压缩—缓存—取回CCR机制工作帮助你快速入门 Headroom 插件开发。一、先理解插件要解决的共同问题CCR 取回机制所有 Headroom 插件都围绕同一个核心机制Compress-Cache-RetrieveCCR压缩—缓存—取回。压缩代理把大体积的工具输出替换成轻量标记例如[1500 items compressed to 50. Retrieve more: hashabc123]或ccr:abc123缓存原始内容保存在代理的压缩存储中带 TTL默认 30 分钟取回Agent 通过headroom_retrieve工具按 hash 随时取回完整原文而不是靠猜或重跑命令。取回端点是代理的POST /v1/retrieve接口实现在 headroom/proxy/server.py 中。Claude Code 用户会自动获得这个 MCP 工具见 headroom/ccr/mcp_server.py而 Hermes、OpenClaw 等 Agent 需要各自注册工具——这正是三个插件分工的由来。二、agent-hooks 插件会话启动时自动确保 Headroom 就绪agent-hooks是三个插件中最轻量的一个面向 Claude Code 和 GitHub Copilot CLI只暴露启动钩子startup hooks。它的原理很简单在会话启动SessionStart和首次执行 Bash/PowerShellPreToolUse两个时机调用一条隐藏辅助命令headroom init hook ensure该命令会检查是否存在匹配的持久化headroom init部署没有就自动拉起。也就是说你不需要手动启动代理——只要 Agent 一启动Headroom 运行时就确保就绪。钩子定义在 plugins/headroom-agent-hooks/hooks/hooks.json 中每个钩子都有 15 秒超时保护避免阻塞 Agent 启动。更多说明见 plugins/headroom-agent-hooks/README.md。 适合人群已经在用headroom init部署了 Claude Code / Copilot 环境希望开机即压缩的新手用户。三、hermes 插件给 Hermes Agent 一个原生取回工具HermesNous Research 的 Agent把流量经过headroom proxy后大工具输出会被压缩成 CCR 标记。但 Hermes 注册的是自己的工具集没有取回工具时标记对模型来说就成了黑箱——模型要么白白重跑命令要么把ccr:abc123当成文件路径去cat。headroom_retrieve插件补齐了这个闭环声明为 Hermes 原生工具元数据见 plugins/hermes/headroom_retrieve/plugin.yaml容忍模型传入完整标记ccr:abc123,base64,4.5KB、ccr:abc123、hashabc123都会被规范化成纯 hash见 plugins/hermes/headroom_retrieve/init.py错误信息可操作hash 过期或代理不可达时直接告诉模型重跑原始命令而不是盲目重试。安装三步走详见 plugins/hermes/README.md把插件目录拷入~/.hermes/plugins/在~/.hermes/config.yaml的toolsets加入headroom并在plugins.enabled中列出headroom_retrieve注意该键一旦存在即为白名单需把你依赖的其他用户插件一并列出重启 Hermes 网关/TUI插件发现按进程缓存。一个关键配置Hermes 的工具名不在 Headroom 内置的受保护清单里强烈建议在代理端设置HEADROOM_EXCLUDE_TOOLSread_file,headroom_retrieve否则取回的原文会在下一次请求中再次被压缩陷入标记→取回→标记的死循环。四、openclaw 插件最完整的上下文压缩引擎openclaw插件是三者中功能最重的它不仅注册了取回工具还注册了完整的ContextEngine上下文引擎在 OpenClaw 每次组装模型上下文时自动压缩工具输出与大消息JSON 数组统计式筛选保留异常项、错误、边界元素代码基于 tree-sitter 的 AST 感知压缩日志模式去重保留错误和边界文本ML 式 token 压缩。全部压缩零 LLM 调用token 节省 70%–90%。核心实现分布在上下文引擎plugins/openclaw/src/engine.ts插件注册入口注册 contextEngine 与headroom_retrieve工具plugins/openclaw/src/plugin/index.tsCCR 取回工具plugins/openclaw/src/tools/headroom-retrieve.ts一键安装headroom wrap openclaw它会自动选择contextEngine槽位并注册压缩引擎。插件支持按需自动拉起本地代理启动顺序PATH → 本地 npm bin → 全局 npm → Python 模块也可通过proxyUrl指向远程代理远程为仅连接模式探测失败快速报错不会拉子进程。值得关注的几个配置项完整表格见 plugins/openclaw/README.md选项默认作用proxyUrl自动探测指向任意可达的 Headroom 代理autoStartfalse本地代理可选自动启动生产环境建议交给 systemdrequestTimeoutMs30000单次压缩调用超时超时回退到未压缩原文circuitBreakerThreshold3连续出错 3 次熔断全部请求旁路代理gatewayProviderIds[]把 codex/claude/copilot/gemini 等上游流量也路由进代理最后一项是进阶玩法插件会在内存中改写 OpenClaw 内置openai-codex提供方的 base URL让 Codex 流量也穿过 Headroom这样/stats能观测到真实的上游请求与缓存活动。该路由可逆、不落盘——禁用插件即恢复原样。五、Token 节省效果与入门路线压缩带来的节省可以在仪表盘与统计接口中直观看到给新手的入门建议先用pip install headroom-ai[proxy]装好核心并启动headroom proxy默认127.0.0.1:8787按 Agent 选型Claude Code / Copilot CLI →agent-hooksHermes →headroom_retrieveOpenClaw →openclaw插件headroom wrap openclaw最省事若要从头开发自己的插件可以直接读三个现成样本最简钩子看 plugins/headroom-agent-hooks/单工具插件看 plugins/hermes/headroom_retrieve/完整引擎插件看 plugins/openclaw/src/需要本地实验时先克隆仓库git clone https://gitcode.com/GitHub_Trending/head/headroom三个插件、一套 CCR 机制——这就是 Headroom 插件生态的全部骨架让任何 Agent 都能在零 LLM 调用压缩后随时按 hash 拿回完整的原始内容。【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考