SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场headroom

headroom

智能体与模型

查看项目

更新于 10-30 16:18

技能介绍

用途

Headroom 用于节省 AI 代理的上下文窗口：它压缩大体积的工具输出，并在之后按需检索原始内容。上游项目地址为 https://github.com/headroomlabs-ai/headroom。

主要能力

  • 按需上下文压缩：通过 MCP 工具 headroom_compress 等压缩大段工具输出。
  • 按哈希检索：压缩后保留返回的哈希，之后用 headroom_retrieve 取回原文。
  • 会话统计：提供会话统计相关工具（如 headroom_stats）。
  • 多宿主支持：与任何 MCP 宿主（Claude、Cursor、Codex、Grok 等）配合使用，前提是服务器已注册；若注册失败，应说明并继续在不使用 Headroom 的情况下工作。

使用方式

工具解析顺序：

  1. 若会话中已有 MCP 工具（如 headroom_compress、headroom_retrieve 等），直接使用；
  2. 否则检查 CLI：headroom --help 或 $env:HEADROOM_CMD；
  3. 否则建议安装。

安装建议：

pip install "headroom-ai[mcp]"     # 仅工具
pip install "headroom-ai[proxy]"   # 代理 + 工具
headroom mcp install               # 在支持的环境（如 Claude Code）中注册

适用场景

  • 在推理前处理巨型日志、grep 结果、JSON 转储、崩溃堆栈；
  • 需要之后回看原文时，保留返回的哈希并用 headroom_retrieve 检索。

限制与注意事项

  • 不适用于极小片段；不用于替代特定领域技能（例如 Skyrim 领域技能）。
  • MCP 不可用时不要编造压缩结果，应改为谨慎总结。
  • Grok 相关：Grok 仅支持 MCP 模式，不要包裹 Grok 推理。除用户已有 XAI_API_KEY 外，不要运行 headroom wrap grok，也不要设置 GROK_MODELS_BASE_URL。Headroom 的 Grok 代理转发至 https://api.x.ai，并使用 XAI_API_KEY 认证；而 Grok 订阅／OIDC 登录（~/.grok/auth.json 中 auth_mode=oidc）使用的是 https://cli-chat-proxy.grok.com/v1，Headroom 没有对应代码路径，包裹这类账号会导致模型目录拉取失败（模型选择器显示 unknown、grok-4.5 不可选）以及 401 错误。这属于认证形态不匹配，没有任何开关能让会话登录方式的包裹工作。

按认证模式决策：auth_mode=oidc（订阅）且无 XAI_API_KEY 时仅使用 MCP 工具；存在 XAI_API_KEY 时可用 MCP 工具并可选包裹推理。

正确的 Grok 配置命令：

.\TOOLS\Ensure-Headroom-Grok.ps1            # MCP 注册，感知认证（默认）
.\TOOLS\Ensure-Headroom-Grok.ps1 -CheckOnly # 只报告，不做更改
.\TOOLS\Ensure-Headroom-Grok.ps1 -Repair    # 撤销破坏 Grok 的 v5.0 包裹
.\TOOLS\Ensure-Headroom-Grok.ps1 -Wrap      # 主动选择；无 XAI_API_KEY 时拒绝

在 ~/.grok/config.toml 中加入 [mcp_servers.headroom] 可让 Grok 获得 headroom_compress / headroom_retrieve / headroom_stats。这是代理有意识调用的按需压缩，不是自动流量压缩；对订阅账号这是唯一可用模式。

若 Grok 显示 unknown 模型或无法使用 grok-4.5，按顺序排查：GROK_MODELS_BASE_URL / GROK_MODEL_GROK_BUILD_BASE_URL 被设为 127.0.0.1（包裹生效，移除）；PowerShell 配置文件中调用 headroom wrap grok 的 grok 函数（重命名或删除）；~/.headroom/deploy/default/manifest.json 中含 grok / grok_build 目标（执行 headroom install remove --profile default）；~/.grok/models_cache.json 的 origin 指向 127.0.0.1（删除以便重新拉取）。之后启动新 shell 运行 grok。

验证：执行 headroom install status。对订阅账号，正确状态为：无 GROK_* base-url 环境变量、无 grok/grok_build 部署目标、~/.grok/config.toml 中存在 [mcp_servers.headroom]、~/.grok/models_cache.json 的 origin 为 https://cli-chat-proxy.grok.com/v1/models。