headroom是一款AI Agent上下文压缩工具核心作用是大幅降低LLM对话的Token消耗适配Codex、Claude Code、Cursor等主流AI编程工具。该工具依赖终端执行核心命令同时支持对接Codex桌面应用并非纯图形化工具。完整安装步骤必须在终端操作headroom主流通过Python安装环境要求Python 3.10及以上版本打开系统终端Windows终端/PowerShell、Mac/Linux终端。执行完整版安装命令推荐包含全部功能pip install headroom-ai[all]若使用Node/TypeScript环境可执行npm install headroom-ai验证安装终端输入headroom --version输出版本号即代表安装成功。四大使用模式结合Codex场景工具提供4种接入方式全部以终端命令为基础可分别适配Codex终端版和桌面版模式一Agent Wrap模式适配Codex终端CLI专门用于一键包装Codex命令行客户端零额外配置headroom wrap codex # 执行后拉起Codex会话自动压缩上下文特点所有对话历史、代码上下文被自动压缩。查看统计使用headroom stats或headroom perf查看Token消耗及节省数据。模式二Proxy代理模式适配Codex桌面应用让Codex桌面端间接使用压缩能力终端启动本地代理服务默认8787端口headroom proxy --port 8787打开Codex桌面应用配置其请求代理指向http://localhost:8787。此后桌面端所有对话和上下文自动压缩无需修改代码。模式三代码集成模式开发者自定义集成在Python或TypeScript代码中直接调用压缩函数Python示例from headroom import compress compressed_messages compress(messages, model对应模型名称) # 传入Codex消息列表模式四MCP Server模式适配Claude Desktop等MCP协议客户端启动MCP服务以支持压缩能力headroom mcp install # 安装并启动MCP服务适用场景桌面端可直接调用压缩和检索功能全程依托后台终端运行。针对核心问题解答能否在Codex桌面应用端直接使用可以但不能脱离终端。Codex桌面端本身无内置图形化入口需先在终端启动proxy或mcp服务再配置桌面端对接本地服务。是否必须终端调用核心操作安装、启动代理、Wrap包装、服务部署必须在终端执行。日常使用分场景Codex终端版全程终端操作使用headroom wrap codex一步完成接入。Codex桌面版仅首次需在终端启动后台服务后续正常使用图形界面即可。补充实用命令与注意事项停止服务终端按下Ctrl C可关闭代理或Wrap会话。端口冲突若8787端口占用自定义端口执行headroom proxy --port 自定义端口号。跨端联动Codex终端会话可输入/app快速跳转至桌面端压缩配置同步生效。