Codex 桌面端接入 Headroom 压缩代理完整教程

console.log('npc')2026-06-16 8:28

以下是针对 Headroom 工具的整理与优化说明：

核心功能

Headroom 是一个本地运行的 AI 上下文压缩工具，能在数据输入大语言模型（LLM）前智能缩减 Token 数量，节省 60-95% 的 Token 消耗，同时保持回答质量。适用于代码搜索、事故调试等场景。

安装方法

环境要求 Python 3.7 及以上版本，支持 Windows/Linux/macOS。

安装命令 完整版安装（推荐）：

bash 复制代码

pip install "headroom-ai[proxy,ml,code,mcp]==0.20.15"

替代方案（使用 uv 加速安装）：

bash 复制代码

uv pip install "headroom-ai[proxy,ml,code,mcp]==0.20.15"

Windows 特殊处理 若遇路径过长错误，分步安装：

bash 复制代码

pip install "headroom-ai==0.20.15" --no-deps
pip install click rich httpx openai uvicorn fastapi websockets watchdog pyyaml typer

设置环境变量绕过 Rust 限制：

powershell 复制代码

$env:HEADROOM_REQUIRE_RUST_CORE = "false"

配置与使用

启动代理服务

bash 复制代码

headroom proxy --port 8787 --openai-api-url https://api.feng.cx/v1

修改 Codex 配置 编辑 ~/.codex/config.toml：

toml 复制代码

[model_providers.custom]
base_url = "http://localhost:8787/v1"  # 指向本地代理

验证连接 执行以下命令检查代理状态：

bash 复制代码

curl http://localhost:8787/stats

关注 api_requests 和 avg_compression_pct 字段确认压缩效果。

桌面端集成

修改 config.toml 后，Codex 桌面端自动继承配置。需确保启动时代理服务已运行。

效率提升脚本

创建批处理文件 start_headroom_codex.bat：

batch 复制代码

@echo off
set HEADROOM_REQUIRE_RUST_CORE=false
start "Proxy" /MIN cmd /c "headroom proxy --port 8787 --openai-api-url https://api.feng.cx/v1"
codex -c model_providers.custom.base_url="http://localhost:8787/v1"
pause

故障排查

代理未启动：检查端口占用或环境变量设置。
Codex 报错 ：添加 --skip-git-repo-check 参数跳过目录验证。
恢复直连 ：将 base_url 改回原始 API 地址。

注意事项

代理模式仅本地运行，API Key 不会外传。
平均压缩率可通过 /stats 接口实时监控。