节省token方案

headroom是一款AI Agent上下文压缩工具，核心作用是大幅降低LLM对话的Token消耗，适配Codex、Claude Code、Cursor等主流AI编程工具。该工具依赖终端执行核心命令，同时支持对接Codex桌面应用，并非纯图形化工具。

完整安装步骤（必须在终端操作）

headroom主流通过Python安装，环境要求Python 3.10及以上版本：

1. 打开系统终端（Windows终端/PowerShell、Mac/Linux终端）。
2. 执行完整版安装命令（推荐，包含全部功能）：

   pip install "headroom-ai[all]"

3. 若使用Node/TypeScript环境，可执行：

   npm install headroom-ai

4. 验证安装：终端输入headroom --version，输出版本号即代表安装成功。

四大使用模式（结合Codex场景）

工具提供4种接入方式，全部以终端命令为基础，可分别适配Codex终端版和桌面版：

模式一：Agent Wrap模式（适配Codex终端CLI）

专门用于一键包装Codex命令行客户端，零额外配置：

headroom wrap codex # 执行后拉起Codex会话，自动压缩上下文

• 特点：所有对话历史、代码上下文被自动压缩。
• 查看统计：使用headroom stats或headroom perf查看Token消耗及节省数据。

模式二：Proxy代理模式（适配Codex桌面应用）

让Codex桌面端间接使用压缩能力：

1. 终端启动本地代理服务（默认8787端口）：

   headroom proxy --port 8787

2. 打开Codex桌面应用，配置其请求代理指向http://localhost:8787。
3. 此后桌面端所有对话和上下文自动压缩，无需修改代码。

模式三：代码集成模式（开发者自定义集成）

在Python或TypeScript代码中直接调用压缩函数：

• Python示例：

  from headroom import compress compressed_messages = compress(messages, model="对应模型名称") # 传入Codex消息列表

模式四：MCP Server模式（适配Claude Desktop等MCP协议客户端）

启动MCP服务以支持压缩能力：

headroom mcp install # 安装并启动MCP服务

• 适用场景：桌面端可直接调用压缩和检索功能，全程依托后台终端运行。

针对核心问题解答

1. 能否在Codex桌面应用端直接使用？
   可以，但不能脱离终端。Codex桌面端本身无内置图形化入口，需先在终端启动proxy或mcp服务，再配置桌面端对接本地服务。

2. 是否必须终端调用？
   核心操作（安装、启动代理、Wrap包装、服务部署）必须在终端执行。日常使用分场景：

   • Codex终端版：全程终端操作，使用headroom wrap codex一步完成接入。
   • Codex桌面版：仅首次需在终端启动后台服务，后续正常使用图形界面即可。

补充实用命令与注意事项

1. 停止服务：终端按下Ctrl + C可关闭代理或Wrap会话。
2. 端口冲突：若8787端口占用，自定义端口执行headroom proxy --port 自定义端口号。
3. 跨端联动：Codex终端会话可输入/app快速跳转至桌面端，压缩配置同步生效。